powerbi-authoring-cli

更新チェック — セッションごとに 1 回（必須） このスキルがセッション内で最初に使用されたときは、続行する前に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code: check-updates スキルを呼び出します。
• Claude Code / Cowork / Cursor / Windsurf / Codex: ローカルとリモートの package.json バージョンを比較します。
• このセッションで既にチェックが実行されている場合はスキップしてください。

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を見つけるには: すべてのワークスペースを一覧表示し、その後、JMESPath フィルタリングを使用します
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を見つけるには: そのワークスペース内のその種類のすべてのアイテムを一覧表示し、その後、JMESPath フィルタリングを使用します

Power BI セマンティックモデル作成 — CLI スキル

目次

タスク	リファレンス	備考
Fabric のワークスペースとアイテムの検索	COMMON-CLI.md § Fabric のワークスペースとアイテムの検索	必須 — 最初にリンクを読む [名前からワークスペース ID を、または名前、アイテムの種類、ワークスペース ID からアイテム ID を検索するために必要です]
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric のトポロジと主要な概念	階層；Fabric 内での項目の検索
環境 URL	COMMON-CORE.md § 環境 URL	本番環境（パブリッククラウド）
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	対象が間違っていると 401；委任 ID とアプリ ID、およびトークンの対象
ツール選択の根拠	COMMON-CLI.md § ツール選択の根拠
認証レシピ	COMMON-CLI.md § 認証レシピ	az login のフロー、環境検出、トークンの取得、デバッグ
az rest を使った Fabric コントロールプレーン API	COMMON-CLI.md § az rest を使った Fabric コントロールプレーン API	必ず --resource を渡してください；ワークスペース／アイテムの操作、ページネーション、LRO パターンを含みます
curl を使った OneLake データアクセス	COMMON-CLI.md § curl を使った OneLake データアクセス	az rest ではなく curl を使用します（トークンの対象が異なります）
ジョブの実行（CLI）	COMMON-CLI.md § ジョブの実行	ノートブック／パイプラインの実行、セマンティックモデルの更新、ジョブの確認／キャンセル
OneLake ショートカット	COMMON-CLI.md § OneLake ショートカット	ショートカットの作成；ショートカットの一覧表示；ショートカットの削除
容量管理（CLI）	COMMON-CLI.md § 容量管理	容量の一覧表示；ワークスペースの容量への割り当て
複合レシピ	COMMON-CLI.md § 複合レシピ	ワークスペース→レイクハウス→ファイル、SQL エンドポイント→クエリ、ノートブック実行のエンドツーエンドレシピ
注意事項とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意事項とトラブルシューティング（CLI 固有）	az rest の対象、シェルのエスケープ、トークンの有効期限
クイックリファレンス	COMMON-CLI.md § クイックリファレンス	az rest のテンプレート；トークンの対象 ↔ CLI ツールの対応表
DAX クエリとメタデータの検出	powerbi-consumption-cli	読み取り専用の DAX クエリ；作成後の検証に使用します
ツールスタック	SKILL.md § ツールスタック	az rest（主要）、jq（JSON 解析）、base64 エンコーディング
認証と API の対象	SKILL.md § 認証と API の対象	2 つの対象：Fabric API と Power BI Datasets API
必須／推奨／回避	SKILL.md § 必須／推奨／回避	セマンティックモデル作成のガードレール
SemanticModel の定義とエンベロープ	ITEM-DEFINITIONS-CORE.md § SemanticModel	TMDL 形式；必須要素、エンベロープ構造、サポートマトリックス
TMDL ファイル構造と例	SKILL.md § TMDL ファイル構造	必須要素、最小コンテンツの例
TMDL CRUD（作成／取得／更新）	SKILL.md § セマンティックモデルの作成	作成 → 取得／ダウンロード → 更新；LRO を含むライフサイクル全体
作成範囲マトリックス	SKILL.md § 作成範囲マトリックス	Fabric API がサポートする内容と回避すべき内容
更新操作	SKILL.md § 更新操作	トリガー、キャンセル、履歴、スケジュール（Power BI API）
データソースとパラメーター	SKILL.md § データソースとパラメーター	データソースとパラメーターの取得／更新
アクセス許可	SKILL.md § アクセス許可	データセットのユーザー権限の付与／更新
デプロイメントパイプライン	SKILL.md § デプロイメントパイプライン	ステージの一覧表示、取得、ステージ間のデプロイ
エージェント型ワークフロー	SKILL.md § エージェント型ワークフロー	手順：検出 → 作成 → 確認 → 更新 → 検証
トラブルシューティング	SKILL.md § トラブルシューティング	一般的なエラーの表：LRO、認証、TMDL エンコーディング、更新
例	SKILL.md § 例	モデルの作成、定義のダウンロード、更新、デプロイ
プロパティと API の対応	semantic-model-properties-guide.md § プロパティと API の対応	各プロパティカテゴリを適切な API に対応付けます
所有者、ストレージモード、運用メタデータ	semantic-model-properties-guide.md § 所有者、ストレージモード	Power BI Datasets API のプロパティ
更新履歴の応答プロパティ	semantic-model-properties-guide.md § 更新履歴	更新詳細の応答フィールド
データソースの応答プロパティ	semantic-model-properties-guide.md § データソース	接続とゲートウェイのプロパティ
DirectQuery／LiveConnection の更新スケジュール	semantic-model-properties-guide.md § DQ の更新スケジュール	DirectQuery／LiveConnection のスケジュール設定
上流データフローへのリンク	semantic-model-properties-guide.md § 上流データフロー	データフローの依存関係プロパティ
テーブルごとのストレージモード	semantic-model-properties-guide.md § テーブルごとのストレージ	TMDL によるテーブルレベルのストレージモード
TMDL 構文ルール	tmdl-authoring-guide.md § TMDL 構文ルール	タブによるインデント、オブジェクト宣言、引用符のルール
モデリングのベストプラクティス	tmdl-authoring-guide.md § モデリングのベストプラクティス	命名規則、列のルール、メジャーと DAX のルール、書式文字列
リレーションシップ	tmdl-authoring-guide.md § リレーションシップ	リレーションシップの宣言、キーのルール
階層	tmdl-authoring-guide.md § 階層	階層の宣言とキーのルール
Direct Lake のガイドライン	tmdl-authoring-guide.md § Direct Lake のガイドライン	Direct Lake モードの構成と制約
計算テーブル	tmdl-authoring-guide.md § 計算テーブル	DAX ベースの計算テーブル定義
日付／カレンダーテーブル	tmdl-authoring-guide.md § 日付／カレンダーテーブル	カレンダーテーブルの設定とマーク付け
パラメーター	tmdl-authoring-guide.md § パラメーター	式ベースのパラメーター宣言
注釈	tmdl-authoring-guide.md § 注釈	モデルおよびオブジェクトレベルの注釈
TMDL ファイルのレイアウトとコアファイル	tmdl-advanced-features-guide.md § ファイルレイアウト	ディレクトリ構造、database.tmdl、model.tmdl
計算グループ	tmdl-advanced-features-guide.md § 計算グループ	計算グループのテーブルと項目
セキュリティロール	tmdl-advanced-features-guide.md § セキュリティロール	RLS／OLS ロールの定義
セキュリティロールのメンバーシップ	SKILL.md § セキュリティロールのメンバーシップ	RLS ロールのユーザーとグループの追加／一覧表示／削除（Power BI API）
翻訳／カルチャ	tmdl-advanced-features-guide.md § 翻訳／カルチャ	カルチャファイルによるローカライズ
パースペクティブ	tmdl-advanced-features-guide.md § パースペクティブ	サブセット表示のためのパースペクティブ定義
関数	tmdl-advanced-features-guide.md § 関数	モデル内のユーザー定義 DAX 関数
カレンダーオブジェクト	tmdl-advanced-features-guide.md § カレンダーオブジェクト	自動日付／時刻カレンダーテーブルのオブジェクト

