deployment-pipelines-authoring-cli

テレメトリ — 必須です。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: deployment-pipelines-authoring-cli を付与してください（az rest の場合は --headers "x-ms-fabric-skill=deployment-pipelines-authoring-cli"）。 すべての LRO ポーリング、fabric_lro、リトライにも付与してください。スニペットでは省略していますが、必ず追加してください。

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を特定するには、すべてのワークスペースを一覧表示してから、JMESPath フィルターを使用します
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を特定するには、そのワークスペース内で該当する種類のアイテムをすべて一覧表示してから、JMESPath フィルターを使用します
3. デプロイメントパイプラインまたはステージの ID を特定するには、デプロイメントパイプライン（次にステージ）を一覧表示し、JMESPath で displayName を使って絞り込みます。ID を推測してはいけません。

Fabric デプロイメントパイプラインの作成 — CLI スキル

デプロイメントパイプラインを使用して Fabric のアプリケーションライフサイクル管理（ALM）を自動化します。Fabric のコアコントロールプレーン REST API を使用して、Fabric コンテンツをステージ間（通常は開発 → テスト → 本番）で昇格します。このスキルでは、パイプライン／ステージのライフサイクル、ワークスペースの割り当て、ステージ間のデプロイ（長時間実行操作）を扱います。

前提知識

まず、次の関連ドキュメントを読んでください。このスキルでは各ドキュメントのパターンを前提としており、繰り返し説明しません。

タスク	参照先	備考
Fabric でのワークスペースとアイテムの検索	COMMON-CLI.md § Finding Workspaces and Items in Fabric	必須 — 一覧表示と JMESPath を使い、名前からワークスペース／アイテムの ID を特定します
認証とトークンの取得	COMMON-CORE.md § Authentication & Token Acquisition	トークンのオーディエンスは https://api.fabric.microsoft.com である必要があります。オーディエンスが異なると 401 が発生します
認証の手順	COMMON-CLI.md § Authentication Recipes	az login のフローとトークン取得
az rest による Fabric コントロールプレーン API の利用	COMMON-CLI.md § Fabric Control-Plane API via az rest	必ず --resource https://api.fabric.microsoft.com を指定してください
コアコントロールプレーン REST API	COMMON-CORE.md § Core Control-Plane REST APIs	ページネーション、LRO ポーリング、レート制限のパターン
長時間実行操作（LRO）	COMMON-CLI.md § Long-Running Operations (LRO) Pattern	デプロイは LRO です — 終端状態になるまで /v1/operations/{id} をポーリングします
環境 URL	COMMON-CORE.md § Environment URLs	ソブリン／政府機関向けクラウドではホストが異なります
サポートされているアイテムの種類	references/supported-item-types.md	デプロイでコピーできるアイテムの種類をカテゴリごとに、プレビューのフラグも含めてまとめた更新され続ける一覧です。公式 Microsoft ドキュメント（信頼できる情報源）と照合してください。推測してはいけません
2 つのアイテム定義を比較する（トークン効率化）	references/scripts/diff_item_definitions.py	2 つの getDefinition ペイロードをデコードし、自動再バインドされるフィールドを正規化して、差分のみを出力するローカルツールです。完全な定義ではなく、差分をモデルに渡してください。python references/scripts/diff_item_definitions.py source.json target.json（終了コード 0=同一、1=変更あり）

このスキルでは、エージェント型ターミナルからデプロイメントパイプラインの REST API を操作する方法を追加で説明します。

概念

