search-consumption-cli

テレメトリ — 必須です。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: search-consumption-cli を付けてください（az rest の場合は --headers "x-ms-fabric-skill=search-consumption-cli"）。 すべての LRO ポーリング、fabric_lro、再試行にも適用されます。スニペットでは省略されていますが、必ず追加してください。

重要な注意事項

1. Catalog Search API で検索できるのはアイテムであり、ワークスペースではありません。名前でワークスペースを検索するには、GET /v1/workspaces を使用してください（COMMON-CLI.md § 名前からワークスペースのプロパティを解決するを参照）。
2. 検索テキストは、アイテムの表示名、説明、ワークスペース名と照合されます。
3. Dataflow (Gen1) と Dataflow (Gen2) はサポートされていません。

Catalog Search — CLI スキル

前提知識

• COMMON-CORE.md — Fabric REST API のパターン、認証
• COMMON-CLI.md — CLI の実装（az、curl、jq）

目次

タスク	リファレンス	備考
アイテムを検索する	SKILL.md § アイテムを検索する	名前、説明、またはワークスペース名で検索
特定の種類のすべてのアイテムを一覧表示する	SKILL.md § 特定の種類のすべてのアイテムを一覧表示する	空の検索文字列 + 種類フィルター
ページネーション	SKILL.md § ページネーション	継続トークンのパターン
エージェント型ワークフロー	SKILL.md § エージェント型ワークフロー
例	SKILL.md § 例
注意点とトラブルシューティング	SKILL.md § 注意点とトラブルシューティング

---

必須／推奨／回避

必ず行うこと

• 最初に認証する — COMMON-CORE.md § 認証とトークンの取得およびCOMMON-CLI.md § 認証のレシピを参照してください。Catalog Search API には Catalog.Read.All スコープが必要です。
• JSON 本文を一時ファイルに書き込む — フィルター文字列のシェルでの引用符の問題を回避できます。
• 結果を識別する — 複数の結果が一致する場合は、表示名、種類、ワークスペース名を提示して、ユーザーに確認を求めてください。

推奨事項

• 一覧取得後のフィルター処理ではなく Catalog Search を使う — ワークスペースをまたいだ単一の呼び出しで済み、事前にワークスペースを解決する必要がありません。
• 種類フィルターを使う — "filter": "Type eq 'Lakehouse'" で結果を絞り込み、不要な結果を減らします。
• 種類フィルターと空の検索文字列を使う — ワークスペースをまたいで特定の種類のアイテムをすべて一覧表示できます。
• 応答から ID を抽出するには jq を使う — 入れ子になった hierarchy.workspace の場合、JMESPath より簡潔です。

避けること

• ワークスペースを検索する — Catalog Search API が返すのはアイテムであり、ワークスペースではありません。代わりに GET /v1/workspaces を使用してください（COMMON-CLI.md § 名前からワークスペースのプロパティを解決するを参照）。
• ワークスペース／アイテムが判明した後にソースデータをクエリする — Catalog Search ではなく、ワークロード固有の利用スキル（sqldw-cli、spark-cli、eventhouse-cli、または fabriciq）に振り分けてください。
• フィルター構文を独自に作る — サポートされているのは eq、ne、or、括弧のみです。
• すべてのアイテム種類がサポートされていると想定する — Dataflow (Gen1) と Dataflow (Gen2) はまだ返されません。

---

アイテムを検索する

cat > /tmp/body.json << 'EOF'
{"search": "SalesLakehouse", "filter": "Type eq 'Lakehouse'", "pageSize": 10}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

検索テキストは、アイテムの表示名、説明、ワークスペース名と照合されます。種類のフィルターは任意です。応答には、一致する各アイテムの id、type、displayName、description、hierarchy.workspace（id と displayName を含む）が含まれます。

アイテム ID とワークスペース ID を抽出する

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[0].{itemId:id, workspaceId:hierarchy.workspace.id, name:displayName}" \
  --output json

---

フィルターの例

目的	フィルター
Lakehouse のみ	Type eq 'Lakehouse'
Report または SemanticModel	Type eq 'Report' or Type eq 'SemanticModel'
Notebook を除外	Type ne 'Notebook'

サポートされているアイテム種類の全一覧については、Catalog Search API リファレンスを参照してください。

---

特定の種類のすべてのアイテムを一覧表示する

種類フィルターを指定して、空の検索文字列を使用します（pageSize の最大値は 1000 です）。

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 100}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

---

ページネーション

レスポンスに null 以外の continuationToken が含まれている場合は、次のリクエストで渡します。

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 100, "continuationToken": "<token>"}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

continuationToken が null になるまで続けます。

---

エージェント型ワークフロー

1. 質問 — ユーザーがアイテム名、種類、または説明のキーワードを指定します。
2. 検索 — ユーザーの入力と任意の種類フィルターを使って、Catalog Search を呼び出します。
3. 曖昧さの解消 — 一致する項目が複数ある場合は、結果（名前、種類、ワークスペース）を提示し、ユーザーに選択を求めます。
4. 返却 — 検索結果を返し、後続処理で使用するアイテムの id と hierarchy.workspace.id を含めます。

---

例

特定のレポートを検索する

cat > /tmp/body.json << 'EOF'
{"search": "Monthly Sales Revenue", "filter": "Type eq 'Report'", "pageSize": 10}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[].{name:displayName, type:type, workspace:hierarchy.workspace.displayName}" \
  --output table

ワークスペース全体からすべてのセマンティックモデルを一覧表示する

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'SemanticModel'", "pageSize": 1000}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

検索結果をファイルに保存する

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 1000}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[].{name:displayName, type:type, workspace:hierarchy.workspace.displayName, id:id}" \
  --output json > /tmp/search_results.json

---

注意点とトラブルシューティング

症状	原因	対処法
401 Unauthorized	トークンのオーディエンスが正しくない、またはセッションの有効期限切れ	--resource "https://api.fabric.microsoft.com" を確認します。az login を実行します。
InvalidPageSize	pageSize が 1～1000 の範囲外	1～1000 の値を指定します。
InvalidFilter	フィルター構文が正しくない	eq、ne、or、および括弧のみ使用できます。eq と and、または ne と or を組み合わせないでください。同じフィルター内で eq と ne を組み合わせないでください。
TypeNotFound	フィルター内のアイテムの種類を認識できない	スペルを確認します（大文字と小文字は区別されます）。有効な種類についてはAPI リファレンスを参照してください。
FilterTooManyValues	フィルター内の値が 500 個を超えている	フィルター内の種類の値の数を減らします。
InvalidRequest	リクエスト本文がない	--body が有効な JSON ファイルを指していることを確認します。
既知のアイテムの検索結果が空	アイテムの種類がサポートされていない	Dataflow Gen1/Gen2 は対象外です。代わりに GET /v1/workspaces/{id}/items を使用します。
新しいアイテムが見つからない	カタログのインデックス反映に遅延がある	インデックス作成の遅延は一定ではなく、まだリアルタイムに近い状態ではありません。通常は数分ですが、保証はありません。作成直後のアイテムはまだ検索結果に表示されない場合があります。代わりに GET /v1/workspaces/{id}/items で存在を確認してください。
結果が多すぎる	検索テキストの範囲が広すぎる	種類フィルターを追加するか、より具体的な検索テキストを使用します。