fabric-cli-powerbi

Fabric CLI Power BI の操作

fab CLI を使用して Power BI アイテム（セマンティックモデル、レポート、ダッシュボード）を操作するための専門的なガイダンスです。

このスキルを使用するタイミング

次のタスクに関係する場合、自動的に有効にしてください。

• セマンティックモデル（データセット）の操作 — 取得、エクスポート、更新、リフレッシュ
• レポートの管理 — エクスポート、複製、別のモデルへの再バインド
• セマンティックモデルに対する DAX クエリの実行
• リフレッシュスケジュールの管理と失敗のトラブルシューティング
• ゲートウェイとデータソースの構成
• TMDL（Tabular Model Definition Language）の操作

前提条件

• 基本的な CLI ガイダンスを確認するため、最初に fabric-cli-core スキルを読み込んでください
• ユーザーが認証済みである必要があります：fab auth status
• 対象アイテムに対する適切なワークスペース権限が必要です

自動化スクリプト

Power BI のタスクにすぐ使える Python スクリプトです。すべてのオプションを確認するには、各スクリプトを --help 付きで実行してください。

スクリプト	目的	使用方法
refresh_model.py	セマンティックモデルのリフレッシュを開始して監視します	python scripts/refresh_model.py <model> [--wait] [--timeout 300]
list_refresh_history.py	リフレッシュ履歴と失敗の詳細を表示します	python scripts/list_refresh_history.py <model> [--last N]
rebind_report.py	レポートを別のセマンティックモデルに再バインドします	python scripts/rebind_report.py <report> --model <new-model>

スクリプトは、このスキルの scripts/ フォルダーにあります。

1 - Power BI アイテムの種類

エンティティサフィックス	種類	説明
.SemanticModel	セマンティックモデル	Power BI データセット（表形式モデル）
.Report	レポート	Power BI レポート（視覚化）
.Dashboard	ダッシュボード	Power BI ダッシュボード（ピン留めされたタイル）
.Dataflow	データフロー	Power Query データフロー
.PaginatedReport	ページ分割レポート	RDL ベースのページ分割レポート

パスの例

# Semantic model
Production.Workspace/Sales.SemanticModel

# Report connected to model
Production.Workspace/SalesReport.Report

# Dashboard
Production.Workspace/ExecutiveDash.Dashboard

2 - セマンティックモデルの操作

モデル情報の取得

# Check if model exists
fab exists "ws.Workspace/Model.SemanticModel"

# Get model properties
fab get "ws.Workspace/Model.SemanticModel"

# Get model ID (needed for Power BI API calls)
fab get "ws.Workspace/Model.SemanticModel" -q "id"

# Get full definition (TMDL)
fab get "ws.Workspace/Model.SemanticModel" -q "definition"

モデルのエクスポート

# Export to local directory (PBIP format with TMDL)
fab export "ws.Workspace/Model.SemanticModel" -o ./exports -f

フォルダー構造が作成されます。

Model.SemanticModel/
├── .platform
├── definition.pbism
└── definition/
    ├── model.tmdl
    ├── tables/
    │   ├── Sales.tmdl
    │   └── Date.tmdl
    └── relationships.tmdl

モデルのインポート／更新

# Import from PBIP folder
fab import "ws.Workspace/Model.SemanticModel" -i ./exports/Model.SemanticModel -f

# Copy between workspaces
fab cp "Dev.Workspace/Model.SemanticModel" "Prod.Workspace/Model.SemanticModel" -f

3 - リフレッシュ操作

リフレッシュの開始

# Get IDs
WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')

# Trigger full refresh
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

# Check refresh status
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

拡張リフレッシュ（パーティションレベル）

# Refresh specific tables
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{
  "type": "Full",
  "commitMode": "transactional",
  "objects": [
    {"table": "Sales"},
    {"table": "Inventory"}
  ]
}'

# Refresh with retry
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{
  "type": "Full",
  "retryCount": 3
}'

リフレッシュスケジュール

# Get current schedule
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule"

# Set daily refresh at 6 AM UTC
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule" -X patch -i '{
  "enabled": true,
  "days": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
  "times": ["06:00"],
  "localTimeZoneId": "UTC"
}'

リフレッシュ失敗のトラブルシューティング

# Get refresh history
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes"

# Common failure patterns:
# - "credentials" → Update data source credentials
# - "gateway" → Check gateway status
# - "timeout" → Use enhanced refresh with smaller batches
# - "memory" → Optimize model or use incremental refresh

4 - DAX クエリの実行

セマンティックモデルに対して DAX クエリを実行します。

MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')

# Simple query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{"query": "EVALUATE VALUES(Date[Year])"}]
}'

# Aggregation query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE SUMMARIZECOLUMNS(Date[Year], \"Total\", SUM(Sales[Amount]))"
  }]
}'

# TOPN query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE TOPN(10, Product, [Total Sales], DESC)"
  }]
}'