• デプロイパイプラインには、順序付けられた2～10 個のステージが含まれます（order は 0 から始まります）。各ステージに割り当てられるワークスペースは最大 1 つであり、1 つのワークスペースを複数のステージに割り当てることはできません。
• デプロイでは、サポート対象のアイテムのコンテンツをソースステージから隣接するターゲットステージにコピーします。前方へのデプロイ（dev→test→prod）は、隣接する任意のステージ間で実行できます。後方へのデプロイ（例：prod→test）が現在サポートされるのは、ターゲットステージが空の場合（ワークスペースが割り当てられていない場合）のみです。すでにワークスペースがあるステージへの後方デプロイはできません。
• アイテムのペアリング（自動バインド）。 デプロイ中、Fabric はソースアイテムとターゲットステージ内のそのクローンとの接続を記録します。このペアリングによって、後続のデプロイで上書きするターゲットアイテムが特定され、関連するアイテム（例：レポートとそのセマンティックモデル）のバインドが維持されます。ペアリングを設定する REST API はありません。ペアリングは自動的に維持されますが、List stage items が返す sourceItemId／targetItemId フィールドを使って現在のペアリングを確認できます。唯一サポートされている修復方法については、以下の壊れたアイテムのペアリングを修正するワークフローを参照してください。
• デプロイは**非同期の長時間実行操作（LRO）**です。API は操作 ID とともに 202 Accepted を返すため、完了するまでポーリングします。
• デプロイルールとパラメータールール（例：ステージごとにデータソースを切り替える）は、Fabric ポータル UI で設定します。ルールを作成する REST API はありません。そのような API があると主張しないでください。
• デプロイでコピーされるのはサポート対象のアイテムタイプのみです。サポート対象外のアイテムはスキップされます（エラーにはなりません）。サポート対象の一覧は随時変更されます。references/supported-item-types.md を参照してください。
• 「変更点」や比較を取得する REST API はありません。 List stage items が返すのはアイテムの識別情報とペアリング（itemId、itemDisplayName、itemType、sourceItemId、targetItemId、lastDeploymentTime）のみで、変更ステータスは含まれません。また、lastDeploymentTime は最後にデプロイした時刻であり、最後に編集した時刻ではないため、変更を判断する信頼できる指標ではありません。変更されたアイテムのみをデプロイするには、2 つのステージを自分で差分比較し、items リストを作成する必要があります（以下の変更されたアイテムのみをデプロイするワークフローを参照）。ポータルの「Compare」ビューはサーバー側で処理され、API では公開されていません。

必須／推奨／回避

必須

• 変更を伴う呼び出しの前に、リスト取得と JMESPath を使って、パイプライン、ステージ、ワークスペースの ID を名前から解決します。GUID を捏造してはいけません。
• 正しいベース URL https://api.fabric.microsoft.com/v1/deploymentPipelines を使用し、https://api.fabric.microsoft.com オーディエンス用のトークンを取得します。
• Deploy Stage Content は LRO として扱います。202 が返されたら操作 ID を取得し、状態が Succeeded／Failed になるまで /v1/operations/{operationId} をポーリングしてから、結果を提示します。
• ターゲットステージにワークスペースが割り当てられていない場合は、デプロイの本文に createdWorkspaceDetails（名前、および必要に応じて capacityId）を含めます。含めない場合、デプロイは失敗します。
• パイプラインの削除、ワークスペースの割り当て解除、prod への後方デプロイなど、破壊的な操作を実行する前に、ユーザーの意図を確認します。
• 変更を伴う呼び出しの前に、呼び出し元に必要なアクセス許可があることを確認します（以下の必要なアクセス許可を参照）。すべてのパイプライン操作にはパイプラインの Admin が、割り当て／デプロイには適切なワークスペースロールも必要です。401／403 が返された場合は、やみくもに再試行せず、明確で実行可能なメッセージを提示します。

推奨

• ユーザーが特定のアイテムを指定した場合は、items 配列（{ sourceItemId, itemType }）を使って選択的にデプロイします。items を省略すると、サポートされているすべてのアイテムがデプロイされます。
• デプロイごとに、人が読める note を付けます。ただし、これは書き込み専用です。API は受け付けますが、返却しません（ポータル UI にのみ表示されます）。プログラムによる監査証跡を残すには、デプロイを外部にも記録してください（CI/CD ログまたは Git コミットメッセージ）。
• デプロイ前に、移動する内容をプレビューするため List Deployment Pipeline Stage Items を使います。
• 冪等なスクリプトを作成します。作成前に、パイプライン、ステージ、割り当てがすでに存在するか確認してください。

