power-bi-pages

Power BI ページスキル

PBIR レポートのページを管理します。ページは definition/pages/ 内のフォルダーで、page.json ファイルと visuals/ ディレクトリが含まれます。Power BI Desktop への接続は必要ありません。

ページの一覧表示と確認

# List all pages with display names, order, and visibility
pbi report list-pages

# Get full details of a specific page
pbi report get-page page_abc123

get-page が返す情報：

• name、display_name、ordinal（並べ替え順）
• width、height（キャンバスサイズ。単位はピクセル）
• display_option（例："FitToPage"）
• visual_count — ページ上のビジュアル数
• is_hidden — ページがナビゲーションウィンドウで非表示かどうか
• page_type — "Default" または "Drillthrough"
• filter_config — ページレベルのフィルター設定（ある場合）
• visual_interactions — カスタムのビジュアル操作ルール（ある場合）
• page_binding — ドリルスルーのパラメーター定義（ドリルスルーページの場合）

ページの追加

# Add with display name (folder name auto-generated)
pbi report add-page --display-name "Executive Overview"

# Custom folder name and canvas size
pbi report add-page --display-name "Details" --name detail_page \
    --width 1920 --height 1080

既定のキャンバスサイズは 1280x720（標準の 16:9）です。一般的な代替サイズ：

• 1920x1080 — フル HD
• 1280x960 — 4:3
• モバイルまたはダッシュボードのレイアウト向けのカスタムサイズ

ページの削除

# Delete a page and all its visuals
pbi report delete-page page_abc123

ビジュアルのすべてのサブディレクトリを含む、ページフォルダー全体が削除されます。

ページの背景

# Set a solid background colour
pbi report set-background page_abc123 --color "#F5F5F5"

ページの表示設定

ページをレポートのナビゲーションウィンドウに表示するかどうかを設定します。

# Hide a page (useful for drillthrough or tooltip pages)
pbi report set-visibility page_abc123 --hidden

# Show a hidden page
pbi report set-visibility page_abc123 --visible

ブックマーク

ブックマークにはページレベルの状態（フィルター、表示設定、スクロール位置）が保存されます。 definition/bookmarks/ に格納されます。

# List all bookmarks in the report
pbi bookmarks list

# Get details of a specific bookmark
pbi bookmarks get "My Bookmark"

# Add a new bookmark
pbi bookmarks add "Executive View"

# Delete a bookmark
pbi bookmarks delete "Old Bookmark"

# Toggle bookmark visibility
pbi bookmarks set-visibility "Draft View" --hidden

ドリルスルーページ

ドリルスルーページには、ドリルスルーパラメーターを定義する pageBinding フィールドが page.json にあります。ドリルスルーページで get-page を呼び出すと、page_binding フィールドに、パラメーター名、バインドされたフィルター、フィールド式を含むバインド定義全体が返されます。通常のページでは null が返されます。

ドリルスルーページを作成するには、ページを追加してから Power BI Desktop でドリルスルーとして設定します（PBIR のドリルスルー設定は CLI ではまだサポートされていません。CLI ではドリルスルー設定の読み取りと報告ができます）。

ワークフロー：レポートページを設定する

# 1. Add pages in order
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Sales Detail" --name sales_detail
pbi report add-page --display-name "Regional Drillthrough" --name region_drill

# 2. Hide the drillthrough page from navigation
pbi report set-visibility region_drill --hidden

# 3. Set backgrounds
pbi report set-background overview --color "#FAFAFA"

# 4. Verify the setup
pbi report list-pages

パスの解決

ページコマンドは、親の pbi report グループからレポートパスを引き継ぎます。

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

自動同期の抑制（--no-sync）

既定では、書き込みコマンドを実行するたびに Power BI Desktop と自動同期されます。複数のページを続けて設定すると、ページごとに Desktop が再読み込みされます。

report コマンドグループで --no-sync を使うと、ページの変更をまとめて適用できます。その後、最後に pbi report reload を一度呼び出します。

# Suppress sync while setting up pages
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync add-page --display-name "Details" --name details
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report --no-sync set-background details --color "#F2F2F2"

# Single reload when all page setup is done
pbi report reload

JSON 出力

pbi --json report list-pages
pbi --json report get-page page_abc123
pbi --json bookmarks list

---

注意点

• delete-page は取り消しできず、ビジュアルを含むフォルダー全体を削除します： ゴミ箱も、元に戻す機能もありません。そのページにほかの場所に複製されていない固有のビジュアルがある場合、それらは失われます。削除する前に、必ず pbi report export-tmdl を実行するか、Git にコミットしてください。
• set-visibility --hidden を設定しても、公開済みレポートの URL からページは非表示になりません： ディープリンク /reports/{id}/{pageId} を知っている人は、引き続きページを読み込めます。機密性の高い下書きページについては、ワークスペースのロールも制限してください。表示設定は UX のためのフラグであり、セキュリティ境界ではありません。
• get-page に pageBinding が表示されるドリルスルーページは、CLI ではまだ作成できません： 読み取りや一覧表示はできますが、バインディングは Desktop で設定する必要があります。Desktop を介して往復すると、無関係なページ設定が再フォーマットされることがあります。コミットする前に差分を確認してください。
• add-page の序数は、見た目上の末尾ではなく、次に大きい値から自動で割り当てられます： 以前のページが削除されていると、新しい序数がユーザーの認識する順序と衝突することがあります。pbi report list-pages を使って、表示順を確認してください。
• ブックマークはビジュアルの状態を名前ではなくビジュアル ID で保存します： ブックマークの保存後にビジュアルの名前を変更すると、ブックマークは古い ID を参照したままになります。ブックマークは読み込まれますが、名前を変更したビジュアルには反映されません。名前を変更したら、必ずブックマークを作り直してください。
• 既定のページサイズ 1280x720 は Desktop では問題ありませんが、モバイルでは崩れます： Desktop では既定で FitToPage でレンダリングされます。スマートフォンの Service では、スマートフォン用レイアウトが定義されていればそれが使われ、なければコンテンツが切り取られます。モバイルでの利用が想定されるレポートでは、必ずスマートフォン用レイアウトを定義するか、キャンバスの幅を最大 1080 に設定してください。