powerbi-consumption-cli

更新检查 — 每个会话仅执行一次（必需） 首次在会话中使用此技能时，继续操作前请先运行 check-updates 技能。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能。
• Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程 package.json 版本。
• 如果本会话早些时候已完成检查，则跳过。

重要说明

1. 若要通过工作区名称查找工作区详情（包括其 ID）：先列出所有工作区，然后使用 JMESPath 进行筛选
2. 若要通过工作区 ID、项目类型和项目名称查找项目详情（包括其 ID）：先列出该工作区中该类型的所有项目，然后使用 JMESPath 进行筛选

Power BI 语义模型使用 — CLI 技能

目录

任务	参考	说明
在 Fabric 中查找工作区和项目	COMMON-CLI.md § 在 Fabric 中查找工作区和项目	必读 — 请先阅读链接内容 [用于按名称查找工作区 ID，或按名称、项目类型和工作区 ID 查找项目 ID]
Fabric 拓扑和关键概念	COMMON-CORE.md § Fabric 拓扑和关键概念	层级结构；在 Fabric 中查找内容
环境 URL	COMMON-CORE.md § 环境 URL	生产环境（公有云）
身份验证和令牌获取	COMMON-CORE.md § 身份验证和令牌获取	受众错误会导致 401；涵盖令牌受众、委托权限与应用权限、OAuth 流程、身份类型和 Entra 应用注册
核心控制平面 REST API	COMMON-CORE.md § 核心控制平面 REST API	包括工作区/项目 CRUD、按名称解析、分页、LRO 轮询和速率限制模式
OneLake 数据访问	COMMON-CORE.md § OneLake 数据访问	需要 storage.azure.com 令牌，而非 Fabric 令牌；涵盖 URL 结构、与 ADLS Gen2 的一致性以及快捷方式
作业执行	COMMON-CORE.md § 作业执行	运行按需作业；获取/取消作业
容量管理	COMMON-CORE.md § 容量管理	列出容量；将工作区分配给容量
注意事项、最佳实践和故障排除	COMMON-CORE.md § 注意事项、最佳实践和故障排除	常见错误；最佳实践
工具选择依据	COMMON-CLI.md § 工具选择依据
身份验证操作指南	COMMON-CLI.md § 身份验证操作指南	az login 流程、环境检测、令牌获取和调试
通过 az rest 调用 Fabric 控制平面 API	COMMON-CLI.md § 通过 az rest 调用 Fabric 控制平面 API	始终传入 --resource；包括工作区/项目操作、分页和 LRO 模式
通过 curl 访问 OneLake 数据	COMMON-CLI.md § 通过 curl 访问 OneLake 数据	使用 curl，不要使用 az rest（令牌受众不同）；列出/读取/上传/删除文件以及创建目录
SQL / TDS 数据平面访问	COMMON-CLI.md § SQL / TDS 数据平面访问	使用 sqlcmd (Go) 连接、查询、导出 CSV、服务主体身份验证以及发现连接参数
作业执行（CLI）	COMMON-CLI.md § 作业执行（CLI）	运行笔记本/管道、刷新语义模型、检查/取消作业
OneLake 快捷方式	COMMON-CLI.md § OneLake 快捷方式	创建快捷方式；列出快捷方式；删除快捷方式
容量管理（CLI）	COMMON-CLI.md § 容量管理（CLI）	列出容量；将工作区分配给容量
组合操作指南	COMMON-CLI.md § 组合操作指南	端到端的工作区→湖屋→文件、SQL 终结点→查询和笔记本执行操作指南
注意事项和故障排除（CLI 专用）	COMMON-CLI.md § 注意事项和故障排除（CLI 专用）
快速参考	COMMON-CLI.md § 快速参考	az rest 模板；令牌受众 ↔ CLI 工具矩阵
先决条件	SKILL.md § 先决条件
必须/优先/避免	SKILL.md § 必须/优先/避免	只读语义模型用法的防护规则。必须执行；优先采用；避免
元数据发现	SKILL.md § 元数据发现	INFO.VIEW.* 和 INFO.* 函数。
推荐的发现顺序	SKILL.md § 推荐的发现顺序	元数据探索的首选顺序
常用 INFO 函数	SKILL.md § 常用 INFO 函数	用于初步发现的高频函数列表
完整 INFO 函数目录（动态）	discovery-queries.md § 完整 INFO 函数目录（动态）
元数据对象 → INFO 函数映射	SKILL.md § 元数据对象 → INFO 函数映射	内嵌的映射，用于以对象为中心的发现
查询执行	SKILL.md § 查询执行	ExecuteQuery 的用法形式
故障排除	SKILL.md § 故障排除	解决常见的执行和元数据问题
示例	SKILL.md § 示例	元数据查询示例；数据查询示例
范围估算查询	discovery-queries.md § 范围估算查询
INFO 输出列	discovery-queries.md § INFO 输出列	INFO.VIEW.（初步元数据发现首选）；关键 INFO.（深层元数据/诊断）
缩小结果范围（投影 + 筛选）	discovery-queries.md § 缩小结果范围（投影 + 筛选）
深层元数据查询	discovery-queries.md § 深层元数据查询
依赖项发现	discovery-queries.md § 依赖项发现	DAX 查询的依赖项行集；限定到度量值的依赖项行；反向依赖项（引用某度量值的内容）

