power-bi-visuals

Power BI ビジュアルスキル

PBIR レポートページでビジュアルを作成、管理します。Power BI Desktop への接続は不要です。これらのコマンドは JSON ファイルを直接操作します。

ビジュアルの追加

# Add by alias (pbi-cli resolves to the PBIR type)
pbi visual add --page page_abc123 --type bar
pbi visual add --page page_abc123 --type card --name "Revenue Card"

# Custom position and size (pixels)
pbi visual add --page page_abc123 --type scatter \
    --x 50 --y 400 --width 600 --height 350

# Named visual for easy reference
pbi visual add --page page_abc123 --type combo --name sales_combo

各ビジュアルは、ページの visuals/ ディレクトリ内に visual.json ファイルを含むフォルダーとして作成されます。テンプレートには、選択した種類に応じた正しいスキーマ URL と queryState ロールが含まれます。

データのバインド

ビジュアルは空の状態で作成されます。Table[Column] 表記を使って visual bind でセマンティックモデルに接続します。バインドのオプションはビジュアルの種類によって異なります。下の種類別一覧を参照してください。

# Bar chart: category axis + value
pbi visual bind mybar --page p1 \
    --category "Geography[Region]" --value "Sales[Revenue]"

# Card: single field
pbi visual bind mycard --page p1 --field "Sales[Total Revenue]"

# Matrix: rows + values + optional column
pbi visual bind mymatrix --page p1 \
    --row "Product[Category]" --value "Sales[Amount]" --value "Sales[Quantity]"

# Scatter: X, Y, detail, optional size and legend
pbi visual bind myscatter --page p1 \
    --x "Sales[Quantity]" --y "Sales[Revenue]" --detail "Product[Name]"

# Combo chart: category + column series + line series
pbi visual bind mycombo --page p1 \
    --category "Calendar[Month]" --column "Sales[Revenue]" --line "Sales[Margin]"

# KPI: indicator + goal + trend axis
pbi visual bind mykpi --page p1 \
    --indicator "Sales[Revenue]" --goal "Sales[Target]" --trend "Calendar[Date]"

# Gauge: value + max/target
pbi visual bind mygauge --page p1 \
    --value "Sales[Revenue]" --max "Sales[Target]"

バインドでは ROLE_ALIASES を使用して、--value などの分かりやすい名前を PBIR のロール名（例：Y、Values、Data）に変換します。Measure と Column のどちらを使うかはロールから推定されます。value／indicator／goal／max ロールでは Measure 参照が作成され、category／row／detail ロールでは Column 参照が作成されます。必要に応じて --measure フラグで変更できます。

調査と更新

# List all visuals on a page
pbi visual list --page page_abc123

# Get full details of one visual
pbi visual get visual_def456 --page page_abc123

# Move, resize, or toggle visibility
pbi visual update vis1 --page p1 --width 600 --height 400
pbi visual update vis1 --page p1 --x 100 --y 200
pbi visual update vis1 --page p1 --hidden
pbi visual update vis1 --page p1 --visible

# Delete a visual
pbi visual delete visual_def456 --page page_abc123

コンテナーのプロパティ

ビジュアルコンテナー自体の枠線、背景、タイトルを設定します。

pbi visual set-container vis1 --page p1 --background "#F0F0F0"
pbi visual set-container vis1 --page p1 --border-color "#CCCCCC" --border-width 2
pbi visual set-container vis1 --page p1 --title "Sales by Region"

ビジュアル計算

ビジュアルのスコープ内で実行する DAX 計算を追加します。

pbi visual calc-add vis1 --page p1 --role Values \
    --name "RunningTotal" --expression "RUNNINGSUM([Revenue])"

pbi visual calc-list vis1 --page p1
pbi visual calc-delete vis1 --page p1 --name "RunningTotal"

一括操作

--type または --name-pattern でフィルターして、複数のビジュアルを一度に操作します。

# Find visuals matching criteria
pbi visual where --page overview --type barChart
pbi visual where --page overview --type kpi --y-min 300

# Bind the same field to ALL bar charts on a page
pbi visual bulk-bind --page overview --type barChart \
    --category "Date[Month]" --value "Sales[Revenue]"

# Resize all KPI cards
pbi visual bulk-update --page overview --type kpi --width 250 --height 120

# Hide all visuals matching a pattern
pbi visual bulk-update --page overview --name-pattern "Temp_*" --hidden

# Delete all placeholders
pbi visual bulk-delete --page overview --name-pattern "Placeholder_*"

where、bulk-bind、bulk-update、bulk-delete のフィルターオプション：

• --type -- PBIR のビジュアル種類またはエイリアス（例：barChart、bar）
• --name-pattern -- ビジュアル名に対する fnmatch グロブ（例：Chart_*）
• --x-min、--x-max、--y-min、--y-max -- 位置の範囲（ピクセル）

誤って多数の項目を操作しないよう、すべての一括コマンドでは --type または --name-pattern のいずれかを指定する必要があります。

