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 § 分页	延续令牌模式
Agent 工作流	SKILL.md § Agentic Workflow
示例	SKILL.md § 示例
注意事项和故障排除	SKILL.md § 注意事项和故障排除

---

必须／优先／避免

必须执行

• 先进行身份验证 — 参见 COMMON-CORE.md § 身份验证与令牌获取 和 COMMON-CLI.md § 身份验证示例。Catalog Search API 需要 Catalog.Read.All 作用域。
• 将 JSON 请求正文写入临时文件 — 避免筛选字符串的 shell 引号问题。
• 消除歧义 — 如果有多个匹配结果，请提供显示名称、类型和工作区名称，并询问用户确认。

优先执行

• 优先使用 Catalog Search，而非列出后筛选 — 只需一次跨工作区调用，无需先解析工作区。
• 使用类型筛选器 — 使用 "filter": "Type eq 'Lakehouse'" 缩小结果范围，减少干扰。
• 使用空搜索和类型筛选器 — 列出所有工作区中的某类型项。
• 使用 jq 从响应中提取 ID — 对嵌套的 hierarchy.workspace，比 JMESPath 更简洁。

避免

• 搜索工作区 — Catalog Search API 返回的是项，而不是工作区。请改用 GET /v1/workspaces（参见 COMMON-CLI.md § 按名称解析工作区属性）。
• 在已知工作区／项后查询源数据 — 应改用特定工作负载的使用技能（sqldw-cli、spark-cli、eventhouse-cli 或 fabriciq），而非 Catalog Search。
• 臆造筛选语法 — 仅支持 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

---

筛选示例

目标	筛选器
仅湖仓	Type eq 'Lakehouse'
报表或语义模型	Type eq 'Report' or Type eq 'SemanticModel'
排除笔记本	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。

---

Agent 工作流

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。
找不到新项目	Catalog 索引传播延迟	索引延迟不固定，且尚未接近实时 — 通常需要几分钟，但无法保证。刚创建的项目可能尚未出现在搜索结果中；请改用 GET /v1/workspaces/{id}/items 验证项目是否存在。
结果过多	搜索文本过于宽泛	添加类型筛选条件，或使用更具体的搜索文本。