避けるべきこと

• 「create deployment rule」または「parameter rule」の REST 呼び出しをでっち上げること。現時点では UI 専用です。
• アクティブなデプロイ中にワークスペースを割り当てること（割り当て呼び出しは失敗します）、またはすでにペアになっているステージ／ワークスペースに割り当てること。
• ソブリンクラウドで api.fabric.microsoft.com をハードコードすること。ホストは環境設定から解決してください。
• Fabric 管理者がデプロイメントパイプラインの SP 作成を有効にしたことを確認せずに、サービスプリンシパルを使うこと。
• 正規化せずに、生の getDefinition 出力をハッシュ化して変更を検出すること。 デプロイ時に、ターゲット内の埋め込み参照（パイプラインの notebookId／workspaceId、レポートからモデルへの ID、Direct Lake のサーバー／データベース）は自動的に再バインドされます。そのため、何も編集していなくても、ペアになったターゲットの定義はソースと正当に異なります。単純なハッシュ化では、誤って「変更あり」と判定されます。比較前に、これらのバインドフィールドを削除または正規化してください。
• すべてのアイテム定義を出力してエージェントのコンテキストに読み込ませ、差分を取ること。 2 つのステージ間で内容をすべて比較すると、getDefinition を数十回呼び出し、100 KB を超える場合があります。スクリプト（references/scripts/diff_item_definitions.py）で比較し、結果の変更一覧だけを提示してください。変更されたアイテムについては、出力された差分のみをモデルに渡し、2 つの完全な定義は決して渡さないでください。
• 破損したペアリングを修復するため、ワークスペースを割り当て解除する前にユーザーへ警告せずに割り当て解除すること。割り当て解除すると、そのステージのデプロイ履歴と設定済みのデプロイ／パラメーター ルールが恒久的に削除されます。割り当て解除の前に、ステージにルールがあるか必ず確認してください（Fix a broken item pairing を参照）。

REST API リファレンス

ベース URL：https://api.fabric.microsoft.com/v1。委任スコープは操作ごとに異なります。最小権限でサービスプリンシパルをプロビジョニングしてください。

操作	必要な委任スコープ
一覧表示／取得（パイプライン、ステージ、ステージアイテム、操作）	Pipeline.Read.All または Pipeline.ReadWrite.All
パイプラインの作成／更新／削除、ステージの更新	Pipeline.ReadWrite.All
ワークスペースの割り当て／割り当て解除	Pipeline.ReadWrite.All および Workspace.ReadWrite.All
ステージのコンテンツをデプロイ	Pipeline.Deploy

デプロイには専用の Pipeline.Deploy スコープを使います。Pipeline.ReadWrite.All のみをスコープに指定したアプリで POST .../deploy を呼び出すと、403 が返されます。

操作	メソッド + パス
パイプラインの一覧表示	GET /deploymentPipelines
パイプラインの作成	POST /deploymentPipelines
パイプラインの取得／更新／削除	`GET
ステージの一覧表示／取得	GET /deploymentPipelines/{id}/stages[/{stageId}]
ステージの更新	PATCH /deploymentPipelines/{id}/stages/{stageId}
ステージアイテムの一覧表示	GET /deploymentPipelines/{id}/stages/{stageId}/items
ステージへのワークスペースの割り当て	POST /deploymentPipelines/{id}/stages/{stageId}/assignWorkspace
ステージからのワークスペースの割り当て解除	POST /deploymentPipelines/{id}/stages/{stageId}/unassignWorkspace
ステージのコンテンツをデプロイ（LRO）	POST /deploymentPipelines/{id}/deploy
操作の一覧表示（直近 20 件まで）	GET /deploymentPipelines/{id}/operations
操作の取得（実行計画を含む）	GET /deploymentPipelines/{id}/operations/{operationId}
ロールの割り当て	`GET

リクエストボディの形式（ガイダンス）

