power-bi

Power BI 开发技能

使用 PBIP（Power BI 项目）格式进行端到端的 Power BI 项目开发。PBIP 是一种适合 Git 管理、基于文本的格式，用于对 Power BI 解决方案进行版本控制。

此技能适用场景

• 创建或修改 Power BI 语义模型（TMDL 文件）
• 编写或调试 Power Query（M）表达式（.pq 文件）
• 编写 DAX 度量值
• 设计星型架构数据模型
• 将报表发布到 Power BI Service
• 配置计划刷新和数据网关
• 排查 PBI 连接器问题（尤其是 Azure Cost Management / EA）
• 使用任何 .tmdl、.pq、.pbip、.pbir、.pbism 文件

PBIP 项目结构

ProjectName/
├── ProjectName.pbip                    # Open this in PBI Desktop
├── ProjectName.Report/
│   ├── report.json                     # Report visuals (edit in PBI Desktop)
│   ├── definition.pbir                 # Report definition pointer
│   └── StaticResources/
│       └── SharedResources/BaseThemes/ # Custom themes (.json)
├── ProjectName.SemanticModel/
│   ├── definition.pbism                # Semantic model pointer
│   └── definition/
│       ├── model.tmdl                  # Model-level settings
│       ├── tables/                     # Table definitions + measures (.tmdl)
│       ├── expressions/                # Power Query scripts (.pq)
│       └── relationships.tmdl          # Star schema joins
├── scripts/                            # Python automation (optional)
└── docs/                               # Documentation

工作流路由

工作流	触发条件	文件
NewProject	“create PBI project”、“scaffold PBIP”、“new Power BI project”	workflows/new-project.md
AddTable	“add table”、“new fact table”、“new dimension”、“add PQ source”	workflows/add-table.md
AddMeasure	“add DAX measure”、“create measure”、“new KPI”	workflows/add-measure.md
DataModeling	“star schema”、“add relationship”、“data model design”	workflows/data-modeling.md
PublishRefresh	“publish to service”、“scheduled refresh”、“data gateway”	workflows/publish-refresh.md
ConnectorAuth	“connector auth”、“EA connector”、“cost management connector”、“PBI sign in failed”	workflows/connector-auth.md
Troubleshooting	“PBI error”、“refresh failed”、“data not loading”、“type error”	workflows/troubleshooting.md

参考文件

按需阅读这些文件，不要一次性全部加载：

参考资料	阅读时机	文件
TMDL 语法	编写或编辑 .tmdl 文件	references/tmdl-syntax.md
Power Query 模式	编写或编辑 .pq 文件	references/power-query-patterns.md
DAX 模式	编写 DAX 度量值	references/dax-patterns.md
星型架构指南	制定数据模型设计决策	references/star-schema-guide.md
PBI Service 与网关	配置发布和刷新	references/pbi-service-gateway.md

工具

文件操作（PBIP 开发）

工具	用途
Read	读取 .tmdl、.pq、.pbip、.pbir、.pbism、report.json、theme.json 文件
Write	为新表、表达式和主题创建新的 .tmdl、.pq、.json 文件
Edit	修改现有 .tmdl 文件（添加度量值、列），编辑 .pq 表达式，更新 relationships.tmdl
Glob	按模式查找文件：**/*.tmdl、**/*.pq、**/expressions/*.pq
Grep	搜索 TMDL/PQ 文件：查找度量值名称、lineageTags、列引用

代码搜索与导航

工具	用途
Grep pattern: "lineageTag"	验证所有 .tmdl 文件中的 lineageTag 唯一性
Grep pattern: "displayFolder"	列出所有度量值文件夹以便整理
Grep pattern: "USERELATIONSHIP"	查找使用非活动关系的度量值
Grep pattern: "isActive: false"	查找需要配合 USERELATIONSHIP 使用的非活动关系
Glob pattern: "**/*.pq"	列出所有 Power Query 表达式
Glob pattern: "**/tables/*.tmdl"	列出所有表定义