---

ツールスタック

ツール	役割	インストール
az CLI	主要：Fabric と Power BI REST API の呼び出しには az rest を、認証には az login を使用します。	ほとんどの開発環境にプリインストールされています
jq	az rest の応答から JSON を解析します	プリインストール済み、または簡単にインストールできます
base64（Linux/macOS） / [Convert]::ToBase64String（PowerShell）	定義ペイロード用に TMDL ファイルの内容をエンコードします	標準搭載

エージェントによる確認 — 初回の操作前に確認してください：

az version 2>/dev/null || echo "INSTALL: https://learn.microsoft.com/cli/azure/install-azure-cli"

---

認証と API オーディエンス

このスキルでは、2 種類の異なる API オーディエンスを使用します。誤ったオーディエンスを使用すると、401 が返されます。

API	オーディエンス（--resource）	用途
Fabric Items API	https://api.fabric.microsoft.com	セマンティックモデル定義の作成／取得／更新／削除、項目の一覧表示、LRO のポーリング
Power BI Datasets API	https://analysis.windows.net/powerbi/api	更新、データソース、パラメーター、アクセス許可、デプロイ パイプライン

# Fabric Items API — semantic model definition operations
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels" \
  ...

# Power BI Datasets API — refresh, data sources, permissions
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/datasets/$DATASET_ID/refreshes" \
  ...