• 作成：{ "displayName", "description"?, "stages": [ { "displayName", "description"?, "isPublic" } ] } — ステージは2～10個です。
• ワークスペースの割り当て：{ "workspaceId" }。
• デプロイ：{ "sourceStageId", "targetStageId", "items"?: [ { "sourceItemId", "itemType" } ], "note"?, "options"?: { "allowCrossRegionDeployment": false }, "createdWorkspaceDetails"?: { "name", "capacityId"? } }。

必要なアクセス許可

デプロイメントパイプラインの操作は、独立した2つのアクセス許可システムによって管理されます。パイプラインにおけるロール（独自のroleAssignments）と、関係する各ワークスペースにおけるロールです。通常、両方が必要です。デプロイメントパイプラインにはFabricの容量／サブスクリプションが必要で、パイプラインの作成者はパイプラインの管理者になります。

操作	パイプラインのロール	ワークスペースのロール
パイプラインの作成	—（作成時に管理者になります）	Fabricワークスペースの管理者（機能へのアクセスに必要）
パイプライン、ステージ、アイテム、操作の取得／一覧表示	管理者（共有アクセス）	—
パイプラインの更新／削除、roleAssignmentsの管理	管理者	—
ステージへのワークスペースの割り当て／割り当て解除	管理者	割り当て／割り当て解除するワークスペースの管理者
ステージのコンテンツのデプロイ	管理者	ソースとターゲットの両方のステージのワークスペースで、少なくとも共同作成者／メンバー（ターゲットアイテムが必要とする場合は、さらに高いロール）
空のターゲットステージへのデプロイ（ワークスペースを作成）	管理者	新しいワークスペースを容量に配置するための容量割り当て権限。デプロイするユーザーは、新しく作成されたワークスペースの唯一の管理者になり、複製されたセマンティックモデルの所有者になります

注意：

• パイプラインを共有すると、パイプラインの管理者ロールが付与されます。これらの操作には、より低い「閲覧のみ」のパイプライン書き込みロールはありません。
• サービスプリンシパルがこれらのAPIを操作するには、Fabric管理者がサービスプリンシパルによるデプロイメントパイプラインの作成を有効にしている必要があります（さらに、SPが上記と同じパイプラインおよびワークスペースのロールを持っている必要があります）。
• 403が返された場合は、メッセージでパイプラインのロール不足とワークスペースのロール不足を区別し、ユーザーがどのアクセス権を申請すればよいか分かるようにしてください。

パイプラインを作成する → 表示名と順序を指定したステージをPOSTします。返されたステージIDを記録してください（ステージ間のデプロイに使用します）。

ステージにワークスペースを割り当てる → 名前からステージIDとワークスペースIDを解決し、両方が未割り当てであることを確認してから、assignWorkspaceをPOSTします。パイプラインとワークスペースの両方で管理者権限が必要です。

コンテンツをデプロイする → ソースとターゲットのステージIDを解決し、必要に応じてステージアイテムをプレビューしてから、noteを付けてdeployをPOSTします（すべてのアイテム、または選択したitemsリスト）。その後、返された操作を完了までポーリングし、移動したアイテムを報告します。 変更された項目のみをデプロイする → 差分／比較 API がないため、差分を自分で計算してください。List stage items で取得できるのは識別情報とペアリング情報のみです（タイムスタンプや変更状況はありません）。そのため、変更を検出するには 項目定義を比較します。