自动化与脚本

工具	用途
Bash	运行 Python 脚本：python scripts/export_billing_data.py --period YYYYMM
Bash	运行异常检测：python scripts/detect_anomalies.py --data-folder ./data
Bash	对 PBIP 文件执行 Git 操作（提交、差异比较、分支）
Bash	安装 Python 依赖项：pip install -r scripts/requirements.txt
Bash	使用 Azure CLI 进行数据导出身份验证：az login、az account set

浏览器自动化（Power BI Service）

工具	用途
浏览器工具（mcp__claude-in-chrome__*）	浏览 Power BI Service 网页界面
navigate	打开 Power BI 工作区、数据集设置和刷新历史记录
form_input	配置计划刷新、数据源凭据和参数
get_page_text / read_page	查看刷新历史记录、错误消息和数据集设置
javascript_tool	与 PBI Service 界面元素交互
tabs_create_mcp	打开 PBI Service 页面的新标签页
gif_creator	录制多步骤 PBI Service 配置过程，用于编写文档

研究与文档

工具	用途
WebSearch	查询 DAX 函数、TMDL 语法变更和 PBI 发布说明
WebFetch	获取 Microsoft Learn 上的 PBI/DAX/M 参考文档
microsoft_docs_search（MCP）	搜索 Microsoft 官方 PBI 文档
microsoft_docs_fetch（MCP）	获取完整的 PBI 文档页面
microsoft_code_sample_search（MCP）	从 Microsoft 文档中查找 DAX/M 代码示例
context7（MCP）	获取 Azure SDK、PBI REST API 的最新库文档

数据检查

工具	用途
Read	检查 CSV 账单导出文件（预览前几行）
Bash wc -l	统计大型 CSV 文件的行数
Bash head -5	预览 CSV 标题行和前几行
CSV 上的 Grep	搜索特定资源组、订阅或成本值

常见工具序列

添加新度量值：

1. 使用 Grep 查找现有 lineageTags → 确保唯一
2. 使用 Read 查看 _Measures.tmdl → 了解现有模式
3. 使用 Edit 编辑 _Measures.tmdl → 添加新度量值

添加新表：

1. 使用 Write 创建 expressions/NewTable.pq → 创建 PQ 表达式
2. 使用 Write 创建 tables/NewTable.tmdl → 创建表定义
3. 使用 Edit 编辑 relationships.tmdl → 添加关系
4. 使用 Grep 查找 lineageTags → 验证没有冲突

排查连接器身份验证问题：

1. 使用 Read 查看 workflows/connector-auth.md → 获取诊断步骤
2. 使用浏览器工具 → 导航至 EA 门户或 PBI Service 设置
3. 使用 Read 查看项目记忆 → 检查已知的 EA 注册详情

发布和刷新：

1. 使用浏览器工具 → 导航至 PBI Service 工作区
2. 使用 read_page → 检查当前数据集设置
3. 使用 form_input → 配置刷新计划
4. 使用 get_page_text → 验证刷新历史记录

关键规则

1. 仅使用 PBIP 格式 — 对于纳入版本控制的项目，绝不要建议使用 .pbix。PBIP 是适合 Git 的格式（TMDL = 文本，PQ = 文本，差异清晰）。

2. 注意本地化 — 询问用户标签应使用哪种语言。对于巴西项目，使用 pt-BR 标签、BRL 货币格式（R$ #,##0.00）和葡萄牙语月份名称。

3. 遵循星型架构规范 — 所有关系都必须是从事实表到维度表的 M:1。使用 crossFilteringBehavior: oneDirection。对于有歧义的路径（例如，多个日期关系），在 DAX 中使用 isActive: false + USERELATIONSHIP()。

4. 度量值表模式 — 所有 DAX 度量值都放在专用的 _Measures 表中（使用 ROW("MeasureColumn", 0) 创建计算表）。将度量值归类到 displayFolder 文件夹中。