---

必須／推奨／回避

必ず行うこと

• TMDL を生成する前に、関連する TMDL リファレンスのセクションを読むこと — 最低限、TMDL 構文ルール と モデリングのベストプラクティス を読んでください。タスクにリレーションシップ、階層、計算グループ、セキュリティロール、または翻訳が含まれる場合は、tmdl-authoring-guide.md と tmdl-advanced-features-guide.md の該当するセクションも読んでください。記憶を頼りに TMDL を生成しないでください。
• az rest には必ず --resource を指定すること — 省略すると、エラーが通知されないまま認証に失敗します。上の表に従って、正しいオーディエンスを使用してください。
• Power BI Datasets API への --body 付き POST／PATCH／PUT 呼び出しには、必ず --headers "Content-Type=application/json" を指定すること — 省略すると、Unsupported Media Type エラーが発生します。
• updateDefinition にはすべての定義パーツ（変更したものと変更していないもの）を含めること — API は定義全体を置き換えるため、パーツを省略すると削除されます。
• updateDefinition のペイロードに .platform を含めないこと — これは Git 統合メタデータであり、エラーの原因になります。
• LRO が完了するまでポーリングすること — createItemWithDefinition、getDefinition、updateDefinition は、Operation-Id ヘッダーを伴う 202 Accepted を返します。終端状態になるまでポーリングしてください。
• TMDL の内容を Base64 エンコードすること — 定義パーツ内のすべての payload 値は Base64 エンコードする必要があります。
• 特殊文字を含む名前はシングルクォートで囲むこと — 空白、.、=、:、または ' を含む名前は、TMDL でシングルクォートで囲む必要があります。
• セマンティックモデルを作成する前に、ワークスペースに容量があることを確認すること — GET /v1/workspaces/{id} を呼び出して、capacityId を確認してください。

推奨事項

• 新しいセマンティックモデルでは、作成してから更新する方法よりも、createItemWithDefinition（単一の POST）を使用してください。
• TMSL よりもTMDL 形式を使用してください — TMDL はテキストベースで差分を確認しやすく、Fabric で推奨される形式です。
• TMDL テーブルファイルでは、列よりもメジャーを先に記述してください — TMDL の慣例に沿っています。
• 複雑な式の可読性を高めるため、複数行の DAX はトリプルバッククォートで囲んでください。
• 細かな変更は powerbi-modeling-mcp に任せてください — 個々のメジャー、列、またはリレーションシップを追加／変更する場合、MCP サーバーを使用する方が、定義全体を取得して更新するより効率的です。
• 更新前に定義を取得してください — 現在の定義を必ず取得してから変更し、POST で戻すことで、同時に行われた変更の上書きを防いでください。
• 作成後の検証には、powerbi-consumption-cli を相互参照してください — DAX クエリを実行して、メジャー、リレーションシップ、データを確認してください。

避けること

• 小規模な変更に updateDefinition を使用すること — 定義全体の往復は負荷が高いため、個々のオブジェクトの編集には powerbi-modeling-mcp を使用してください。
• レポートの作成 — このスキルではサポートされていません。レポートには別の定義形式（PBIR/PBIR-Legacy）が必要です。
• 新しいオブジェクトでの lineageTag — TMDL がリネージタグを自動生成するため、手動で追加すると競合が発生します。
• TMDL での // コメント — サポートされていません。代わりに /// の説明を使用してください。
• TMDL での description プロパティ — 代わりに、オブジェクトの上に /// 構文を使用してください。
• ワークスペース／アイテム ID のハードコード — REST API を使用して動的に解決してください（COMMON-CLI.md § Fabric でのワークスペースとアイテムの検索を参照）。
• updateDefinition で変更部分だけを送信すること — API は定義全体を置き換えるため、不足している部分は削除されます。