1. ソースとターゲットの ステージ ID、およびそれぞれに割り当てられたワークスペースを解決します。
2. 両方のステージの項目を一覧表示します（GET .../stages/{stageId}/items）。ソース側の各行には sourceItemId（itemId として）と、ペアになっている targetItemId が含まれます（存在しない場合は 新規／未ペアリング）。また、ターゲットステージも一覧表示し、 削除済みの項目（ターゲットに存在し、どのソース項目ともペアになっていないもの）を見つけます。targetItemId でペアリングし、パイプラインのペアリングが存在しない場合に限り (itemType, displayName) にフォールバックします（名前の照合では名前の変更を検出できません）。
3. システム管理の子項目を除外します。SQLEndpoint は各 Lakehouse／Warehouse に対して自動作成されるため、単独で差分比較やデプロイを行わないでください。親項目に従います。
4. ペアになった各項目を分類します。
   • 新規（targetItemId がない）→ デプロイします。
   • 変更あり → 両方のステージで POST .../items/{id}/getDefinition を実行し、差分を比較して検出します。2 つの レスポンスに対して references/scripts/diff_item_definitions.py を実行します。このスクリプトは各パートをデコードし、自動的に再バインドされたフィールド（パイプラインの notebookId／ workspaceId、レポートのモデル ID、Direct Lake のサーバー／DB）を正規化して、異なるパートのみを出力します（終了コード 1 = 変更あり、0 = 同一）。そのため、ハッシュ処理を自分で実装したり、編集されていない項目を誤って変更ありと判定したりする必要はありません。getDefinition の仕様は種類によって異なります。 Notebook／SemanticModel／Report は LRO（202 → ポーリング → GET .../result）です。 DataPipeline は 200 で同期的に返ります。
   • 利用可能な getDefinition の差分比較がない種類：Warehouse には項目定義 API がありません。また、 Lakehouse／Environment は getDefinition を公開していますが、その定義に含まれるのは構造／メタデータのみです（テーブルデータやほとんどのコンテンツ編集は含まれません）。そのため、これら 3 種類すべてについて、存在の有無で差分を比較し、新規の場合、またはユーザーがコンテンツの変更を示した場合に限り、変更ありとして扱います。
   • 同一であることを証明できない場合は、安全な既定の動作として変更ありと扱います。
5. 比較はスクリプト内で実行します（独立した getDefinition 呼び出しを並列化してください。これらがレイテンシの大部分を占めます）。算出した変更リストのみを提示します。モデルが項目の「何が」変更されたかを判断できるようにするには、2 つの完全な定義ではなく、出力された差分のみ（diff_item_definitions.py の出力）を渡します。正規化された差分は通常、100 KB を超える生ペイロードに対して数行程度です。
6. サポートされている項目の種類（references を参照）に絞り込み、変更リストをユーザーに提示して確認を取り、{ sourceItemId, itemType } 配列と note を含む選択的な deploy を POST し、完了までポーリングします。

削除は、items を指定した選択的なデプロイでは反映されません。ソースステージから削除された項目は、選択的なデプロイではターゲットから削除されません。削除を反映するには、items を省略した全体デプロイを使用するか、ターゲットの項目を手動で削除してください。昇格の前に、この点をユーザーに警告してください。 壊れたアイテムのペアリングを修復する → ペアリング（ソース↔ターゲット間の接続。Fabric が維持する自動バインドとも呼ばれます）は、REST API では設定できません。ステージ間でペアリングされるべき 2 つのアイテムがペアリングされていない場合（アイテムが上書きされずに重複して作成されるデプロイ、自動バインド／依存関係の失敗、またはユーザーからの報告で判明します）、サポートされている唯一の修復方法は、該当ステージのワークスペースの割り当てを解除してから再割り当てすることです。これにより、次回のデプロイ時に Fabric がペアリングを再構築します。この操作は破壊的です。

1. まずユーザーに警告してください。 ワークスペースの割り当てを解除すると、そのステージのデプロイ履歴と、設定済みのデプロイ／パラメーターのルールが完全に削除されます。再割り当てしても復元できません。
2. ステージにルールが設定されているか確認してください。 ルールは UI 専用で（読み取りや再作成のための REST API はありません）、割り当てを解除する前に、そのステージにデプロイ／パラメーターのルールが設定されているかユーザーに明示的に確認してください。設定されている場合は、ユーザーにルールを記録してもらい（または後でポータルで再作成してもらい）、続行することへの明示的な確認を得てください。
3. 確認を得てから、POST .../stages/{stageId}/unassignWorkspace を実行し、続けて同じ workspaceId を指定して POST .../stages/{stageId}/assignWorkspace を実行します。その後、デプロイを再実行してペアリングを再確立します。

追跡／監査 → 最近の履歴には List operations、特定のデプロイの実行計画とアイテムごとの状態の確認には Get operation を使用します。

