powerbi-report-management

テレメトリ — 必須です。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: powerbi-report-management を含める必要があります（az rest の場合は --headers "x-ms-fabric-skill=powerbi-report-management"）。 fabric_lro やリトライを含む、すべての LRO ポーリングにも適用されます。スニペットでは省略されていますが、必ず追加してください。

重要な注意事項

1. ワークスペース名から ID を含むワークスペースの詳細を見つけるには、すべてのワークスペースを一覧表示し、その後 JMESPath でフィルタリングします
2. ワークスペース ID、項目の種類、項目名から ID を含む項目の詳細を見つけるには、そのワークスペース内の該当する種類の項目をすべて一覧表示し、その後 JMESPath でフィルタリングします

Power BI レポート管理

Fabric REST API に対して az rest を使用し、Microsoft Fabric ワークスペース内の Power BI レポートを管理します。このスキルでは、レポート項目とその PBIR 定義の CRUD ライフサイクル全体を扱います。

対象範囲：レポート項目の CRUD と定義管理のみです。レポートのレイアウト（ページ、ビジュアル、フィルター、書式設定）を作成するには、powerbi-report-authoring を使用してください。

境界：このスキルは、PBIR 定義を Fabric との間で転送します。PBIR コンテンツの作成は引き続き powerbi-report-authoring の担当です。

関連スキル

このスキルは、Power BI の作成機能を分担する 3 つのスキルのうちの 1 つです。 それぞれが単一の役割を担います。作業に適したスキルに振り分けてください。

スキル	担当	用途
powerbi-report-authoring	レポートコンテンツ（PBIR JSON の作成）	ページ、ビジュアル、フィルター、書式設定、テーマ、式、definition.pbir、version.json、report.json
powerbi-report-management（このスキル）	Fabric とのレポート転送	レポート項目の一覧表示、作成、取得、更新、削除。PBIR 定義のダウンロード／アップロード
セマンティックモデル作成スキル	セマンティックモデルの作成とデプロイ	メジャー／テーブル／リレーションシップの作成・編集、TMDL、セマンティックモデルの Fabric へのデプロイ

ローカルの .pbip を Fabric に公開する場合、このスキルを入口として使用します。ユーザーがローカルのセマンティックモデルもレポートと一緒に公開したい場合、このスキルは利用可能なセマンティックモデル作成スキルにモデルのデプロイを委任し、その後、生成された semanticModelId を解決してレポートに紐付けます。ローカルの .pbip の公開 ワークフローを参照してください。

ツールスタック

ツール	役割	インストール
az CLI	主なツール：Fabric REST API 呼び出しには az rest、認証には az login を使用します	ほとんどの開発環境にプリインストールされています
jq	JSON ペイロードの解析と構築	標準 CLI ツールです。COMMON-CLI.md § ツール選定の根拠を参照してください
base64	定義ペイロード用の PBIR ファイルコンテンツのエンコード／デコード	Linux／macOS では組み込みです。Windows では PowerShell の [Convert]::ToBase64String() ／ FromBase64String() を使用してください

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

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

認証

すべての呼び出しで Fabric API のオーディエンスを使用します。誤ったオーディエンスを使用すると 401 が返されます。

API	オーディエンス（--resource）
Fabric レポート項目 API	https://api.fabric.microsoft.com

共通の認証モデル、トークンのオーディエンス、ID の種類については、COMMON-CORE.md § 認証とトークンの取得を参照してください。

認証方法の詳しい手順（対話型、デバイスコード、サービスプリンシパル、マネージド ID）については、COMMON-CLI.md § 認証手順を参照してください。

ワークスペースとレポートの検索

共通パターン — ワークスペースと項目の解決、ページネーション、LRO ポーリングについては、共通スキルライブラリに記載されています。 以下の CRUD 操作を行う前に、COMMON-CLI.md § Fabric でのワークスペースと項目の検索をお読みください。

名前からレポート ID を解決する

COMMON-CLI.md に従ってワークスペース ID を取得したら、レポートを解決します：

REPORT_NAME="Sales Report"
REPORT_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --query "value[?displayName=='$REPORT_NAME'] | [0].id" \
  --output tsv)

例：CRUD 操作

レポートの一覧表示

ワークスペース内のすべてのレポートを返します。

• 権限：ワークスペースの閲覧者ロール
• スコープ：Workspace.Read.All または Workspace.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --query "value[].{name:displayName, id:id, description:description}" \
  --output table