---

TMDL ファイル構造

定義エンベロープ全体とパーツパスについては、ITEM-DEFINITIONS-CORE.md § SemanticModelを参照してください。

createItemWithDefinition と updateDefinition に必要な TMDL パーツ：

パーツパス	内容	必須
definition.pbism	セマンティックモデルの接続設定	はい
definition/database.tmdl	データベースのプロパティ（互換性レベル）	はい
definition/model.tmdl	モデルのプロパティ（カルチャ、既定の集計方法）	はい
definition/tables/<TableName>.tmdl	テーブルごとの列、メジャー、パーティション	はい（1 つ以上）

重要：updateDefinition には、変更したものと変更していないものを含め、すべてのパーツを含める必要があります。API は定義全体を置き換えます。更新ペイロードには .platform を絶対に含めないでください。

TMDL の構文規則、命名規則、モデリングのベストプラクティスについては、tmdl-authoring-guide.mdを参照してください。

---

TMDL コンテンツの最小例

definition.pbism

{
    "version": "4.2",
    "settings": {
        "qnaEnabled": true
    }
}

database.tmdl

database
	compatibilityLevel: 1702
	compatibilityMode: powerBI

model.tmdl

model Model
	culture: en-US
	defaultPowerBIDataSourceVersion: powerBI_V3
	discourageImplicitMeasures

注：Import モードのモデルには defaultPowerBIDataSourceVersion: powerBI_V3 が必要です。これがない場合、API は Import from JSON supported for V3 models only を返します。

Import モードのテーブル