# Query with parameters
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE FILTER(Sales, Sales[Year] = @Year)",
    "parameters": [{"name": "@Year", "value": "2024"}]
  }]
}'

5 - レポートの操作

レポート情報の取得

# Check exists
fab exists "ws.Workspace/Report.Report"

# Get properties
fab get "ws.Workspace/Report.Report"

# Get connected model
fab get "ws.Workspace/Report.Report" -q "definition.parts[?contains(path, 'definition.pbir')].payload | [0]"

レポートのエクスポート

# Export to PBIP format
fab export "ws.Workspace/Report.Report" -o ./exports -f

レポートの複製

# Copy within workspace
fab cp "ws.Workspace/Report.Report" "ws.Workspace/ReportCopy.Report" -f

# Copy to another workspace
fab cp "Dev.Workspace/Report.Report" "Prod.Workspace/Report.Report" -f

レポートを別のモデルに再バインド

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
REPORT_ID=$(fab get "ws.Workspace/Report.Report" -q "id" | tr -d '"')
NEW_MODEL_ID=$(fab get "ws.Workspace/NewModel.SemanticModel" -q "id" | tr -d '"')

fab api -A powerbi "groups/$WS_ID/reports/$REPORT_ID/Rebind" -X post -i "{
  \"datasetId\": \"$NEW_MODEL_ID\"
}"

レポートをファイルにエクスポート（PDF/PPTX）

# Export to PDF
fab api -A powerbi "groups/$WS_ID/reports/$REPORT_ID/ExportTo" -X post -i '{
  "format": "PDF"
}'

# Poll for completion, then download

6 - ゲートウェイの操作

ゲートウェイの一覧表示

# Tenant-level gateways (hidden entity)
fab ls .gateways

# Get gateway details
fab get ".gateways/MyGateway.Gateway"

データソースの管理

GATEWAY_ID=$(fab get ".gateways/MyGateway.Gateway" -q "id" | tr -d '"')

# List data sources on gateway
fab api -A powerbi "gateways/$GATEWAY_ID/datasources"

# Get data source status
fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID"

データソースの資格情報の更新

# Update credentials (basic auth example)
fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID" -X patch -i '{
  "credentialDetails": {
    "credentialType": "Basic",
    "credentials": "{\"credentialData\":[{\"name\":\"username\",\"value\":\"user\"},{\"name\":\"password\",\"value\":\"pass\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "Organizational"
  }
}'

7 - 所有権の引き継ぎ

セマンティックモデルの所有者が組織を離れた場合：

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')

# Take over semantic model ownership
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/Default.TakeOver" -X post

8 - 一般的なパターン

開発環境から本番環境へのデプロイ

#!/bin/bash
DEV_WS="Dev.Workspace"
PROD_WS="Prod.Workspace"

# 1. Export from dev
fab export "$DEV_WS/Sales.SemanticModel" -o ./deploy -f
fab export "$DEV_WS/SalesReport.Report" -o ./deploy -f

# 2. Import to prod
fab import "$PROD_WS/Sales.SemanticModel" -i ./deploy/Sales.SemanticModel -f
fab import "$PROD_WS/SalesReport.Report" -i ./deploy/SalesReport.Report -f

# 3. Trigger refresh
PROD_WS_ID=$(fab get "$PROD_WS" -q "id" | tr -d '"')
MODEL_ID=$(fab get "$PROD_WS/Sales.SemanticModel" -q "id" | tr -d '"')
fab api -A powerbi "groups/$PROD_WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

# 4. Verify
fab api -A powerbi "groups/$PROD_WS_ID/datasets/$MODEL_ID/refreshes?\$top=1" -q "value[0].status"

セマンティックモデルのバックアップ

# Export definition for version control
fab export "Prod.Workspace/Model.SemanticModel" -o ./backups/$(date +%Y%m%d) -f
git add ./backups/
git commit -m "Backup Model $(date +%Y-%m-%d)"

増分リフレッシュの設定

大規模なモデルでは、増分リフレッシュを使用します。

1. Power BI Desktop で RangeStart/RangeEnd パラメーターを設定します
2. ワークスペースに発行します
3. 最初のリフレッシュでパーティションが作成されます。

# Monitor partition creation
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=5"

9 - 安全に関するガイドライン

• リフレッシュ操作の前に、必ずワークスペースのコンテキストを確認してください
• 最初に開発環境でテストしてください — テストせずに本番環境をリフレッシュしないでください
• リフレッシュ所要時間を監視してください — 適切なタイムアウトを設定してください
• 大きな変更の前にバックアップしてください — 更新前に定義をエクスポートしてください
• 大規模なモデルでは拡張リフレッシュを使用してください — タイムアウトを回避できます

10 - 参考資料

詳しいパターンについては、次を参照してください。

• references/semantic-models.md — TMDL 操作の全般
• references/reports.md — レポートの管理
• references/refresh.md — リフレッシュのトラブルシューティング
• references/dax-queries.md — 高度な DAX パターン
• references/gateways.md — ゲートウェイの構成