continuationToken クエリパラメーターによるページネーションに対応しています。

レポートの取得（プロパティ）

特定のレポートのプロパティ（名前、説明、ID、ワークスペース、秘密度ラベル）を返します。

• 権限：レポートに対する読み取り権限
• スコープ：Report.Read.All または Report.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID"

レポート定義の取得

完全な PBIR 定義をダウンロードします。これは POST（GET ではありません）で、LRO に対応しています。

• 権限：レポートに対する読み取りおよび書き込み権限
• スコープ：Report.ReadWrite.All または Item.ReadWrite.All
• 制限事項：暗号化された秘密度ラベルが設定されたレポートではブロックされます

必ず format=PBIR を指定してください。このパラメーターを指定しない場合、古いレポートでは PBIR-Legacy 形式（単一の report.json ブロブ）が返されることがあります。このスキルはこの形式に対応していません。

RESPONSE=$(az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID/getDefinition?format=PBIR" \
  --verbose 2>&1)

# If 202 Accepted, extract operation ID and poll the LRO (see Long-Running Operations section)
# If 200 OK, the response contains the definition parts

形式の確認：定義を取得した後、definition.format == "PBIR" であることを確認してください。"PBIR-Legacy" の場合、このスキルはその形式に対応していません。

定義のパーツをローカルファイルにデコードする

注：getDefinition は 202 Accepted（LRO）を返すことがよくあります。デコードする前に、長時間実行操作のセクションを確認し、操作 ID を抽出して結果をポーリングしてください。

# After retrieving the definition (from 200 response or LRO result):
echo "$DEFINITION_JSON" | jq -r '.definition.parts[] | "\(.path)\t\(.payload)"' | \
  while IFS=$'\t' read -r path payload; do
    mkdir -p "$(dirname "./report-definition/$path")"
    echo "$payload" | base64 -d > "./report-definition/$path"
  done

レポートの作成（定義を含む）

PBIR 定義を含む新しいレポートを作成します。LRO に対応しています。

• 権限：ワークスペースの投稿者ロール
• スコープ：Report.ReadWrite.All または Item.ReadWrite.All

# Walk ./report-definition/ and build the parts[] array — every file under the
# directory is encoded and uploaded. Includes definition.pbir, report.json,
# version.json, pages/pages.json, every pages/<page>/page.json, and every
# pages/<page>/visuals/<visual>/visual.json.
PARTS=$(find ./report-definition -type f -not -name '.*' -not -name 'Thumbs.db' | while read -r file; do
  rel="${file#./report-definition/}"
  payload=$(base64 < "$file" | tr -d '\n')
  jq -nc --arg p "$rel" --arg b "$payload" \
    '{path:$p, payload:$b, payloadType:"InlineBase64"}'
done | jq -sc '.')

jq -n \
  --arg name "My New Report" \
  --arg desc "Created via Fabric API" \
  --argjson parts "$PARTS" \
  '{displayName:$name, description:$desc, definition:{parts:$parts}}' \
  > create-report.json

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --headers "Content-Type=application/json" \
  --body @create-report.json \
  --verbose 2>&1

PowerShell — ディレクトリを走査するには Get-ChildItem -Recurse -File を使用し、各ファイルをエンコードするには（base64 | tr -d '\n' の代わりに）[Convert]::ToBase64String([System.IO.File]::ReadAllBytes($_.FullName)) を使用してください。

重要：definition.pbir は常に必須です。上記のディレクトリ走査では ./report-definition/ 以下のすべてのファイルが自動的に含まれます。エンコードする前に、ローカルディレクトリが PBIR の完全なレイアウト（トップレベルのファイルに加え、すべての pages/<page>/page.json および pages/<page>/visuals/<visual>/visual.json ファイル）と一致していることを確認してください。

レポート定義の更新

定義全体を上書きします。これは POST で、LRO に対応しています。

• 権限：レポートに対する読み取りおよび書き込み権限
• スコープ：Report.ReadWrite.All または Item.ReadWrite.All

# Rebuild parts[] from ./report-definition/ after edits (same walk as Create).
PARTS=$(find ./report-definition -type f -not -name '.*' -not -name 'Thumbs.db' | while read -r file; do
  rel="${file#./report-definition/}"
  payload=$(base64 < "$file" | tr -d '\n')
  jq -nc --arg p "$rel" --arg b "$payload" \
    '{path:$p, payload:$b, payloadType:"InlineBase64"}'
done | jq -sc '.')

jq -n --argjson parts "$PARTS" \
  '{definition:{parts:$parts}}' \
  > update-definition.json

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID/updateDefinition" \
  --headers "Content-Type=application/json" \
  --body @update-definition.json \
  --verbose 2>&1

重大な注意：updateDefinition は定義全体を置き換えます。変更済みと未変更のものを含むすべてのパーツを含めてください。パーツを省略すると、そのパーツは削除されます。

オプションのクエリパラメーター ?updateMetadata=true を指定すると、.platform ファイルが含まれている場合に、そのファイルからアイテムのメタデータを更新します。

レポートの更新（プロパティ）

表示名や説明のみを更新します（定義は更新しません）。

• 権限：レポートに対する読み取りおよび書き込み権限
• スコープ：Report.ReadWrite.All または Item.ReadWrite.All

cat > update-report.json << 'EOF'
{
  "displayName": "Renamed Report",
  "description": "Updated description"
}
EOF

az rest --method patch \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID" \
  --headers "Content-Type=application/json" \
  --body @update-report.json

レポートの削除

レポートを削除します。ソフト削除（既定）と完全削除に対応しています。

• 権限：レポートに対する書き込み権限
• スコープ：Report.ReadWrite.All または Item.ReadWrite.All

# Soft delete (recoverable)
az rest --method delete \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID"

# Hard delete (permanent)
az rest --method delete \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID?hardDelete=true"

長時間実行操作（LRO）

Create Report、Get Report Definition、Update Report Definition は、すぐに結果を返す代わりに 202 Accepted を返す場合があります。詳細出力から x-ms-operation-id を取得し、COMMON-CLI.md § Long-Running Operations に従って、終端状態になるまでポーリングしてください。

競合する場合は、以下の管理固有のガードレールが一般的なパターンより優先されます。

⚠️ 202 を受け取った後、作成 POST を再試行しないでください。 202 Accepted レスポンスは、操作が受け付けられ、サーバー側で処理中である可能性が高いことを意味します。POST を再試行すると、重複が作成されるおそれがあります。

各試行で x-ms-operation-id ヘッダーを確実に取得するため、--verbose の出力は必ずファイルに書き込んでください。 これが操作を追跡する唯一の確実な方法です。メモリ内の文字列から正規表現で抽出する方法は、シェルやプラットフォームによって不安定です。取得したら、ほかの LRO 呼び出しと同様に、操作が完了するまでポーリングしてください。

# PowerShell — 操作 ID を確実に取得
az rest --method post ... --verbose 2>&1 | Out-File "$env:TEMP\lro-response.txt" -Encoding utf8
$opId = (Select-String -Path "$env:TEMP\lro-response.txt" -Pattern "x-ms-operation-id.*?'([a-f0-9-]+)'" | Select-Object -First 1).Matches.Groups[1].Value

最後の手段として、ファイルに書き込んでも操作 ID が失われた場合は、ワークスペース内のレポート一覧から作成されたレポートを特定してください。ただし、これは通常の手順にしないでください。

詳しくは、Long-Running Operations を参照してください。

PBIR 定義の構造

レポートでは PBIR 形式（JSON ファイルのフォルダー）を使用します。

Report/
├── definition.pbir                              # Semantic model reference (required)
├── definition/
│   ├── report.json                              # Report-level settings (required)
│   ├── version.json                             # Format version (required)
│   ├── pages/
│   │   ├── pages.json                           # Page listing (required)
│   │   ├── <pageId>/
│   │   │   ├── page.json                        # Page layout
│   │   │   ├── visuals/
│   │   │   │   ├── <visualId>/
│   │   │   │   │   ├── visual.json              # Visual config
│   │   │   │   │   ├── mobile.json              # Mobile layout (optional)
│   ├── bookmarks/                               # Bookmarks (optional)
├── StaticResources/                             # Custom themes, images (optional)

すべてのパーツは、"payloadType": "InlineBase64" を使用して API ペイロード内で base64 エンコードされます。

definition.pbir — セマンティックモデルの参照

Fabric API では、byPath ではなく byConnection を使用します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "semanticmodelid=<SemanticModelId>"
    }
  }
}