前提条件

• COMMON-CORE.md — Fabric 概念、身份验证和控制平面 API 背景信息。
• COMMON-CLI.md — 面向 CLI 的发现方式及令牌/受众模式。

必须/优先/避免

必须执行

• 将此技能限制为只读：仅进行元数据发现和分析型 DAX 查询。
• 将 DAX 数据查询和 INFO.VIEW.* 视为所有具有语义模型读取权限的用户均可使用；假设其他 INFO.* 函数可能需要更高权限。
• 动态解析工作区和语义模型项的标识，不要对 ID 进行硬编码。
• 在编写数据查询前，使用 DAX INFO.VIEW.* / INFO.* 发现元数据。

优先执行

• 尽早验证语义模型范围（artifactId），再迭代优化查询。
• 逐步发现语义模型架构：使用经过筛选和投影的 INFO.VIEW.* / INFO.* 调用（例如，SELECTCOLUMNS + FILTER），仅获取与当前任务直接相关的信息，而不要一开始就检索完整架构。请参阅 discovery-queries.md § 缩小结果范围（投影 + 筛选）。
• 保持指南与提供方无关，以降低工具端点迁移风险。

避免

• 在此技能中执行模型更改操作。

推荐的发现顺序

1. 运行 discovery-queries.md § 范围估算查询，在深入发现前估算元数据范围（表、列、度量值和关系的数量）。
2. 从 INFO.VIEW.TABLES() 开始，快速盘点表。
3. 扩展到 INFO.VIEW.COLUMNS() 和 INFO.VIEW.MEASURES()，获取语义详细信息。
4. 使用 INFO.VIEW.RELATIONSHIPS() 验证联接和筛选行为。
5. 如需更深入的模式，请使用 discovery-queries.md 中的完整查询目录。

常用 INFO 函数

• INFO.VIEW.TABLES
• INFO.VIEW.MEASURES
• INFO.VIEW.COLUMNS
• INFO.VIEW.RELATIONSHIPS
• INFO.PARTITIONS
• INFO.MODEL
• INFO.STORAGETABLECOLUMNSEGMENTS
• INFO.DEPENDENCIES
• INFO.EXPRESSIONS
• INFO.ROLES
• INFO.STORAGETABLECOLUMNS
• INFO.CALCULATIONGROUPS
• INFO.CALCULATIONITEMS
• INFO.CULTURES
• INFO.OBJECTTRANSLATIONS
• INFO.USERDEFINEDFUNCTIONS
• INFO.REFRESHPOLICIES
• INFO.ATTRIBUTEHIERARCHYSTORAGES
• INFO.COLUMNPARTITIONSTORAGES
• INFO.COLUMNSTORAGES
• INFO.DICTIONARYSTORAGES
• INFO.HIERARCHYSTORAGES
• INFO.PARTITIONSTORAGES
• INFO.RELATIONSHIPINDEXSTORAGES
• INFO.RELATIONSHIPSTORAGES
• INFO.SEGMENTMAPSTORAGES
• INFO.SEGMENTSTORAGES
• INFO.STORAGEFOLDERS
• INFO.STORAGEFILES
• INFO.TABLESTORAGES
• INFO.GENERALSEGMENTMAPSEGMENTMETADATASTORAGES
• INFO.DELTATABLEMETADATASTORAGES
• INFO.PARQUETFILESTORAGES
• INFO.STORAGETABLES

元数据对象 → INFO 函数映射

