power-bi-build

/power-bi-build

IPPF ブランドの Power BI 成果物を作成します。v1 の範囲：pbi CLI を使ってセマンティックモデルに DAX メジャーを書き込み、.pbip フォルダーに IPPF テーマ JSON を直接書き込みます。インジケーターダッシュボード、エクイティ、方法論のページレシピは JSON ステージング成果物として保存し、ユーザーが Power BI Desktop で手動で適用します。ページとビジュアルの完全な自動化は v2 です。

ツールの現状

pbi CLI（パッケージ pbi-cli-tool、コマンド名 pbi）は、セマンティックモデル操作のみを行う Power BI MCP サーバーをラップします。

• ✅ pbi measure create — DAX メジャーを追加します。
• ✅ pbi table、pbi column、pbi relationship — モデル構造を操作します。
• ✅ pbi dax — DAX を実行して検証します。
• ❌ pbi theme コマンドはありません。テーマ JSON は .pbip フォルダーに直接書き込みます。
• ❌ pbi page または pbi visual コマンドはありません。ステージングレシピ JSON をガイドとして、Power BI Desktop でページとビジュアルを手動で作成します。

上流ツールにレポートレイヤーのコマンドが追加されたら、このスキルにも取り込みます。v1 の範囲は上記のとおりです。

2 つの方法があります。 以下の v1 のフロー（メジャーには pbi CLI、テーマ、ステージングされたページレシピ）は、既存のモデルをユーザーが手作業で構築し続ける場合に適しています。ソースが Excel ワークブックで、ユーザーが すぐに使える完全なダッシュボードの引き渡し（データの読み込み、メジャー、テーマ、レポートページのすべてを作成）を希望する場合は、代わりに以下の専用セクションにある 完全な .pbip 作成方法を使用します。この方法はエンドツーエンドで検証済みです（CERV Portfolio Dashboard、2026-06-20）。

事前確認

以下の確認を順に実行します。最初に失敗した時点で、指定されたメッセージを表示して停止します。

1. pbi がインストールされていること。

   • 実行：pipx list | grep pbi-cli-tool。
   • 出力が空の場合：停止します。次のメッセージを表示します："pbi CLI is not installed. Run: pipx install pbi-cli-tool && pipx ensurepath && pbi skills install. Open a fresh shell so PATH updates pick up."

2. Power BI Desktop が、名前付き接続のあるアクティブなプロジェクトで実行中であること。

   • pbi connect（引数なし）を一度実行し、"Auto-detected Power BI Desktop on localhost:" の行からポートを読み取ります。切断します：pbi disconnect。
   • MCP サーバーの内部ラベルと一致する明示的な名前で再接続します：pbi connect -d localhost:<port> -n PBIDesktop-<pbip-basename>-<port>。モデルから導出された名前が必要です。pbi-cli のデフォルトの保存名 localhost-<port> は、メジャー／テーブル操作で MCP サーバーに拒否され、"Connection 'localhost-<port>' not found" が返されます。
   • pbi connect がアクティブなプロジェクトがないと報告した場合：停止します。次のメッセージを表示します："Open Power BI Desktop and load a .pbip project, then re-run."
   • セッション中に Analysis Services のポートが変わった場合（Power BI Desktop はファイルを再度開いたときやモデルビューに切り替えたときなどにエンジンを再起動することがあります）、新しいポートでこの手順を再実行します。

3. アクティブなプロジェクトがレガシーの .pbix バイナリではなく、テキスト形式の .pbip であること。

   • pbi connect の出力にプロジェクトパスが含まれます。パスが .pbix で終わる場合：停止します。次のメッセージを表示します："Save your project as .pbip first — File → Save as → set Save as type to Power BI Project. The skill operates on the text-based PBIP format only."

4. ブランドレイヤーをインポートできること。

   • ${WORK_FOLDER_ROOT}/ane_package/reporting/powerbi_dashboard/__init__.py が存在することを確認します。
   • 存在しない場合：停止します。次のメッセージを表示します："Brand layer not found at ${WORK_FOLDER_ROOT}/ane_package/reporting/powerbi_dashboard/. Verify OneDrive sync."

意図の特定

プロンプトと、このセッションで最も新しい分析成果物から、以下を特定します。