サポート対象のビジュアル種類（32）

グラフ

Alias	PBIR Type	Bind Options
bar	barChart	--category, --value, --legend
line	lineChart	--category, --value, --legend
column	columnChart	--category, --value, --legend
area	areaChart	--category, --value, --legend
ribbon	ribbonChart	--category, --value, --legend
waterfall	waterfallChart	--category, --value, --breakdown
stacked_bar	stackedBarChart	--category, --value, --legend
clustered_bar	clusteredBarChart	--category, --value, --legend
clustered_column	clusteredColumnChart	--category, --value, --legend
scatter	scatterChart	--x, --y, --detail, --size, --legend
funnel	funnelChart	--category, --value
combo	lineStackedColumnComboChart	--category, --column, --line, --legend
donut / pie	donutChart	--category, --value, --legend
treemap	treemap	--category, --value

カードと KPI

エイリアス	PBIR タイプ	バインドオプション
card	card	--field
card_visual	cardVisual	--field（モダンカード）
card_new	cardNew	--field
multi_row_card	multiRowCard	--field
kpi	kpi	--indicator、--goal、--trend
gauge	gauge	--value、--max / --target

テーブル

エイリアス	PBIR タイプ	バインドオプション
table	tableEx	--value
matrix	pivotTable	--row、--value、--column

スライサー

エイリアス	PBIR タイプ	バインドオプション
slicer	slicer	--field
text_slicer	textSlicer	--field
list_slicer	listSlicer	--field
advanced_slicer	advancedSlicerVisual	--field（タイル／画像スライサー）

マップ

エイリアス	PBIR タイプ	バインドオプション
azure_map / map	azureMap	--category、--size

装飾とナビゲーション

エイリアス	PBIR タイプ	バインドオプション
action_button	actionButton	（データバインドなし）
image	image	（データバインドなし）
shape	shape	（データバインドなし）
textbox	textbox	（データバインドなし）
page_navigator	pageNavigator	（データバインドなし）

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

デフォルトでは、書き込みコマンドを実行するたびに Power BI Desktop が自動的に同期されます。ビジュアルを連続して追加またはバインドすると、そのたびに Desktop が再読み込みされます。

--no-sync を visual コマンドグループに指定すると、すべての変更をまとめて適用できます。その後、最後に pbi report reload を一度実行します。

# Suppress sync while building visuals
pbi visual --no-sync add --page overview --type card --name rev_card
pbi visual --no-sync bind rev_card --page overview --field "Sales[Total Revenue]"
pbi visual --no-sync add --page overview --type bar --name sales_bar
pbi visual --no-sync bind sales_bar --page overview --category "Product[Category]" --value "Sales[Revenue]"

# Single reload when all visuals are done
pbi report reload

JSON 出力

すべてのコマンドで、エージェントが利用するための --json を指定できます。

pbi --json visual list --page overview
pbi --json visual get vis1 --page overview
pbi --json visual where --page overview --type barChart

---

注意点

• visual bind は基になる TMDL オブジェクトではなく、ロールから Measure と Column を推測します： --value のようなロールは、常に Measure の参照を作成します。Sales[Revenue] が実際には列（メジャーではない）の場合、エラーは発生せず、ビジュアルには BLANK が表示されます。--measure を使うか、実際のメジャーに名前を変更してください。
• --type または --name-pattern を指定しない bulk-bind はブロックされますが、パターンが緩すぎると無関係なビジュアルも再バインドされます： --name-pattern "Chart_*" は Chart_Revenue、Chart_Margin、そして Chart_Drillthrough_Hidden に一致します。必ず先に pbi visual where でプレビューしてください。
• ビジュアルの位置 --x／--y は画面上のピクセルではなく、レポートデザイン上のピクセルです： 幅が 1280 のキャンバスで --x 1280 を指定すると、閲覧者の画面サイズに関係なく、ビジュアルは右端に配置されます。キャンバスの境界を越えて配置されたビジュアルは、警告なしで画面外に表示されます。
• calc-add によるビジュアル計算は、ビジュアルのスコープ内でメジャーの AFTER に実行されます： ビジュアル計算内でメジャーを参照すると、フィルター適用後の値が取得されます。メジャーであるかのように計算（たとえば SUMX 内で）を反復すると、計算はビジュアルのクエリスコープ内にしか存在しないため、予期しない結果になります。
• PBIR ビジュアルの name はフォルダー名であり、名前の変更には CLI フラグではなくファイルシステム上の移動が必要です： --name フラグが適用されるのは作成時のみです。その後の visual update では名前を変更できません。名前を変更するには、削除して再追加する（ビジュアル ID が失われます）か、ファイルシステムを直接編集してください。
• bulk-delete --name-pattern "Placeholder_*" は取り消せず、確認も求められません： 削除するたびにフォルダーが削除されるため、--no-sync と組み合わせると、気付く前に何十ものビジュアルを消してしまうことがあります。必ず最初に同じパターンで pbi visual where を実行してください。