必須／推奨／回避

必須

• すべての PBIR コンテンツは、必ず powerbi-report-authoring スキルを通じて作成してください — これは最も重要なルールです。新しいレポートを作成する場合も、既存のレポートを変更する場合も、すべての PBIR ファイル（definition.pbir、report.json、version.json、pages.json、ページ構成、ビジュアル、フィルター、書式設定、テーマ、式）は powerbi-report-authoring を使用して作成する必要があります。正しい PBIR 構造、スキーマ、フィールド値については、そのガイダンスに従ってください。検証には CLI ツールを使用してください。記憶や推測に基づいて PBIR JSON を作成してはいけません。「単純な」ファイルである definition.pbir や version.json であっても同様です。このスキルは API の転送（ダウンロード、エンコード、アップロード）のみに使用します。PBIR コンテンツの作成には使用しません。
• az rest には必ず --resource "https://api.fabric.microsoft.com" を渡してください。省略すると、エラーが表示されずに認証が失敗します。
• getDefinition では必ず ?format=PBIR を指定してください。指定しない場合、古いレポートはこのスキルでサポートされていない PBIR-Legacy 形式で返されます。
• PBIR 形式のみを扱ってください。定義が "format": "PBIR-Legacy" で返された場合は処理を中止し、PBIR-Legacy はサポートされていないことをユーザーに伝えてください。
• updateDefinition には、変更したものと変更していないものを含むすべての定義パーツを含めてください。API は定義全体を置き換えるため、パーツを省略すると削除されます。
• すべてのパーツのペイロードを Base64 でエンコードしてください。すべての payload 値を Base64 でエンコードする必要があります。
• Fabric API では definition.pbir 内で byConnection を使用してください。byPath はローカル／Git シナリオ専用です。
• LRO が完了するまでポーリングしてください。Create、getDefinition、updateDefinition は 202 Accepted を返します。終端状態になるまでポーリングしてください。
• LRO 操作では必ず --verbose を使用してください。az rest は既定ではレスポンスヘッダーを表示しません。--verbose がないと、ポーリングに必要な x-ms-operation-id ヘッダーを取得できず、後から取得する方法もありません。
• 一時ファイルを削除してください。ワークフロー完了後、処理中に作成したローカルの一時ディレクトリやファイル（デコードした定義、JSON ペイロード）を削除してください。これらはサイズが大きく、ユーザーのマシンに蓄積する可能性があります。
• ターゲットモデルの解決後、セマンティックモデルのバインディングを検証してください。レポートのターゲットとなるセマンティックモデルが判明したら（利用可能なセマンティックモデル作成スキルを通じて新たにデプロイする場合も、既存のワークスペースモデルを選択する場合も）、その TMDL をダウンロードし、すべての PBIR バインディング（Entity、queryRef、nativeQueryRef、フィルターの Source／Entity 参照）を、モデルのテーブル名、列名、メジャー名と比較してください。これは両方の分岐に適用されます。引き継ぎデプロイであっても、発行時にモデルの名前が変更されたり変換されたりする可能性があるため、差分確認は必須です。モデルの構造が同等（同じ列／メジャー）で名前が異なる場合は、powerbi-report-authoring を通じて、テーブルで修飾されたすべてのバインディングを対応付け直してください。モデルの構造が同等でない場合は、再作成を試みる前にユーザーに確認してください。一致しないテーブル／列／メジャーを説明し、続行するかどうかを尋ねてください。
• ローカルでの編集は、既定ではローカルにとどめてください。ユーザーがローカルの .pbip レポートへの変更を依頼した場合は、ローカルファイルにのみ変更を適用してください。ユーザーがレポートの発行、アップロード、またはプッシュを明示的に依頼しない限り、Fabric に発行しないでください。レポートが以前 Fabric に発行されていた場合も、指示があるまでは、その後の編集をローカルのみとして扱ってください。ユーザーがローカルの .pbip の発行を依頼した場合は、ローカルの .pbip の発行のワークフローに従ってください。（a）最初に一度、ターゲットのワークスペースを確認する。（b）ローカルモデルを発行するか、既存のワークスペースモデルに接続するかを尋ねる。（c）モデルを発行する分岐では、現在のセッションでセマンティックモデル作成スキルを利用できるか確認し、利用できない場合は適切に対応する。（d）レポート自体について、新規作成するか既存のものを更新するかを確認する。