5. Power Query 参数 — 对于基于文件夹的 CSV 导入，使用 Parameter_ExportFolder 参数。这样无需编辑 PQ 代码即可配置数据源路径。

6. lineageTag 规范 — 每个表、度量值、列和关系都需要唯一的 lineageTag。使用描述性的 kebab-case：m-custo-total、t-fact-usage、rel-usage-date。

7. 格式字符串 — 货币：R$ #,##0.00（或符合区域设置的格式）。百分比：0.0%;-0.0%;0.0%。整数：#,##0。百分比使用三段式格式，以正确处理负值。

8. EA 连接器与 Azure RBAC — 面向 EA 注册的 PBI Cost Management 连接器要求在计费账户级别具有 Enterprise Administrator (read-only) 角色。标准 Azure RBAC 角色（Cost Management Reader、Billing Reader）不起作用。请参阅 workflows/connector-auth.md。

快速示例

TMDL 度量值

measure 'Custo Total' =
    SUM(Fact_Usage[PretaxCost])
    formatString: R$ #,##0.00
    displayFolder: Custo
    lineageTag: m-custo-total

TMDL 关系

relationship Fact_Usage_to_Dim_Date
    fromColumn: Fact_Usage.DateKey
    toColumn: Dim_Date.Date
    crossFilteringBehavior: oneDirection

Power Query — 基于文件夹的 CSV 导入

let
    Source = Folder.Files(Parameter_ExportFolder),
    Filtered = Table.SelectRows(Source, each
        Text.Contains([Name], "UsageDetails") and Text.EndsWith([Name], ".csv")),
    Combined = Table.Combine(
        Table.AddColumn(Filtered, "Data", each
            Csv.Document([Content], [Delimiter=",", Encoding=65001])
        )[Data]
    )
in
    Combined

DAX — 使用安全除法计算环比差异

measure 'Variacao MoM %' =
    VAR CustoAtual = [Custo Mes Atual]
    VAR CustoAnterior = [Custo Mes Anterior]
    RETURN
        IF(
            CustoAnterior <> 0,
            DIVIDE(CustoAtual - CustoAnterior, CustoAnterior),
            BLANK()
        )
    formatString: 0.0%;-0.0%;0.0%
    displayFolder: Variacao

---

注意事项

• PBIP 与 PBIX 单向重新生成： 将 .pbip 重新保存为 .pbix，再转回 .pbip，可能会悄悄重新生成所有 lineageTag GUID 并改写 TMDL 空白字符，造成规模巨大的零语义差异。始终通过 PBIP 往返转换，并在提交前检查差异。
• EA 连接器不识别 Azure RBAC： 对于 EA 注册，Cost Management Reader 和 Billing Reader 角色总是会失败。只有计费账户级别的 Enterprise Administrator (read-only) 才有效。MCA 注册使用完全不同的身份验证路径。
• Parameter_ExportFolder 必须是 Text 类型，而不能是路径字面量： 开发期间 PQ 接受字面量，但 Service 刷新会在凭据之前评估参数，从而抛出含糊的 "formula.firewall" 错误，且不会指出有问题的参数。
• 三段式格式字符串会让零值显示为正数形式： 0.0%;-0.0%;0.0% 会以正数形式显示零值。如果零值应显示为短横线，请使用 0.0%;-0.0%;"-" — 正数在审阅时看起来完全相同。
• 对实时导出文件夹使用 Folder.Files 会导致结果不确定： 如果导出在刷新过程中覆盖同名文件，PQ 可能会读取不完整文件，但不会报错。请按 Date.From([Date modified]) 进行筛选，或在导出路径中按 YYYYMM 分区。
• crossFilteringBehavior: oneDirection 是唯一正确的写法： singleDirection 导入时可以解析，但会被悄悄忽略。拼写错误会使星型架构变为双向筛选，导致性能下降并产生有歧义的路径。