デプロイ時の注意事項とよくあるエラー

• パイプラインごとに実行できるデプロイは 1 件までです。 パイプラインでは一度に 1 つの操作しか実行できません。操作の実行中に別の操作を開始すると、WorkspaceMigrationOperationInProgress（HTTP 400） で失敗します。次のステージへの昇格を開始する前に、現在の操作が終端状態になるまで必ずポーリングしてください（アクティブなデプロイ中にワークスペースの assign 呼び出しが失敗するのもこのためです）。
• ワークスペースの割り当て後、最初のデプロイは Alm_InvalidRequest_WorkloadUnavailable で失敗することがあります。 新しく割り当てられたワークスペースでは、ワークロードサービス（Lakehouse、Notebook など）の初期化に 約 60～120 秒かかります。最初のデプロイまで待つか、先に Power BI アイテム（SemanticModel、Report）をデプロイし、少し待ってから Fabric ネイティブのアイテム（Lakehouse、Notebook）をデプロイして対処してください。このエラーが発生した場合は再試行してください。ワークロードがウォームアップされれば、以降のデプロイは安定して実行できます。
• 操作 ID は 202 の本文ではなく、x-ms-operation-id レスポンスヘッダー（Location と併せて返されます）で返されます。 az rest ではレスポンスヘッダーを確実に取得できません。自動化でヘッダーを確実に取得するには、curl -i（または Python の requests）でデプロイを実行してヘッダーを解析し、その後 az rest で /v1/operations/{operationId} をポーリングしてください。
• デプロイでコピーされるのは定義であり、データではありません。 昇格されるのはアイテムのメタデータ／定義のみです。テーブルデータ、クエリ結果、キャッシュはコピーされません。デプロイ後、ターゲットステージで更新／読み込みを実行してください。
• デプロイリクエストあたりの最大アイテム数は 300 件です。 選択したアイテムのみのデプロイでも全アイテムのデプロイでも、デプロイ対象のアイテムは 300 件までです。これを超える昇格は複数のデプロイ呼び出しに分けてください。

例

3 ステージのパイプラインを作成する

デプロイパイプラインの displayName はテナント全体で一意である必要があります。同じ名前がすでに使われている場合、作成は Alm_InvalidRequest_DuplicateAlmPipelineName（HTTP 400、「pipeline name ... is already in use」）で失敗します。作成を再実行できるようにするには、まず同じ名前の既存パイプラインを削除してから作成してください。JSON 本文はファイルに書き出し、--body @file.json で渡してください。インラインの複数行 --body '{...}' は Windows／PowerShell（az は az.cmd）では空の本文に変換され、API が InvalidInput: Unexpected end when reading JSON で拒否します。

# Idempotent: delete an existing "Sales Analytics ALM" if present, then create.
EXISTING=$(az rest --method GET --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
  --query "value[?displayName=='Sales Analytics ALM'].id | [0]" --output tsv)
if [ -n "$EXISTING" ]; then
  az rest --method DELETE --resource https://api.fabric.microsoft.com \
    --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$EXISTING"
fi

cat > /tmp/create-pipeline.json << 'EOF'
{
  "displayName": "Sales Analytics ALM",
  "description": "Dev/Test/Prod promotion for Sales Analytics",
  "stages": [
    { "displayName": "Development", "isPublic": false },
    { "displayName": "Test",        "isPublic": false },
    { "displayName": "Production",  "isPublic": true }
  ]
}
EOF
az rest --method POST \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
  --headers "Content-Type=application/json" \
  --body @/tmp/create-pipeline.json

Development ステージにワークスペースを割り当てる