推奨

• 完全削除よりもソフト削除を優先してください。復元が可能になります。
• フィルタリングには、JMESPath の --query を指定した az rest を使用してください。組み込みの JSON 解析を利用でき、追加のツールは不要です。

避けるべきこと

• PBIR JSON を手書きしたり、直接構築したりすること — 新しいファイルの作成でも既存ファイルの変更でも、すべての PBIR コンテンツ（definition.pbir、report.json、version.json、ページ、ビジュアル、フィルター、書式設定、テーマ、式）は、必ず powerbi-report-authoring スキルを通じて作成してください。記憶や推測に基づいて PBIR JSON を構築してはいけません。「単純な」構造ファイルであっても同様です。例外はありません。
• PBIR-Legacy 形式 — PBIR-Legacy の定義を作成、読み取り、更新しないでください。サポートされているのは最新の PBIR 形式のみです。
• updateDefinition で変更した部分だけを送信すること — API は定義全体を置き換えるため、欠落した部分は削除されます。
• API ペイロードの definition.pbir で byPath を使用すること — ローカル/Git のシナリオでのみ機能します。
• ワークスペース ID やレポート ID をハードコードすること — List API を使って動的に解決してください。
• LRO のポーリングを省略すること — 定義の操作は非同期の場合があります。必ず 202 レスポンスを確認してください。
• getDefinition で ?format=PBIR を省略すること — 使用できない PBIR-Legacy 形式が返される場合があります。
• 202 を受信した後に作成 POST を再試行すること — 重複が作成されるおそれがあります。正しい復旧手順については、LRO のセクションを参照してください。

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

