power-bi

Power BI 開発スキル

PBIP（Power BI Project）形式を使用した、エンドツーエンドの Power BI プロジェクト開発です。PBIP は、Power BI ソリューションのバージョン管理に適した、Git フレンドリーなテキストベースの形式です。

このスキルを使用する場面

• 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	「PBI プロジェクトを作成」「PBIP のひな形を作成」「新しい Power BI プロジェクト」	workflows/new-project.md
AddTable	「テーブルを追加」「新しいファクトテーブル」「新しいディメンション」「PQ ソースを追加」	workflows/add-table.md
AddMeasure	「DAX メジャーを追加」「メジャーを作成」「新しい KPI」	workflows/add-measure.md
DataModeling	「スタースキーマ」「リレーションシップを追加」「データモデル設計」	workflows/data-modeling.md
PublishRefresh	「サービスに発行」「スケジュールされた更新」「データゲートウェイ」	workflows/publish-refresh.md
ConnectorAuth	「コネクタ認証」「EA コネクタ」「コスト管理コネクタ」「PBI サインインに失敗」	workflows/connector-auth.md
Troubleshooting	「PBI エラー」「更新に失敗」「データが読み込まれない」「型エラー」	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 の Web UI を操作します
navigate	Power BI ワークスペース、データセットの設定、更新履歴を開きます
form_input	スケジュール更新、データソースの資格情報、パラメーターを設定します
get_page_text / read_page	更新履歴、エラーメッセージ、データセットの設定を読み取ります
javascript_tool	PBI Service の UI 要素を操作します
tabs_create_mcp	PBI Service のページを開く新しいタブを作成します
gif_creator	ドキュメント用に、複数ステップからなる PBI Service の設定を記録します

調査とドキュメント

ツール	用途
WebSearch	DAX 関数、TMDL 構文の変更、PBI リリースノートを検索します
WebFetch	PBI／DAX／M のリファレンスとして Microsoft Learn のドキュメントを取得します
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。負の値に対応するため、パーセンテージには 3 部構成の書式を使用してください。

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 として再保存し、さらに戻すと、すべての 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」エラーが発生します。
• 3 部構成の書式文字列ではゼロが反転します： 0.0%;-0.0%;0.0% では、ゼロが正の値と同じ形式で表示されます。ゼロをダッシュで表示する場合は 0.0%;-0.0%;"-" を使用してください。正の値の表示はレビュー時と同じです。
• ライブのエクスポートフォルダーに対する Folder.Files は非決定的です： 更新中にエクスポートで同じファイル名が上書きされると、PQ はエラーを出さずに不完全なファイルを読み込むことがあります。Date.From([Date modified]) でフィルターするか、エクスポートパスを YYYYMM 単位で分割してください。
• crossFilteringBehavior: oneDirection が唯一正しい表記です： singleDirection はインポート時に解析されますが、予告なく無視されます。誤った表記を使うと、スター スキーマが双方向になり、パフォーマンスが低下して、あいまいなパスが生じます。