• インジケーター — MEL_DAX_LIBRARY のキー。不明確な場合は、Ane に次のように尋ねます："Which indicators? Available: {sorted(MEL_DAX_LIBRARY.keys())}"。
• 対象者のティア — デフォルトは Tier 1 の作業用ブリーフです。プロンプトで指定された場合のみ Tier 2 の公開用とします。
• ページセット — インジケーターごとに、デフォルトは (indicator_dashboard, equity_disaggregation, methodology_card) です。
• ソース表記 — 以前の成果物から導出します。見つからない場合は、一度だけ尋ねます。
• ステージングディレクトリ — デフォルトは ${PWD}/powerbi-build-output/ です。実行用の theme.json、measures.json、ページレシピを格納します。

作成（Python — すべての成果物をメモリ内で生成）

import json
from pathlib import Path
from ane_package.reporting.powerbi_dashboard import (
    MEL_DAX_LIBRARY,
    build_equity_disaggregation_page,
    build_indicator_dashboard_page,
    build_ippf_theme,
    build_methodology_card_page,
)

theme = build_ippf_theme()
measures = {k: MEL_DAX_LIBRARY[k] for k in selected_indicators}

pages = []
for indicator in selected_indicators:
    pages.append(build_indicator_dashboard_page(indicator, target, source))
    pages.append(build_equity_disaggregation_page(
        indicator, ("age", "gender", "geography", "wgss_disability"), source))
pages.append(build_methodology_card_page(method_note, evidence_base_sources, glossary_terms))

staging = Path("powerbi-build-output")
staging.mkdir(exist_ok=True)
(staging / "theme.json").write_text(json.dumps(theme, indent=2))
(staging / "measures.json").write_text(json.dumps(measures, indent=2))
for i, page in enumerate(pages):
    (staging / f"page_{page['page_id']}.json").write_text(json.dumps(page, indent=2))

適用

1. pbi measure create を使った DAX メジャーの作成

各メジャーについて、DAX 式内の [角括弧] 参照からテーブルを推測します（ヒューリスティック：式内で最初に参照される Table[Column]。式が他のメジャーのみを参照する場合は _Measures）。

pbi measure create <measure-key> \
    --table <inferred-table> \
    --expression "<dax-expression>"

メジャー名は位置引数です（--name フラグではありません）。pbi-cli-tool 0.5.6 で確認済みです。

エラーは一字一句そのまま表示してください。再試行は絶対にしないでください。pbi の失敗は通常、参照先のテーブルまたは列がモデルに存在しないことを意味します。pbi-cli は「table not found」が発生するとトランザクションをロールバックします。そのため、赤いアイコン付きのメジャーは作成されません（以前の Power BI の動作とは異なります）。再試行の前にスタブテーブルを用意するか、DAX を修正してください。

1a. 保存ルール — pbi によるモデルの書き込み後、毎回必須

pbi table／pbi measure／pbi column／pbi relationship による書き込みのたびに、Ane に Power BI Desktop に切り替えて、すぐに Ctrl+S を押すよう伝えてください。外部からの pbi による書き込みは、Analysis Services エンジンのメモリにのみ保持されます。ディスク上の .pbip は、Power BI Desktop で［ファイル］→［保存］を実行したときに更新されます。保存前にエンジンが再起動すると（ポートの変更、ファイルの再オープン、場合によってはモデルビューへの切り替え）、書き込み内容は失われます。

2. テーマ JSON — .pbip フォルダーに直接書き込む

.pbip はテキスト形式のプロジェクトです。テーマ JSON はカスタムテーマとしてレポートフォルダーに配置します。パスの構成（Power BI Desktop 2.140 以降）：

<project>.pbip
<project>.Report/
    StaticResources/
        SharedResources/
            BaseThemes/
                ippf-visual-identity-2025.json   ← write theme here
        RegisteredResources/
            ippf-visual-identity-2025.json       ← also write here
    definition/
        report.json                              ← register the theme (see below)

テーマ JSON を両方のパスに書き込みます。その後、report.json を更新してテーマを登録します（Power BI Desktop は report.json のメタデータからテーマ名を読み取ります。登録しないと、テーマギャラリーには表示されても自動適用されません）。

ユーザーが Power BI Desktop で PBIP レポート形式のプレビュー（［ファイル］→［オプション］→［プレビュー機能］→［Power BI Project (.pbip) source control］）を有効にしていない場合、テーマのパスが異なることがあります。<project>.Report/ が存在しない場合は、明確なメッセージを表示してください。

