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（Tabular Model Definition Language）は、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 の差分（スナップショットの比較）

2 つの 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 のセッションをまたいで保持されます： --name prod は Desktop を閉じた後も残ります。dev に接続していると思い込んで破壊的な import-tmdl を実行するのは、よくある危険なミスです。変更を伴うコマンドを実行する前に、必ず pbi connections last を実行してください。
• table refresh --type Full は計算列とリレーションシップを再構築します： 大きなテーブルでは長時間の再処理が発生し、モデルがロックされます。本番環境の更新には --type DataOnly を優先し、Full はスキーマ変更に限って使用してください。
• TMSL のエクスポートは JSON、TMDL のエクスポートはテキストファイルのフォルダーです： Git の差分比較では、この 2 つの形式は互換性がありません。TMSL はすべてのメジャーを 1 つの大きな JSON にまとめるため、きれいな差分が得られなくなります。バージョン管理には TMDL を使い、SSAS/AAS との互換性が必要な場合に限って TMSL を使用してください。
• transaction rollback で取り消されるのはメタデータの変更だけで、データの更新は対象外です： トランザクション内で table refresh を実行した場合、ロールバック後も更新済みのデータは残ります。更新処理はトランザクションの範囲外でコミットされます。