power-bi-deployment

Power BI 部署技能

通过 TMDL 导出/导入、事务和版本控制管理模型生命周期。

先决条件

pipx install pbi-cli-tool
pbi-cli skills install
pbi connect

连接到目标

# Local Power BI Desktop (auto-detects port)
pbi connect

# Local with explicit port
pbi connect -d localhost:54321

# Named connections for switching
pbi connect -d localhost:54321 --name dev
pbi connections list
pbi connections last
pbi disconnect

TMDL 导出和导入

TMDL（表格模型定义语言）是一种基于文本的格式，用于对 Power BI 模型进行版本控制。

# Export entire model to TMDL folder
pbi database export-tmdl ./model-tmdl/

# Import TMDL folder into connected model
pbi database import-tmdl ./model-tmdl/

TMSL 导出

# Export as TMSL JSON (for SSAS/AAS compatibility)
pbi database export-tmsl

TMDL 差异（比较快照）

比较两个 TMDL 导出文件夹，查看快照之间的变更。 适用于 CI/CD 流水线（“此 PR 对模型做了哪些变更？”）。

# Compare two exports
pbi database diff-tmdl ./model-before/ ./model-after/

# JSON output for CI/CD scripting
pbi --json database diff-tmdl ./baseline/ ./current/

返回结构化摘要：

• tables：新增、删除和变更的表格，以及每个表格的实体差异 （新增、删除或变更的度量值、列、分区、层次结构）
• relationships：新增、删除和变更的关系
• model：变更的模型级属性（例如，区域性、默认 Power BI 数据集版本）
• summary：所有变更的总计数

系统会自动过滤仅涉及 LineageTag 的变更（GUID 重新生成但没有实际编辑）， 以避免误报。

无需连接 Power BI Desktop——可直接处理导出的文件夹。

数据库操作

# List databases on the connected server
pbi database list

事务管理

使用事务执行原子性的多步变更：

# Begin a transaction
pbi transaction begin

# Make changes
pbi measure create "New KPI" -e "SUM(Sales[Amount])" -t Sales
pbi measure create "Another KPI" -e "COUNT(Sales[OrderID])" -t Sales

# Commit all changes atomically
pbi transaction commit

# Or rollback if something went wrong
pbi transaction rollback

表格刷新

# Refresh individual tables
pbi table refresh Sales --type Full
pbi table refresh Sales --type Automatic
pbi table refresh Sales --type Calculate
pbi table refresh Sales --type DataOnly

工作流：使用 Git 进行版本控制

# 1. Export model to TMDL
pbi database export-tmdl ./model/

# 2. Commit to git
cd model/
git add .
git commit -m "feat: add new revenue measures"

# 3. Later, import back into Power BI Desktop
pbi connect
pbi database import-tmdl ./model/

工作流：部署前检查模型

# Get model metadata
pbi --json model get

# Check model statistics
pbi --json model stats

# List all objects
pbi --json table list
pbi --json measure list
pbi --json relationship list

最佳实践

• 变更前务必导出 TMDL（作为备份）
• 对涉及多个对象的变更使用事务
• 部署到生产环境前，先在开发环境中测试变更
• 在脚本化部署中使用 --json
• 将 TMDL 存储在 git 中，以保留版本历史
• 使用命名连接（--name），避免误操作错误的环境

---

注意事项

• import-tmdl 无法对整个文件夹执行原子操作： 如果导入过程中某个文件解析失败，已应用的部分变更会保留在已连接的模型中。务必在 import-tmdl 外层使用 pbi transaction begin，或先导出备份，以便通过重新导入回滚。
• diff-tmdl 按设计会过滤仅涉及 lineageTag 的变更： 这有助于减少干扰，但也会掩盖依赖这些标签重新分配的下游 Power BI Service 有效变更（部署流水线、透视表、数据集市）。调查 Service 中引用失效的问题时，请使用 git diff 比较原始文件夹。
• 命名连接会跨 pbi-cli 会话保留： 即使关闭 Desktop，--name prod 仍然有效。如果误以为自己连接的是 dev，却运行了具有破坏性的 import-tmdl，就很容易出错。执行变更命令前，务必先运行 pbi connections last。
• table refresh --type Full 会重建计算列和关系： 对大型表格，这会触发耗时的重新处理，并锁定模型。生产环境刷新时优先使用 --type DataOnly；仅在架构变更时使用 Full。
• TMSL 导出为 JSON；TMDL 导出为文本文件夹： 这两种格式不能互换用于 git 差异比较——TMSL 会将所有度量值合并到一个大型 JSON 文件中，导致差异难以清晰查看。使用 TMDL 进行版本控制，将 TMSL 留作 SSAS/AAS 兼容用途。
• transaction rollback 只会回滚元数据变更，不会回滚数据刷新： 如果在事务中运行了 table refresh，回滚后刷新后的数据仍会保留。刷新操作会在事务之外提交。