# $PIPELINE_ID and $DEV_STAGE_ID resolved via list + JMESPath; $WS_ID resolved from workspace name.
az rest --method POST \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$DEV_STAGE_ID/assignWorkspace" \
  --headers "Content-Type=application/json" \
  --body "{ \"workspaceId\": \"$WS_ID\" }"

dev から test にすべてのアイテムをデプロイし、LRO の完了を待つ

# Kick off the deployment (returns 202 + an operation id header).
az rest --method POST \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
  --headers "Content-Type=application/json" \
  --body "{ \"sourceStageId\": \"$DEV_STAGE_ID\", \"targetStageId\": \"$TEST_STAGE_ID\", \"note\": \"Promote validated dev build\" }" \
  --verbose
# Then poll /v1/operations/{operationId} until state is Succeeded or Failed
# (see COMMON-CLI § Long-Running Operations pattern).

選択したアイテムのみをデプロイする

az rest --method POST \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
  --headers "Content-Type=application/json" \
  --body '{
    "sourceStageId": "'"$TEST_STAGE_ID"'",
    "targetStageId": "'"$PROD_STAGE_ID"'",
    "items": [
      { "sourceItemId": "'"$MODEL_ID"'", "itemType": "SemanticModel" },
      { "sourceItemId": "'"$REPORT_ID"'", "itemType": "Report" }
    ],
    "note": "Promote reviewed model + report to production"
  }'

変更されたアイテムのみをデプロイする（先に差分を計算する）

# 1. List paired items for BOTH stages. Each source row carries itemId (= sourceItemId)
#    and its paired targetItemId (absent = new/unpaired). There is NO timestamp or
#    change-status field, so "changed" must be detected from item definitions.
az rest --method GET --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$SOURCE_STAGE_ID/items" \
  > source-items.json

# 2. NEW items = unpaired (no targetItemId). Exclude system-managed SQLEndpoint children.
NEW=$(jq '[.value[]
  | select(.itemType != "SQLEndpoint")
  | select(has("targetItemId") | not)
  | { sourceItemId: .itemId, itemType: .itemType }]' source-items.json)

# 3. CHANGED items (paired): fetch getDefinition from BOTH stages, then diff with
#    references/scripts/diff_item_definitions.py. It decodes each part, NORMALIZES the
#    auto-rebound fields (notebookId/workspaceId in pipelines, model id in reports,
#    server/db in Direct Lake models) and prints ONLY the differing parts. Notebook/
#    SemanticModel/Report are LRO (202 -> poll -> /result); DataPipeline returns 200 sync.
#    Parallelize the independent getDefinition calls. Per paired definition-backed item:
#      getDefinition SOURCE_WS id            > src.json
#      getDefinition TARGET_WS targetItemId  > tgt.json
#      python references/scripts/diff_item_definitions.py src.json tgt.json > diff.json
#      # exit 1 = changed -> add { sourceItemId, itemType } to $ITEMS; exit 0 = unchanged.
#      # Forward diff.json (NOT src.json/tgt.json) to the model to explain the change.
#    Merge NEW + CHANGED into $ITEMS. When equality can't be proven, include the item.

# 4. Selective deploy of just the changed set.
az rest --method POST --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
  --headers "Content-Type=application/json" \
  --body "$(jq -n --arg s "$SOURCE_STAGE_ID" --arg t "$TARGET_STAGE_ID" --argjson items "$ITEMS" \
    '{ sourceStageId: $s, targetStageId: $t, items: $items, note: "Deploy only changed items" }')"
# Then poll /v1/operations/{operationId} until terminal.
# NOTE: a selective deploy does NOT propagate deletions — use a full deploy (omit items) for those.

プロンプト／応答

ユーザー：「Sales dev ワークスペースを Test ステージに昇格し、完了したら知らせてください。」

アシスタント（動作）：

1. デプロイメントパイプラインを一覧表示し、Development ステージに Sales dev ワークスペースがあるパイプラインに絞り込みます。sourceStageId（Development）と targetStageId（Test）を取得します。
2. Test ステージに割り当て済みのワークスペースがあることを確認します（ない場合は、作成するための名前と容量を尋ねます）。
3. note を指定して deploy を POST し、202 を受け取り、オペレーション ID を抽出します。
4. /v1/operations/{operationId} を終端状態になるまでポーリングし、成功したこととデプロイされた項目の一覧（または失敗の理由）を報告します。