ローカルの .pbip を発行する

これは、ユーザーがローカルディスク上に .pbip（レポートと同階層の .SemanticModel）を持ち、そのレポートを Fabric ワークスペースに発行、アップロード、プッシュ、またはデプロイするよう依頼した場合の主なエントリーポイントです。

1. ソースがローカルの .pbip であることを検出します。 次のいずれかが該当します。

• 作業ディレクトリ内またはその上位に <Name>.pbip ファイルがある。
• <Name>.Report フォルダーと、同階層に <Name>.SemanticModel フォルダーがある。
• レポートの definition.pbir が、byConnection（API 形式）ではなく byPath（ローカル/Git 形式）を使用している。
• .pbi/ キャッシュフォルダーが存在する。

ソースがローカルの .pbip ではない場合（たとえば、レポートがすでに Fabric からダウンロードされており、byConnection の definition.pbir がある .Report フォルダーだけが存在する場合）は、代わりにFabric の既存レポートを変更するワークフローを使用してください。

2. 対象のワークスペースを一度確認します。 名前からワークスペース ID を解決して保存します（COMMON-CLI.mdを参照）。このワークスペースは、モデルのデプロイ（該当する場合）とレポートの発行の両方で使用します。別々のワークスペースに分けてはいけません。

3. セマンティックモデルについてユーザーに確認します。 明示的に質問してください。黙って選択してはいけません。

「ローカルのセマンティックモデルもこのワークスペースに発行しますか？ それとも、このレポートをワークスペース内の既存のセマンティックモデルに接続しますか？」

4a. 分岐：「ローカルモデルを発行する」。

• 現在のセッションでセマンティックモデル作成スキルが利用可能か確認します。
  • 利用可能 → そのワークフローに引き継ぎ、セマンティックモデルを作成または更新します。次の情報を渡します。対象のワークスペース ID、ローカルの .SemanticModel フォルダーパス（TMDL ソース）、希望するモデル表示名。そのスキルのワークフローが最終的な成功状態に達するまで待ってから、次に進んでください。
  • 利用不可 → このセッションではセマンティックモデル作成スキルが読み込まれておらず、それがないとローカルモデルを発行できないことをユーザーに伝えます。その後、分岐 4b（既存モデルへの接続）に切り替え、レポートをどのワークスペースモデルにバインドするかを再度確認します。

4b. 分岐：「ワークスペース内の既存モデルに接続する」。

• 対象のワークスペース内のセマンティックモデルを一覧表示し、対象モデルをユーザーに確認します。名前から semanticModelId を解決します。

5. semanticModelId を解決します。 どちらの分岐でも、レポートのバインド先として具体的なモデル ID が必要です。

