power-bi-report

Power BI レポートスキル

Power BI PBIR レポートプロジェクトを最上位レベルで管理します。スキャフォールディング、検証、プレビュー、Desktop との連携に対応しています。ほとんどの操作で Power BI Desktop への接続は必要ありません。

PBIR 形式

PBIR（拡張レポート形式）では、レポートを JSON ファイルのフォルダーとして保存します。

MyReport.Report/
  definition.pbir            # dataset reference
  definition/
    version.json             # PBIR version
    report.json              # report settings, theme
    pages/
      pages.json             # page order
      page_abc123/
        page.json            # page settings
        visuals/
          visual_def456/
            visual.json      # visual type, position, bindings

各ファイルには、検証用の Microsoft 公開 JSON スキーマがあります。 PBIR は 2026 年 1 月時点で GA となり、2026 年 3 月以降、Desktop の既定の形式です。

レポートの作成

# Scaffold a new report project
pbi report create ./MyProject --name "Sales Report"

# With dataset reference
pbi report create ./MyProject --name "Sales" --dataset-path "../Sales.Dataset"

これにより、definition.pbir、report.json、version.json を含む完全なフォルダー構造と、空の pages/ ディレクトリが作成されます。

レポート情報と検証

# Show report metadata summary (pages, theme, dataset)
pbi report info
pbi report info --path ./MyReport.Report

# Validate report structure and JSON files
pbi report validate

検証では、次の項目を確認します。

• 必須ファイル（definition.pbir、report.json、version.json）が存在する
• すべての JSON ファイルをエラーなく解析できる
• スキーマ URL が存在し、一貫している
• pages.json のページ参照が実際のページフォルダーと一致している

プレビュー

レポートレイアウトのライブ HTML プレビューを開始します。

pbi report preview

ブラウザーが開き、すべてのページが、視覚的なプレースホルダー、種類、位置、データバインディングとともに表示されます。ファイルが変更されると、プレビューは自動で更新されます。

preview オプション依存関係が必要です：pip install pbi-cli-tool[preview]

Desktop との連携

# Trigger Power BI Desktop to reload the current report
pbi report reload

Power BI Desktop の Developer Mode は TMDL の変更を自動検出しますが、PBIR の変更は検出しません。このコマンドは Desktop ウィンドウにキーボードショートカットを送信して、再読み込みを実行します。reload オプション依存関係が必要です：pip install pbi-cli-tool[reload]

自動同期を抑制する（--no-sync）

既定では、すべての書き込みコマンド（add-page、delete-page、set-background、set-theme など）の実行後に、Power BI Desktop が自動で同期されます。複数の手順でレポートを作成すると、コマンドの実行ごとに Desktop が再読み込みされます。

report コマンドグループで --no-sync を使用すると、コマンドごとの同期を抑制できます。その後、最後に一度だけ pbi report reload を呼び出します。

# BAD: Desktop reloads after every command
pbi report add-page --display-name "Overview" --name overview
pbi report set-background overview --color "#F2F2F2"

# GOOD: suppress sync during build, reload once at the end
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report reload

--no-sync は、report、visual、filters、bookmarks の各コマンドグループで使用できます。

変換

# Convert a .Report folder into a distributable .pbip project
pbi report convert ./MyReport.Report --output ./distributable/

パスの解決

すべてのレポートコマンドは .Report フォルダーを自動検出します。

1. 明示的に指定：pbi report --path ./MyReport.Report info
2. 自動検出：CWD から上位へたどり、*.Report/definition/ を検索します
3. .pbip から検出：.pbip ファイルと同階層にある .Report フォルダーを探します

ワークフロー：レポートを完成させる

このワークフローでは、複数のスキルのコマンドを使用します。

# 1. Scaffold report (this skill)
pbi report create . --name "SalesDashboard" --dataset-path "../SalesModel.Dataset"

# 2. Add pages (power-bi-pages skill)
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Details" --name details

# 3. Add visuals (power-bi-visuals skill)
pbi visual add --page overview --type card --name revenue_card
pbi visual add --page overview --type bar --name sales_by_region

# 4. Bind data (power-bi-visuals skill)
pbi visual bind revenue_card --page overview --field "Sales[Total Revenue]"
pbi visual bind sales_by_region --page overview \
    --category "Geo[Region]" --value "Sales[Amount]"

# 5. Apply theme (power-bi-themes skill)
pbi report set-theme --file brand-colors.json

# 6. Validate (this skill)
pbi report validate

モデルとレポートの組み合わせ

pbi-cli は、セマンティックモデルレイヤーとレポートレイヤーの両方に対応しています。

# Model layer (requires pbi connect)
pbi connect
pbi measure create Sales "Total Revenue" "SUM(Sales[Amount])"

# Report layer (no connection needed)
pbi report create . --name "Sales"
pbi visual add --page overview --type card --name rev_card
pbi visual bind rev_card --page overview --field "Sales[Total Revenue]"

関連スキル

スキル	使用する場面
power-bi-visuals	ビジュアルの追加、バインド、更新、削除
power-bi-pages	ページやブックマークの追加、削除、設定
power-bi-themes	テーマ、条件付き書式
power-bi-filters	ページおよびビジュアルのフィルター

JSON 出力

pbi --json report info
pbi --json report validate

---

注意点

• report validate は Desktop が開けない PBIR でも成功します： 検証で確認するのは JSON 構造と必須ファイルのみです。データセットのバインド、スキーマ URL のバージョン、ビジュアルの queryState の整合性は検証されません。検証に成功した後、Desktop で「レポートを開けません」と表示されるのは、既知の落とし穴です。
• --dataset-path は CWD ではなく .Report フォルダーからの相対パスです： ../Sales.Dataset を指定すると作成時には正しく解決されますが、後で .Report フォルダーを移動すると、バインドが気付かないうちに壊れます。安定したワークスペース構成を使用するか、CI では絶対パスを指定してください。
• pbi report reload は、フォーカスがあるウィンドウにキーボードショートカットを送信します： リロードの実行時にユーザーが別のアプリで入力していると、キー入力がそのアプリに送られます。リロードは一連の処理の最後にのみ実行し、ユーザーには別のアプリに切り替えないよう伝えてください。
• .pbip への report convert では、セマンティックモデルはバンドルされません： データセットをパスで参照する .pbip のシェルが生成されます。.SemanticModel ディレクトリも同梱せずに生成されたフォルダーを配布すると、開いたときに「データセットが見つかりません」というエラーが発生します。
• PBIR のスキーマバージョンはプロジェクト単位ではなく、ファイル単位で固定されます： 異なるバージョンの Desktop で編集されたファイルを混在させると（例：2026 年 3 月ビルドで編集したページと、2026 年 1 月ビルドで編集したページ）、一方では検証に失敗し、もう一方では成功することがあります。必ずプロジェクト全体をまとめてアップグレードしてください。
• --no-sync が適用されるのは、指定したコマンドグループのみです： pbi visual --no-sync add ... の後に pbi report set-background ... を実行すると、2 つ目のコマンドの後も同期されます。一連の処理で使用するすべてのグループに --no-sync を指定してください。