再試行時はキャッシュを回避します。 Power BI Desktop は、インポートに失敗した場合、登録済みテーマをファイル名でキャッシュします。修正後に同じファイル名で再インポートしても、古い検証エラーが再表示されます。検証失敗後に再試行する場合は、新しいテーマ JSON をバージョン付きの名前（ippf-visual-identity-2025-v2.json、-v3 など）で書き込み、Power BI が新しいファイルとして解析するようにしてください。

3. ページレシピ — v1 ではステージングのみ

各ページレシピをステージングディレクトリに JSON として保存します。v1 では、PBIR ページファイルを .pbip フォルダーに書き込もうとしないでください（PBIR 形式はまだプレビュー段階で、スキーマも安定していません）。

チャット出力で、どのファイルにどのページレシピが含まれているか、またどのビジュアルを手動で作成するかを、Ane に正確に伝えてください。

Pages saved to staging — apply manually in Power BI Desktop:

powerbi-build-output/page_cyp_total-dashboard.json
  → New page "cyp_total Dashboard"
  → Card visual: measure [cyp_total], position (40, 40, 280, 120)
  → Line chart: x=Date[Month], y=[cyp_total], position (360, 40, 880, 320)
  → Bar chart: x=Geography[country], y=[cyp_total], position (40, 380, 1200, 280)

(repeat for each page)

v2 では、上流の pbi-cli にレポートレイヤーのサポートが追加された後、または PBIR の直接書き込み機能を実装した後に、ページ作成を自動化します。

Excel から完全な .pbip を作成する（完全引き継ぎルート）

ソースが Excel ブックで、ユーザーがステージングされたレシピではなく、完全に動作するダッシュボードを希望する場合に使用します。pbi CLI は Excel データをインポートできず（PowerBI 互換モードでは DataSourceOperationsTool がスキップされます）、レポートページ／ビジュアルの API もありません。そのため、Python ジェネレーター（再実行可能な単一スクリプト）で .pbip 全体を作成します。参考ビルド：${WORK_FOLDER_ROOT}/scripts/gen_cerv_dashboard_pbip.py。

対象の .pbip がすでに存在する場合は、mel_wiki/wiki/concepts/edit-preservation-protocol.md を適用してください。 ユーザーが対象のプロジェクトを開いている場合は、新しいプロジェクトフォルダーに作成してください（ファイルロックを回避できます）。ユーザーには、保存せずに閉じてから再度開いてもらいます。 手順：