• 4a の後：対象のワークスペース内のセマンティックモデルを一覧表示し、名前からデプロイしたばかりのモデルを探します（モデルスキルはワークスペース項目の一覧表示で確認しますが、ID は返しません）。
• 4b の後：すでに完了しています。 6. バインドを解決済みモデルに照らして検証します（両方の分岐に共通）。 モデルの TMDL をダウンロードし、MUST ターゲットモデルの解決後にセマンティックモデルのバインドを検証する に従ってバインドの差分を確認します。ローカルモデルを発行する分岐でも、モデルスキルがデプロイ中にテーブル名を変更したり、変換を適用したりする可能性があるため、この差分確認は必須です。差異があれば powerbi-report-authoring スキルで再マッピングします。構造的に大きく異なる場合は、再オーサリングの前にユーザーに確認します。

7. definition.pbir を byPath から byConnection に再バインドします。 powerbi-report-authoring を使って、次のように設定します。

"datasetReference": {
  "byConnection": {
    "connectionString": "semanticmodelid=<resolved-id>"
  }
}

Fabric API は byPath を拒否するため、ローカルソースを発行するたびにこの切り替えが必須です。

8. レポートを新規作成するか、既存のものを更新するかを決定します。 レポートの displayName は、既定で拡張子を除いた .pbip ファイル名にします（例：SalesDashboard.pbip → "SalesDashboard"）。既定値をユーザーに提示し、変更できるようにします。

• ターゲットワークスペースのレポート一覧を取得し、選択した displayName を検索します。
  • 見つからない場合 → 作成します。レポートの作成（定義を使用） に従います。
  • 見つかった場合 → 既存のレポートを上書きする（updateDefinition）、別の名前で発行する、またはキャンセルするかをユーザーに確認します。上書きする場合はレポート定義の更新に従います。

9. エンコードしてアップロードします。 既存の転送手順を実行します。PBIR のすべての部分を base64 エンコードし（スラッシュは / を使用）、parts ペイロードを作成して POST し、x-ms-operation-id を取得します（--verbose の出力はファイルに書き込みます）。その後、LRO を終端状態の成功までポーリングします。

10. フロー中に作成した一時ファイルをクリーンアップします。

レポート側の検証に関する注意：発行後にレポートが正しくレンダリングされることをプログラムで確実に確認する方法はありません。レポートは Fabric サービスの URL 上にあり、視覚的なレンダリングにはブラウザーセッションが必要です。ユーザーがブラウザーで確認できるよう、ワークスペースとレポートの URL を提示してください。

Fabric で既存のレポートを変更する

1. 認証 → COMMON-CLI.md § 認証レシピを参照してください。
2. ワークスペースの検索 → 名前からワークスペース ID を解決します。
3. レポートの一覧表示／検索 → 名前からレポート ID を解決します。
4. 定義のダウンロード → getDefinition?format=PBIR を実行 → LRO をポーリング → パーツをデコードしてローカルファイルに保存します。
5. PBIR コンテンツの作成 → すべての変更に powerbi-report-authoring スキルを使用します。 対象となるファイルはすべてです。definition.pbir、report.json、version.json、pages.json、ページ設定、ビジュアル、フィルター、書式設定、テーマ、式が含まれます。正しい構造、スキーマ、フィールド値については、そのガイダンスに従ってください。検証には CLI ツールを使用します。記憶や推測に基づいて PBIR JSON を作成しないでください。
6. 変更のアップロード → すべてのローカルファイルを base64 に再エンコード → 変更済みと未変更の両方を含むすべてのパーツを指定して updateDefinition を実行します。
7. クリーンアップ → ワークフロー中に作成した一時ローカルファイルとディレクトリをすべて削除します。

Fabric での新しいレポートの作成

1. 認証する → COMMON-CLI.md § 認証レシピを参照してください
2. ワークスペースを見つける → 名前からワークスペース ID を解決します
3. セマンティックモデルを解決する → definition.pbir の接続文字列に使用するセマンティックモデル ID とワークスペース名を見つけます
4. セマンティックモデルのバインドを検証する → 対象のセマンティックモデル定義（TMDL）をダウンロードし、すべての PBIR Entity、queryRef、nativeQueryRef、およびフィルター参照を対象のテーブル名／列名と照合します。名前が異なっていても構造が一致する場合は、テーブル修飾されたすべてのバインドを再マッピングします。モデルの構造が異なる場合は、続行する前にユーザーに確認します。一致しない箇所を説明し、該当するバインドを再作成するかどうか尋ねます
5. PBIR コンテンツを作成する → powerbi-report-authoring スキルを使用して、definition.pbir、report.json、version.json、pages.json、ページ設定、およびすべてのビジュアルを含む完全な PBIR 定義を最初から生成します。記憶や推測に頼って PBIR JSON を作成してはいけません
6. アップロードする → すべてのファイルを base64 にエンコードします → displayName とすべての定義パーツを指定して POST /reports を実行します
7. クリーンアップする → 一時的なローカルファイルを削除します