元数据对象	主要 INFO 函数
模型	INFO.MODEL
表	INFO.VIEW.TABLES
列	INFO.VIEW.COLUMNS、INFO.GROUPBYCOLUMNS、INFO.RELATEDCOLUMNDETAILS
度量值	INFO.VIEW.MEASURES、INFO.FORMATSTRINGDEFINITIONS、INFO.DETAILROWSDEFINITIONS
关系	INFO.VIEW.RELATIONSHIPS
分区	INFO.PARTITIONS、INFO.EXPRESSIONS、INFO.QUERYGROUPS、INFO.REFRESHPOLICIES、INFO.DATACOVERAGEDEFINITIONS
安全角色和权限	INFO.ROLES、INFO.TABLEPERMISSIONS、INFO.COLUMNPERMISSIONS
层次结构	INFO.HIERARCHIES、INFO.LEVELS、INFO.ATTRIBUTEHIERARCHIES、INFO.VARIATIONS
计算组/项	INFO.CALCULATIONGROUPS、INFO.CALCULATIONITEMS、INFO.CALCULATIONEXPRESSIONS
透视	INFO.PERSPECTIVES、INFO.PERSPECTIVETABLES、INFO.PERSPECTIVECOLUMNS、INFO.PERSPECTIVEHIERARCHIES、INFO.PERSPECTIVEMEASURES
日历	INFO.CALENDARS、INFO.CALENDARCOLUMNGROUPS、INFO.CALENDARCOLUMNREFERENCES
区域性	INFO.CULTURES
对象翻译	INFO.OBJECTTRANSLATIONS
函数	INFO.USERDEFINEDFUNCTIONS
依赖项/血缘	INFO.DEPENDENCIES、INFO.CHANGEDPROPERTIES、INFO.EXCLUDEDARTIFACTS
存储内部信息/大小	INFO.STORAGEFOLDERS、INFO.STORAGEFILES、INFO.TABLESTORAGES、INFO.COLUMNSTORAGES、INFO.PARTITIONSTORAGES、INFO.SEGMENTMAPSTORAGES、INFO.DICTIONARYSTORAGES、INFO.COLUMNPARTITIONSTORAGES、INFO.SEGMENTSTORAGES、INFO.RELATIONSHIPSTORAGES、INFO.RELATIONSHIPINDEXSTORAGES、INFO.ATTRIBUTEHIERARCHYSTORAGES、INFO.HIERARCHYSTORAGES、INFO.GENERALSEGMENTMAPSEGMENTMETADATASTORAGES、INFO.DELTATABLEMETADATASTORAGES、INFO.PARQUETFILESTORAGES、INFO.STORAGETABLES、INFO.STORAGETABLECOLUMNS、INFO.STORAGETABLECOLUMNSEGMENTS

查询执行

使用单一的 ExecuteQuery 能力，包含以下负载概念：

• artifactId：目标语义模型标识符。
• daxQuery：直接 DAX 查询文本。

临时实现说明：当前查询集成预计会在发布前替换为公开的 HTTP 端点，以提供 ExecuteQuery。

故障排除

• MCP 服务中无法使用 ExecuteQuery 能力
  • 问题： 活动工具列表中没有 ExecuteQuery，因此无法开始执行查询。
  • 原因： Fabric MCP 服务未注册、未加载，或者当前客户端会话的工具元数据已过时。
  • 解决方法： 检查活动 MCP 服务／工具清单，并确认已公开 ExecuteQuery。
• 高级 INFO 函数返回权限错误
  • 问题： 对 INFO.* 的查询因授权或权限相关错误而失败。
  • 原因： 许多 INFO.* 函数需要超出标准读取权限的语义模型高级权限。
  • 解决方法： 从面向读取的发现函数 INFO.VIEW.* 开始。
• 元数据输出量过大，不利于聚焦分析
  • 问题： 返回完整元数据行集会引入过多属性，挤占工作上下文。
  • 原因： 不受限制的 INFO.VIEW.* 和 INFO.* 查询会返回范围广泛的对象／属性信息，而这些信息通常与当前任务无关。
  • 解决方法： 使用 discovery-queries.md § Scope Estimation Queries 中的范围估算查询来估算范围并检查输出架构，然后按照 discovery-queries.md § Narrowing Results (Projection + Filtering) 中的示例，通过投影和筛选缩小结果范围。
• 不要使用 INFO DAX 函数检索角色成员身份
  • 问题： INFO.ROLEMEMBERSHIPS() 返回空结果或不完整结果。
  • 原因： 角色成员是在部署后于服务级别（Entra ID）分配的，而非定义在模型中，因此 DAX INFO 函数无法可靠地获取这些信息。
  • 解决方法： 改用 Power BI REST API。请参阅 powerbi-authoring-cli § Security Role Memberships。

示例

完整的查询目录（包括依赖模式）请参阅 discovery-queries.md。

元数据查询示例

EVALUATE
INFO.VIEW.TABLES()
ORDER BY [Name]

数据查询示例

DEFINE
MEASURE 'Sales'[Total Sales] = SUM('Sales'[Amount])
EVALUATE
SUMMARIZECOLUMNS(
    'Customer'[Customer Name],
    "Total Sales", [Total Sales]
)
ORDER BY [Total Sales] DESC