table Customer

	/// Total number of customers
	measure '# Customers' = COUNTROWS(Customer)
		formatString: #,##0

	column CustomerId
		dataType: int64
		isHidden
		isKey
		summarizeBy: none
		sourceColumn: CustomerId

	column 'Customer Name'
		dataType: string
		sourceColumn: CustomerName

	partition Customer = m
		mode: import
		source =
			let
				Source = Sql.Database(#"Server", #"Database"),
				Customer = Source{[Schema="dbo", Item="Customer"]}[Data]
			in
				Customer

Direct Lake テーブル

expression DL_Lakehouse =
	let
		Source = AzureStorage.DataLake("https://onelake.dfs.fabric.microsoft.com/<WorkspaceId>/<LakehouseId>", [HierarchicalNavigation=true])
	in
		Source

table Sales

	/// Total revenue
	measure 'Total Sales' = ```
			SUMX(
				Sales,
				Sales[Quantity] * Sales[UnitPrice]
			)
			```
		formatString: \$#,##0.00

	column SalesKey
		dataType: int64
		isHidden
		isKey
		summarizeBy: none
		sourceColumn: sales_key

	column Quantity
		dataType: int64
		sourceColumn: quantity

	column UnitPrice
		dataType: decimal
		summarizeBy: none
		sourceColumn: unit_price

	partition Sales = entity
		mode: directLake
		source
			entityName: Sales
			schemaName: dbo
			expressionSource: DL_Lakehouse

---

セマンティックモデルの作成

ライフサイクル全体：TMDL を作成 → base64 エンコード → ペイロードを構築 → POST → LRO をポーリング。

COMMON-CLI.md § アイテム CRUD 操作およびITEM-DEFINITIONS-CORE.md § 定義エンベロープに従ってください。

WS_ID="<workspaceId>"

# 1. Base64-encode each TMDL file
PBISM=$(base64 -w 0 < definition.pbism)
DB=$(base64 -w 0 < definition/database.tmdl)
MODEL=$(base64 -w 0 < definition/model.tmdl)
TABLE=$(base64 -w 0 < definition/tables/Customer.tmdl)

# 2. Construct payload and create — use --verbose to capture HTTP status and LRO headers
cat > /tmp/body.json << EOF
{
  "displayName": "MySalesModel",
  "definition": {
    "format": "TMDL",
    "parts": [
      {"path": "definition.pbism", "payload": "$PBISM", "payloadType": "InlineBase64"},
      {"path": "definition/database.tmdl", "payload": "$DB", "payloadType": "InlineBase64"},
      {"path": "definition/model.tmdl", "payload": "$MODEL", "payloadType": "InlineBase64"},
      {"path": "definition/tables/Customer.tmdl", "payload": "$TABLE", "payloadType": "InlineBase64"}
    ]
  }
}
EOF
az rest --method post --verbose \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

PowerShell — base64 -w 0 の代わりに [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("file")) を使用してください。

応答が 202 Accepted の場合は、COMMON-CLI.md § 長時間実行操作の LRO パターンを使用してポーリングしてください。

---

定義の取得／ダウンロード

バックアップ、移行、または調査のために TMDL 定義を取得します。getDefinition は POST です（GET ではありません）。

WS_ID="<workspaceId>"
MODEL_ID="<semanticModelId>"

# 1. Request definition — may return 200 (inline) or 202 (LRO)
RESPONSE=$(az rest --method post --verbose \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels/$MODEL_ID/getDefinition?format=TMDL" \
  --body '{}' \
  --output json 2>/dev/null)

# 2. If 202, poll the Location header URL until Succeeded, then GET /result

# 3. Decode each part
echo "$RESPONSE" | jq -r '.definition.parts[] | .path + " " + .payload' | \
while read -r path payload; do
  mkdir -p "$(dirname "$path")"
  echo "$payload" | base64 -d > "$path"
done

---

定義の更新

重要なルール：変更したものと変更していないものを含め、すべてのパーツを含める必要があります。.platform は絶対に含めないでください。API は定義全体を置き換えるため、省略したパーツは削除されます。

WS_ID="<workspaceId>"
MODEL_ID="<semanticModelId>"

# 1. Get current definition (see Get/Download Definition above)
# 2. Modify the relevant TMDL files
# 3. Re-encode ALL parts and POST

cat > /tmp/body.json << EOF
{
  "definition": {
    "format": "TMDL",
    "parts": [
      {"path": "definition.pbism", "payload": "$PBISM", "payloadType": "InlineBase64"},
      {"path": "definition/database.tmdl", "payload": "$DB", "payloadType": "InlineBase64"},
      {"path": "definition/model.tmdl", "payload": "$MODEL", "payloadType": "InlineBase64"},
      {"path": "definition/tables/Customer.tmdl", "payload": "$TABLE", "payloadType": "InlineBase64"}
    ]
  }
}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels/$MODEL_ID/updateDefinition" \
  --body @/tmp/body.json

定義を介して表示名または説明を更新するために .platform ファイルを含める必要がある場合に限り、?updateMetadata=true クエリパラメーターを使用してください。

---

作成範囲の一覧

操作	対応状況	方法
TMDL を使用したセマンティックモデルの作成	✅	定義とともに POST /v1/workspaces/{id}/semanticModels を実行
TMDL 定義の取得／ダウンロード	✅	POST .../semanticModels/{id}/getDefinition?format=TMDL
TMDL 定義全体の更新	✅	POST .../semanticModels/{id}/updateDefinition
セマンティックモデルの削除	✅	DELETE /v1/workspaces/{id}/semanticModels/{id}
データセットの更新	✅	Power BI Datasets API（フェーズ 4）
単一のメジャーまたは列の追加／変更	⚠️ powerbi-modeling-mcp にルーティング	定義全体の取得と再適用は非効率です
レポートの作成	❌	対象外 — 別の定義形式（PBIR）を使用します

---

更新操作

すべての更新操作では、Power BI Datasets API のオーディエンス（https://analysis.windows.net/powerbi/api）を使用します。

WS_ID="<workspaceId>"
DATASET_ID="<semanticModelId>"
PBI="https://api.powerbi.com/v1.0/myorg"

# Trigger full refresh
cat > /tmp/body.json << 'EOF'
{"notifyOption": "NoNotification"}
EOF
az rest --method post --verbose \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshes" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

# Get refresh history (latest first)
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshes?\$top=5"

# Cancel an in-progress refresh
az rest --method delete \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshes/<refreshId>"

# Get refresh schedule
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshSchedule"

# Update refresh schedule
cat > /tmp/body.json << 'EOF'
{
  "value": {
    "enabled": true,
    "days": ["Monday", "Wednesday", "Friday"],
    "times": ["02:00", "14:00"],
    "localTimeZoneId": "UTC"
  }
}
EOF
az rest --method patch \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshSchedule" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

---

データソースとパラメーター

# Get data sources for a dataset
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/datasources"

# Get parameters
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/parameters"

# Update parameters
cat > /tmp/body.json << 'EOF'
{
  "updateDetails": [
    {"name": "Server", "newValue": "newserver.database.windows.net"},
    {"name": "Database", "newValue": "ProductionDB"}
  ]
}
EOF
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/Default.UpdateParameters" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

パラメーターまたはデータソースの資格情報を更新した後、変更を反映するには更新を実行してください。

---

アクセス許可

# List dataset users
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users"

# Grant dataset permissions to a user
cat > /tmp/body.json << 'EOF'
{
  "identifier": "[email protected]",
  "principalType": "User",
  "datasetUserAccessRight": "Read"
}
EOF
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

# Update existing user permissions
cat > /tmp/body.json << 'EOF'
{
  "identifier": "[email protected]",
  "principalType": "User",
  "datasetUserAccessRight": "ReadReshare"
}
EOF
az rest --method put \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

アクセス許可レベル：Read、ReadReshare、ReadExplore、ReadReshareExplore。

---

セキュリティロールのメンバーシップ

TMDL で RLS／OLS ロールを定義した後（セキュリティロールを参照）、Power BI Datasets API を使用してユーザーとグループをそれらのロールに割り当てます。

PBI="https://api.powerbi.com/v1.0/myorg"

# List members of a security role
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  | jq '[.value[] | select(.datasetUserAccessRight == "Read" and .roles != null)]'

# Add a user to a security role
cat > /tmp/body.json << 'EOF'
{
  "identifier": "[email protected]",
  "principalType": "User",
  "datasetUserAccessRight": "Read",
  "roles": ["SalesRegion"]
}
EOF
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

# Add a security group to a role
cat > /tmp/body.json << 'EOF'
{
  "identifier": "<group-object-id>",
  "principalType": "Group",
  "datasetUserAccessRight": "Read",
  "roles": ["SalesRegion"]
}
EOF
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

# Update role membership (e.g., move user to a different role)
cat > /tmp/body.json << 'EOF'
{
  "identifier": "[email protected]",
  "principalType": "User",
  "datasetUserAccessRight": "Read",
  "roles": ["EuropeOnly"]
}
EOF
az rest --method put \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/users" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

roles 配列には、セマンティックモデルの TMDL で定義されたロール名と一致する 1 つ以上のロール名を指定します。ユーザー／グループには、データセットに対する少なくとも Read アクセス許可も必要です。principalType には User、Group、または App を指定できます。

---

デプロイパイプライン

デプロイパイプラインでは、Fabric API のオーディエンス（https://api.fabric.microsoft.com）を使用します。

FABRIC="https://api.fabric.microsoft.com/v1"

# List deployment pipelines
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "$FABRIC/deploymentPipelines"

# Get pipeline stages
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "$FABRIC/deploymentPipelines/<pipelineId>/stages"

# Deploy from one stage to the next (e.g., Dev → Test)
cat > /tmp/body.json << 'EOF'
{
  "sourceStageOrder": 0,
  "targetStageOrder": 1,
  "items": [
    {
      "sourceItemId": "<semanticModelId>",
      "itemType": "SemanticModel"
    }
  ],
  "options": {
    "allowCreateArtifact": true,
    "allowOverwriteArtifact": true
  }
}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "$FABRIC/deploymentPipelines/<pipelineId>/deploy" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

ステージ内のすべての項目をデプロイするには、items 配列を省略してください。デプロイ呼び出しは 202 Accepted を返します。LRO パターンを使用してポーリングしてください。

---

エージェント型ワークフロー

ツール選択の優先順位

1. powerbi-modeling-mcp が利用可能 → 細かなオブジェクト変更（メジャー、列、リレーションシップ）には MCP ツールを使用します
2. MCP は利用できないが、TMDL ファイルは利用可能 → TMDL ファイルを直接編集し、az rest updateDefinition でデプロイします
3. MCP は利用できず、ワークスペースのみ利用可能 → このスキルを使用します：getDefinition → TMDL を編集 → updateDefinition

ワークフローの手順

1. ワークスペースを検出 → ワークスペースを一覧表示し、名前で対象を検索します（COMMON-CLI.md § Fabric でワークスペースと項目を検索するを参照）
2. セマンティックモデルを一覧表示 → GET /v1/workspaces/{id}/semanticModels を実行し、既存のモデルを検索するか、名前を使用できることを確認します
3. ソーススキーマを分析 → SQL、DAX、または Lakehouse のメタデータを使用してソーステーブル／列を調査し、スター スキーマの設計に役立てます
4. スター スキーマを設計 → ファクトテーブルとディメンションテーブルを特定し、リレーションシップのキーを定義して、メジャーを計画します
5. TMDL ファイルを作成 → 最小限の TMDL コンテンツ例とtmdl-authoring-guide.mdに従って、definition.pbism、database.tmdl、model.tmdl、およびテーブルファイルを作成します
6. リレーションシップを作成 → 依存するメジャーを作成する前に、テーブルの TMDL ファイルで定義します
7. メジャーを作成 → 集計可能な値すべてに formatString を指定して、明示的なメジャーを追加します
8. デプロイ → すべての部分を base64 エンコードし、POST createItemWithDefinition を実行します（セマンティックモデルの作成を参照）
9. 検証 → 検証チェックを実行します（以下を参照）
10. 更新 → 更新操作を使用して、データセットの更新を実行します
11. DAX で検証 → powerbi-consumption-cli を使用して、デプロイ済みモデルに対する DAX クエリを実行します

作成後の検証

• TMDL の構造 — 必須のパーツがすべて存在することを確認します（definition.pbism、database.tmdl、model.tmdl、テーブルが 1 つ以上）
• メジャーのテスト — DAX を使用して各メジャーに対し EVALUATE { [Measure Name] } を実行します
• リレーションシップの検証 — カーディナリティ、クロスフィルターの方向、両側の dataType が一致していることを確認します
• 列の検証 — sourceColumn のマッピングと dataType がソーススキーマと一致していることを確認します
• 重複の確認 — メジャー名や孤立したオブジェクトに重複がないことを確認します

---

トラブルシューティング

早期中断ルール：getDefinition が 404 EntityNotFound を返し（一覧表示／GET が可能なアイテムに対して）、かつ Power BI の更新 API が "identity None" とともに 403 Forbidden を返す場合は、すぐに再試行を中止してください。ユーザーのワークスペースでのロールは、ほぼ確実に Viewer のみです。GET /v1/workspaces/{id}/roleAssignments を呼び出して確認してください。それも 403 InsufficientWorkspaceRole を返す場合は、Contributor 以上のロールが必要であることをユーザーに伝えてください。異なる URL 形式、エンドポイント、パラメーターで再試行してはいけません。問題は API の使用方法ではなく、権限です。

症状	原因	対処方法
Power BI API で "identity None" とともに 403 Forbidden が発生する	ユーザーのロールが Viewer です。更新、データソース、権限の各 API には Contributor 以上が必要です	すぐに中止してください。 ワークスペースで Contributor／Member／Admin ロールを申請するようユーザーに依頼します
アイテムが一覧に存在するのに、getDefinition で 404 EntityNotFound が発生する	権限不足が 404 に見せかけられています。getDefinition には Contributor 以上が必要です	まずワークスペースのロールを確認します。異なる URL 形式で再試行してはいけません
roleAssignments で 403 InsufficientWorkspaceRole が発生する	ユーザーのワークスペースでのロールが Viewer です	Viewer ロールであることが確認されます。すべての作成操作とほとんどの読み取り操作がブロックされます
Fabric API で 401 Unauthorized が発生する	--resource が誤っているか、指定されていません	--resource "https://api.fabric.microsoft.com" を使用します
Power BI API で 401 Unauthorized が発生する	オーディエンスが誤っています	--resource "https://analysis.windows.net/powerbi/api" を使用します
getDefinition で 411 Length Required が発生する	リクエスト本文がありません	--body '{}' を渡します。getDefinition は POST です
LRO のポーリングが完了しない	長時間の処理中にトークンの有効期限が切れました	ポーリングループ内でトークンを再取得し、Retry-After の間隔を長くします
202 Accepted が返るが、結果がない	LRO の完了まで追跡していません	Location ヘッダーの URL をポーリングし、Succeeded になったら /result を GET します
作成／更新時に TMDL 検証エラーが発生する	TMDL の内容に構文エラーがあります	tmdl-authoring-guide.md で TMDL のルールを確認し、エンコード前に検証します
updateDefinition 後にパーツが欠落する	変更したパーツのみを送信しました	更新ごとに、変更したパーツと変更していないパーツを含むすべてのパーツを含める必要があります
update 時に .platform を含むエラーが発生する	.platform はデフォルトでは受け付けられません	パーツから .platform を削除するか、?updateMetadata=true を使用します
Base64 デコード後の内容が文字化けする	エンコードが誤っているか、行が折り返されています	base64 -w 0（行折り返しなし）または [Convert]::ToBase64String() を使用します
データソースエラーで更新に失敗する	資格情報の有効期限が切れているか、パラメーターが誤っています	データソースとパラメーターを確認し、必要に応じて資格情報を更新します
デプロイメントパイプラインが失敗する	ワークスペースがステージに割り当てられていません	デプロイ前に、ワークスペースをパイプラインのステージに割り当てます
新しいオブジェクトで lineageTag が競合する	lineageTag を手動で追加しました	新しいオブジェクトから lineageTag を削除します。これは自動生成されます
メジャーのテスト時に DAX エラーが発生する	メジャー名の大文字と小文字が一致していません	DAX のメジャー名は大文字と小文字を区別するため、完全に一致させます
DAX を介して INFO.ROLES()／INFO.ROLEMEMBERSHIPS() を使用し、ロールのメンバーを取得しようとしている	DAX の INFO 関数はロールのメンバーシップデータを確実に返すとは限らず、空または不完全な結果を返すことがあります	代わりに Power BI REST API を使用します：GET /v1.0/myorg/groups/{workspaceId}/datasets/{datasetId}/users を呼び出し、roles フィールドでフィルターします（セキュリティロールのメンバーシップを参照）

---

例

TMDL からセマンティックモデルを作成する

WS_ID="<workspaceId>"

# Encode all TMDL files
PBISM=$(base64 -w 0 < definition.pbism)
DB=$(base64 -w 0 < definition/database.tmdl)
MODEL=$(base64 -w 0 < definition/model.tmdl)
CUSTOMER=$(base64 -w 0 < definition/tables/Customer.tmdl)
SALES=$(base64 -w 0 < definition/tables/Sales.tmdl)

cat > /tmp/body.json << EOF
{
  "displayName": "SalesModel",
  "definition": {
    "parts": [
      {"path": "definition.pbism", "payload": "$PBISM", "payloadType": "InlineBase64"},
      {"path": "definition/database.tmdl", "payload": "$DB", "payloadType": "InlineBase64"},
      {"path": "definition/model.tmdl", "payload": "$MODEL", "payloadType": "InlineBase64"},
      {"path": "definition/tables/Customer.tmdl", "payload": "$CUSTOMER", "payloadType": "InlineBase64"},
      {"path": "definition/tables/Sales.tmdl", "payload": "$SALES", "payloadType": "InlineBase64"}
    ]
  }
}
EOF
az rest --method post --verbose \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels" \
  --headers "Content-Type=application/json" \
  --body @/tmp/body.json

セマンティックモデル定義をダウンロードする

WS_ID="<workspaceId>"
MODEL_ID="<semanticModelId>"

# Get definition (may return 202 — follow LRO)
RESULT=$(az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/semanticModels/$MODEL_ID/getDefinition?format=TMDL" \
  --body '{}' --output json)

# Decode and save all parts
echo "$RESULT" | jq -r '.definition.parts[] | .path + "\t" + .payload' | \
while IFS=$'\t' read -r path payload; do
  mkdir -p "$(dirname "$path")"
  echo "$payload" | base64 -d > "$path"
  echo "Saved: $path"
done

更新を実行してステータスを確認する

WS_ID="<workspaceId>"
DATASET_ID="<semanticModelId>"
PBI="https://api.powerbi.com/v1.0/myorg"

# Trigger refresh
cat > /tmp/body.json << 'EOF'
{"type": "Full"}
EOF
az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshes" \
  --body @/tmp/body.json

# Check latest refresh status
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "$PBI/groups/$WS_ID/datasets/$DATASET_ID/refreshes?\$top=1"

パイプライン経由で本番環境にデプロイする

FABRIC="https://api.fabric.microsoft.com/v1"
PIPELINE_ID="<pipelineId>"

# Deploy from Test (stage 1) to Production (stage 2)
cat > /tmp/body.json << 'EOF'
{
  "sourceStageOrder": 1,
  "targetStageOrder": 2,
  "items": [
    {"sourceItemId": "<semanticModelId>", "itemType": "SemanticModel"}
  ],
  "options": {
    "allowCreateArtifact": true,
    "allowOverwriteArtifact": true
  }
}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "$FABRIC/deploymentPipelines/$PIPELINE_ID/deploy" \
  --body @/tmp/body.json