トラブルシューティング

エラー	原因	解決方法
401 Unauthorized	--resource の対象が誤っているか、指定されていません	常に --resource "https://api.fabric.microsoft.com" を指定してください
403 Forbidden	権限が不足しています	ワークスペースのロールを確認してください（書き込み操作には Contributor 以上が必要です）
404 Not Found	ワークスペースまたはレポート ID が誤っています	List API を使用して ID を再解決してください
CorruptedPayload	base64 の形式が正しくないか、PBIR JSON が無効です	ファイルを再エンコードし、エンコード前に JSON を検証してください
202 で結果が返らない	LRO のポーリングが完了まで行われていません	LRO のポーリングパターンを実装してください
OperationNotSupportedForItem	レポートに暗号化された秘密度ラベルが設定されています	暗号化されたレポートの定義は取得できません
ItemDisplayNameAlreadyInUse	ワークスペース内で名前が重複しています	一意の表示名を使用してください
format: "PBIR-Legacy"	PBIR がデフォルトになる前にレポートが作成されました	このスキルでは PBIR-Legacy はサポートされていません
発行後にビジュアルが空、またはデータが表示されない	PBIR のエンティティ名が、ワークスペースのセマンティックモデルのテーブル名（例：ローカル CSV のテーブル名とワークスペースのテーブル名）と一致していません	対象のセマンティックモデルの TMDL をダウンロードし、テーブル名を比較して、すべての Entity、queryRef、nativeQueryRef、およびフィルター参照を一致するように更新してください
すべてのファイルが含まれているのに、作成／更新時に MissingDefinitionParts が発生する	定義パーツのパスにバックスラッシュ（definition\report.json）が使用されています。Fabric API ではスラッシュが必要です。Windows では、path.join() はデフォルトでバックスラッシュを生成します。	アップロード前に、ペイロード内のすべての path 値をスラッシュに正規化してください（例：Node.js では .replace(/\\\\/g, '/')、PowerShell では .Replace('\\', '/')）。
作成後、ワークスペースに重複したレポートが表示される	202 Accepted 応答の後に Create POST が再試行されました。再試行のたびに新しいレポートが作成される可能性があります。	202 の後に Create POST を再試行しないでください。操作 ID の確実な取得方法と復旧手順については、LRO のセクションを参照してください。Delete Report API を使用して重複を削除してください。
モデルの引き渡しを介してローカルの .pbip を発行した後、ビジュアルが空になる	セマンティックモデルの作成スキルによって、デプロイ時にテーブルや列の名前が変更または変換されることがあり、その結果、新しくデプロイされたモデルの TMDL がレポートの PBIR バインディングと一致しなくなります。	デプロイ済みモデルに対して TMDL 差分の検証を再実行し（MUST 対象モデルの解決後にセマンティックモデルのバインディングを検証するに従ってください）、ずれたバインディングを powerbi-report-authoring スキルを使って再マッピングしてください。
TMDL の差分に問題がないのに、発行後にビジュアルが空になる	definition.pbir の byConnection が、解決済みの新しいモデルではなく、古いモデル ID（例：.pbi/ キャッシュまたは以前の発行時のもの）を参照しています。	ローカルの .pbip の発行の手順 7 を再実行し、byConnection に実際に解決された semanticModelId を設定してから再発行してください。
ユーザーがローカルモデルの発行を希望しているが、セマンティックモデルの作成スキルを利用できない	現在のセッションでセマンティックモデルの作成スキルが読み込まれていません。	ユーザーにその旨を伝え、既存モデルへの接続分岐に切り替えてください。レポートをバインドするワークスペースモデルを再度尋ねてください。黙って次の処理に進まないでください。
モデルはあるワークスペースに発行されたが、レポートは別のワークスペースに POST された	あらかじめワークスペースが確認されていなかったか、モデルのデプロイとレポートの発行に異なるワークスペースが使用されました。	単一ワークスペースのルール（ローカルの .pbip の発行の手順 2）を徹底してください。復旧方法：モデルと同じワークスペースにレポートを再発行するか、モデルを移動してください。