1. スキーマをそのまま再現します。 既存の空の .pbip のスケルトンを読み、バージョンを正確にコピーします（compatibilityLevel 1600、report.json 3.3.0、visual 2.9.0、page 2.1.0、pbism 4.2）。Desktop で PBIP と PBIR のプレビュー機能を有効にする必要があります。
2. openpyxl で Excel を調べます。 シート名、ヘッダーの文字列（末尾のスペースを削除しないでください。列参照が機能しなくなります）、ヘッダー行の位置、列ごとの値の型を確認します。既存のブック内ダッシュボードタブがある場合は、想定される集計値と照合します。
3. セマンティックモデルの TMDL を作成します（TAB インデント）。database.tmdl、model.tmdl（ref table X 行と relationship ブロックを含む）、cultures/、tables/*.tmdl（列、メジャー、M の partition）を作成します。M ブロックは source = より深くインデントします。
4. レポート PBIR を作成します。 definition.pbir（セマンティックモデルへの相対 byPath。このリンクはフォルダーを移動しても維持されます）、report.json（IPPF カスタムテーマとベーステーマを登録）、pages/<id>/page.json、pages/<id>/visuals/<id>/visual.json を作成します。
5. メジャーをソースの集計値と照合し、ユーザーに開いて更新してもらいます。 読み込み後、CLI で確認します。pbi connect を実行し、続いて pbi dax execute "EVALUATE <Table>" を実行して RowCount= を読み取ります（CLI はセルの値を出力しません。テーブルの EVALUATE を使い、行数を読み取ってください）。

Power Query M の注意点（いずれも更新エラーを招くため、事前に対処してください）：

• Excel.Workbook(File.Contents(path), null, true) は先頭の完全な空行を削除するため、固定の Table.Skip(n) ではヘッダーの位置がずれます。動的に検索します。HeaderRow = List.PositionOf(Sheet[Column1], "<key header>")、続いて Table.Skip(Sheet, HeaderRow)、その後に Table.PromoteHeaders(.., [PromoteAllScalars=true]) を使います。
• List.PositionOf（リスト + 値）を使います。Table.PositionOf（テーブル + レコード）ではありません。後者は "cannot convert List to Table" をスローします。
• ダッシュボードで必要な列だけを明示的に型指定します（金額 → type number、件数 → Int64.Type）。計算列や "(auto)" 列を型指定すると、未入力の行で数値以外（"" / "Pending"）が返された場合、セルごとに "N errors" が発生します。これらの列は型指定しないでください。
• 複数行ヘッダーまたは結合セルのあるシートでは、PromoteHeaders をスキップし、位置指定の Table.Range + Table.SelectColumns({"Column1",...}) + 名前変更を使います。
• M のファイルパスはリテラルです（バックスラッシュのエスケープは不要です）。ソースパスは共有式に一度だけ記述するか、一貫してインラインに記述します。

PBIR のビジュアル JSON（事前に作成したものはすべて正しくレンダリングされました）： 最小構成は visual.query.queryState.<role>.projections[{field:{Measure|Column:{Expression:{SourceRef:{Entity}},Property}}, queryRef:"Entity.Prop", nativeQueryRef:"Prop"}] です。ロール：card → Values、clusteredColumnChart／clusteredBarChart → Category + Y（複数メジャーのグラフでは Category を省略）、tableEx → Values（リスト）。タイトルオブジェクトは省略します。IPPF テーマと自動タイトルにスタイル設定を任せてください。追加要素：スライサーの複数選択 + すべて選択 = objects.selection[{properties:{singleSelect:{Literal false}, selectAllCheckboxEnabled:{Literal true}}}]、ナビゲーションバー = visualType pageNavigator、ロゴ = visualType image に ResourcePackageItem(RegisteredResources) を指定し、PNG を StaticResources/RegisteredResources/ にコピーして report.json に登録、ヘッダーバンド = visualContainerObjects.background を指定したテキストボックス。

見やすいレイアウト（1280×720）： コンパクトな全幅のスライサー列（スライサーはドロップダウンとして表示）、KPI カードの列、その下に全幅を使った大きなグラフを配置します。右側に余白ができる部分幅のスライサー列は避けてください。ページの displayOption は FitToWidth に設定し、モニターの幅に合わせて表示し、縦方向にスクロールできるようにします。

配布とライセンス（ユーザーへの案内）

• .pbip は開発／ソース管理用の形式です。更新するまで空の状態で開くため、初心者には向きません。
• 初心者が閲覧する場合は .pbix を配布してください（ファイル → 名前を付けて保存 → .pbix にするとデータが埋め込まれ、データが表示された状態で開き、ライセンスも不要です）。.pbix を作成できるのは Power BI Desktop だけです。CLI やスクリプトでは作成できず、データを埋め込むには事前にライブ更新が必要です。
• Power BI Service で公開する場合、無料プランの同僚が閲覧できるのは、ワークスペースが Premium（P SKU）または Fabric F64 以上の容量にある場合のみです。それ以外の場合、閲覧者全員に Pro/PPU も必要です。機微データ（SRHR／財務／サブグランティー）には「Publish to web」を絶対に使用しないでください。公開状態になります。
• ページナビゲーターとボタンは、閲覧ビュー／公開済みの状態ではシングルクリック、編集ビューでは Ctrl+クリックで移動します（Power BI 固有の動作であり、バグではありません）。
• 絶対パスまたは OneDrive パスを参照する Excel ソースは、SharePoint に移動すると動作しなくなります。クラウドでのスケジュール更新には、SharePoint コネクタを使って参照先を設定し直してください。更新のたびにソースが再読み込みされます。

出力（ティア 1 作業用ブリーフ）

Power BI build complete (v1 scope: measures + theme + page recipes).

Measures applied to semantic model: {N} ({list of keys}).
Theme written to: {project}.Report/StaticResources/SharedResources/BaseThemes/ippf-visual-identity-2025.json

Page recipes staged at powerbi-build-output/:
  - page_<id>.json — {N} visuals each. Apply manually per the recipe.

Source: {derived source line}.

よくあるエラー

エラー	考えられる原因	対処方法
インストール後に pbi: command not found と表示される	PATH がまだ更新されていません	pipx ensurepath を実行し、新しいシェルを開きます。
pbi connect でセッションがないと報告される	Power BI Desktop が起動していない、または .pbip が開かれていません	Power BI Desktop を開き、.pbip を読み込みます。
pbi measure create が失敗し、「table not found」と表示される	DAX メジャーが、モデルに存在しないテーブルを参照しています	データモデルがメジャーの想定と一致しているか確認し、テーブルを追加するか、DAX を調整します。
インジケーターが MEL_DAX_LIBRARY にない	新しいインジケーターを追加しようとしています	wiki エントリとともに dax_library.py に追加し、anework-package に PR を送ります。
Power BI Desktop でテーマが適用されない	PBIP プレビュー機能が無効になっているか、テーマが report.json に登録されていません	PBIP プレビューを有効にします（File → Options → Preview features）。report.json にテーマ名が含まれていることを確認します。
ページレシピに、ユーザーが見つけられない visualType が指定されている	Power BI Desktop の UI 上の名前が、レシピの type と異なります	ビジュアル ギャラリーを使います。card = "Card"、lineChart = "Line chart"、barChart / stackedBarChart = "Stacked bar chart"、slicer = "Slicer"、table = "Table"、textbox = "Text box" です。
pbi measure create が失敗し、Connection 'localhost-<port>' not found と表示される	pbi-cli が自動保存する名前と、MCP サーバーの内部名が異なります	-n PBIDesktop-<pbip-basename>-<port> を指定して再接続します。Pre-flight の手順 2 を参照してください。
pbi によるモデルへの書き込みがコマンド間で消える	File → Save の前に AS エンジンが再起動しました	pbi で書き込むたびに、Power BI Desktop で Ctrl+S を押します。Apply の手順 1a を参照してください。
修正後も同じキーに関する oneOf 検証エラーでテーマのインポートに失敗する	Power BI Desktop が、失敗した前回の解析結果をファイル名でキャッシュしています	テーマ JSON を -v2（または -v3）というファイル名で書き直し、再度参照します。Apply の手順 2 を参照してください。
pbi table refresh が Invalid operation: Refresh で失敗する	pbi-cli 0.5.6 は Refresh という操作名を送信しますが、MCP サーバーが受け付けるのは REFRESHWITHXMLA / REFRESHWITHAPI のみです	pbi-cli の上流バグです。回避策として、Power BI Desktop で手動で更新を実行します（Home → Refresh）。
pbi measure get または pbi table export-tmdl が References is required で失敗する	pbi-cli 0.5.6 は References パラメーターを MCP サーバーに渡しません	pbi-cli の上流バグです。メジャーの存在確認には pbi measure list --table <name> を使い、TMDL の確認には Power BI Desktop の Tabular Editor ビューを使います。
更新時に「The column '' of the table wasn't found」と表示される（ヘッダー昇格テーブル）	Excel.Workbook が先頭の空白行を削除したため、固定の Table.Skip でヘッダーの位置がずれました	ヘッダーを動的に検索します：Table.Skip(Sheet, List.PositionOf(Sheet[Column1], "<key>"))。full-authoring のルートを参照してください。
更新時に「We cannot convert a value of type List to type Table」と表示される	列に Table.PositionOf を使用しました	Table.PositionOf(table, record) ではなく、List.PositionOf(list, value) を使います。
1 つのテーブルで更新時に「N rows loaded. M errors」と表示される	型指定された計算列／「(auto)」列が、まだ入力されていない行に対して数値以外の値を返しています	その列の型変換を削除し、ダッシュボードで必要な列だけに型を指定します。
レポートは開くが、更新後にすべてのビジュアルが空白になる	インポートモデルの読み込み行数が 0 です（M が失敗）。バインドの問題ではありません	pbi で接続し、pbi dax execute "EVALUATE <Table>" を実行して RowCount= を確認します。ビジュアルではなく M を修正します。
受信者が .pbip を開くと、空のレポートが表示される	.pbip にはデータが保存されないため、更新するまでは空の状態で開きます	データを埋め込んだ .pbix を配布するか、Service に発行します。Distribution & licensing を参照してください。