variable-library-cli

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

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を調べるには、すべてのワークスペースを一覧表示してから、JMESPath でフィルタリングしてください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を調べるには、そのワークスペース内にある該当する種類のアイテムをすべて一覧表示してから、JMESPath でフィルタリングしてください。
3. Variable Library には 2 つのプレーンがあります。Git 内の定義ファイルと、ワークスペース内のアクティブな値セットのアイテム状態です。アクティブな値セットを Git の編集として扱わないでください。定義プレーンは authoring、アイテム状態プレーンは operations です。
4. Variable Library の定義リクエストでは、format フィールドを完全に省略してください。format: null は送信しないでください。
5. スキルの使い分け：コンシューマー参照における Variable Library 側も含め、Variable Library に関するすべての作業には variable-library-cli を使用してください。コンシューマーアイテム自体の詳細なオーサリングは別のスキルの対象です。パイプラインには pipeline-migration、ノートブックには spark-cli、Dataflow Gen2 には dataflows-cli、Git のライフサイクルには git-integration-operations-cli、デプロイメントパイプラインの仕組みには deployment-pipelines-authoring-cli を使用してください。
6. 依頼内容が不明確な場合は、作成前に確認してください。「Variable Library をセットアップ／作成して」という依頼で、変数名、型、デフォルト値、値セットが指定されていない場合は、確認の質問をするか、作成前に選択肢を整理して提示してください。設定を捏造し、意図を確認せずにアイテムを作成してはいけません。具体的かつ完全に指定された依頼であれば、確認は不要です。
7. Variable Library の Boolean 値を読み取るコンシューマーコード（ノートブック、UDF）を生成する場合は、str(value).lower() == "true" を使って防御的に型変換してください。文字列に対して bool(value) を使ってはいけません。Python では "false" を含む空でない文字列はすべて真として扱われるため、bool("false") は常に True になります。
8. 値が変数のデフォルト値と同じになる値セットのオーバーライドは書き込まないでください。オーバーライドは値を固定します。一度書き込むと、後からデフォルト値を編集してもその値セットには反映されなくなるため、重複するオーバーライドを設定すると、値セットが暗黙的に継承から外れます。オーバーライドを省略し、値セットに継承させてください。値が実際に異なる場合にのみオーバーライドしてください。

Fabric Variable Library -- CLI スキル

このスキルは、Fabric Variable Library のアイテム（定義と値セット）、コンシューマー参照の VL 側、アクティブな値セットのアイテム状態、Variable Library の CI/CD 動作を担当します。

これはモードディスパッチャーであり、手順は一切含まれていません。以下の表から依頼に合ったモードを選び、コマンドを 1 つでも実行する前に、ファイル読み取りツールを使って該当する references/<mode>.md ファイルを最初から最後まで読んでください。そのファイルにはエンドポイント、ペイロードの形式、テンプレート、注意点が記載されています。読まずに作業すると、誤ったペイロードや結果につながります。

セッションごとに一度だけ読んでください。すでに読んだファイルの内容はコンテキストに保持されるため、後のターンで再読する必要はありません。

モードの選択

モード	リクエストの内容	例となるトリガー	最初に読むもの
authoring	ライブラリ定義（変数、既定値、型、値セットのオーバーライドファイル、settings.json）を作成または変更する	変数ライブラリの作成、変数の追加、valueSets、variableOverrides、valueSetsOrder、updateDefinition	references/authoring.md
consumption	変数をコンシューマー項目に組み込む、またはコンシューマーによる変数の解決方法を説明する	libraryVariables、notebookutils の変数ライブラリ、パイプライン式、Dataflow Gen2／コピー ジョブ／ショートカット／UDF／Plan の参照	references/consumption.md
operations	アクティブな値セットを読み取る、または切り替える、あるいはステージ、Git のシリアル化、デプロイを扱う	アクティブな値セット、activeValueSetName、本番環境への昇格、ステージごとの値、Git の差分、fabric-cicd	references/operations.md

モードの境界ルール

用語ではなく、プレーンで分類してください。値セットに言及するリクエストでも、オーバーライド ファイル を変更する場合は authoring、ワークスペースでアクティブにする値セットを変更する場合は operations です。valueSets/prod.json の作成は authoring、prod ワークスペースでその値セットを指定するのは operations です。

consumption が扱うのは、参照のうち Variable Library 側だけです。コンシューマー項目自体の定義を作成する場合は、その項目のスキルが担当します（CRITICAL NOTES 5）。

リクエストが実際に複数のモードにまたがる場合は、一度に一つずつ対応し、その作業に着手する前に各リファレンスを読んでください。この表を読んでもモードが曖昧な場合は、推測せず、短い確認質問を一つしてください。

ターミナル書き込み -- 省略してはならないステップ

リファレンスを読み、変更を計画しただけでは、タスクは完了していません。変更を伴う各モードでは、最後に状態を変更する呼び出しが一つ必要です。これを実行していない場合、変更は保存されていません。成功したと報告するのではなく、その旨を明示してください。

モード	ターミナル書き込み
authoring	新しいライブラリの場合は type: "VariableLibrary" を指定して POST /v1/workspaces/{ws}/items を実行し、編集内容を保存する場合は POST /v1/workspaces/{ws}/items/{id}/updateDefinition を実行します。どちらも base64 の定義パーツを送信し、format は省略する必要があります。JSON をローカルで作成しても、何も書き込まれません。
consumption	コンシューマー項目自体の更新呼び出しを、その項目のスキルが担当します。このスキルの成果物は、その項目に設定する正しい参照コントラクトです。
operations	{"properties":{"activeValueSetName":"<name>"}} を指定して PATCH /v1/workspaces/{ws}/variableLibraries/{id} を実行します。これは項目の状態であり、settings.json、variables.json、valueSets/*.json は編集されず、Git の差分にも表示されません。

タスク完了を報告する前に、最後の呼び出しが成功したことを確認し、アーティファクトを読み戻して変更が反映されたことを確かめてください。operations の場合は GET /variableLibraries/{id} で読み戻してください。汎用の /items/{id} では properties が省略され、アクティブな値セットが表示されません。

共有の基本事項（すべてのモード）

まずワークスペースとアイテムを特定してください。すべてのモードで必要になります。

タスク	参照先	メモ
Fabric でワークスペースとアイテムを検索する	COMMON-CLI.md	必須 — ワークスペースまたはアイテムの ID を特定する前に読んでください
Fabric のトポロジと主要な概念	COMMON-CORE.md	アイテムの種類、ワークスペース、容量
認証とトークンの取得	COMMON-CORE.md	audience が誤っていると 401 が発生します。認証の問題が発生した場合は、まず読んでください
認証の手順	COMMON-CLI.md	az login のフローとトークンの取得
az rest を使った Fabric REST	COMMON-CLI.md	このスキルの主なアクセス方法
コアのコントロールプレーン REST API	COMMON-CORE.md	ページネーション、LRO のポーリング、レート制限
長時間実行操作（LRO）	COMMON-CLI.md	作成 API と定義 API は 202 を返す場合があります
VariableLibrary アイテム定義	ITEM-DEFINITIONS-CORE.md	正式なパートパスとフィールド名
注意事項とトラブルシューティング	COMMON-CLI.md	az rest の audience、シェルのエスケープ、トークンの有効期限

ルール

必須

• 何かを行う前に、上の表からモードを必ず 1 つだけ選択してください。
• そのモードの最初のコマンドを実行する前に、references/<mode>.md を最初のツール呼び出しとして、最初から最後まで読んでください。1 回だけ、全体をまとめて読んでください。再度開いたり、再び grep したり、ページ単位で読み進めたりしないでください。すでに読み込み済みです。
• ワークスペース ID とアイテム ID は、一覧表示して絞り込むことで特定してください。GUID を推測してはいけません。
• リクエストが境界をまたぐ場合は、モードを切り替えることを明示してください。
• 参照資料は指示として扱い、成果物として扱わないでください。読み終えたら、記載されたコマンドを実際のワークスペースに対して実行し、実際の結果を報告してください。
• 正式なパート名 variables.json、settings.json、および valueSets/<name>.json を使用し、既定値には value、値セットのオーバーライドには variableOverrides を使用してください。
• ユーザーが求めた成果物はすべて、ユーザーが指定した名前で作成してください。また、結果が「なし」の場合も、その見出しを残してください。

推奨

• リクエストを満たす最も限定的なモードを選択してください。
• モード参照資料は正確に 1 つだけ読むようにしてください。リクエストが実際に複数のモードにまたがる場合に限り、2 つ目を読み、その前に理由を伝えてください。
• 最初の応答で選択したモードを伝え、ユーザーが修正できるようにしてください。
• base64 ペイロードの UTF-8 を正しく保ち、安定した引用符処理を行えるよう、Python または jq で JSON 本文を生成してください。
• ここで手作業で作り込むのではなく、デプロイ全体の自動化には fabric-cicd を推奨してください。

避けるべきこと

• このディスパッチャーだけを頼りに作業すること。この文書では、意図的に運用上の詳細を省略しています。
• 値セットのオーバーライドを文字列化すること。variableOverrides[].value には、必ず変数のネイティブな JSON 型を使用してください。REST のドキュメントではフィールドが String と記載されていますが、文字列化されたブール値または数値は InvalidContent (InvalidValueOrTypeMismatch) により拒否されます。
• Variable Library の定義で defaultValue、values、または format を使用すること。
• Fabric fab CLI のコマンド構文を使用すること。コマンドは存在しますが、Variable Library のコマンド形式はここでは検証されていません。
• 利用側アイテムの定義を細部まで作り込むこと（重要な注意事項 5）。
• すでに読み込んだ参照資料を再読したり、再び grep したりすること。ターンとトークンを消費します。

例

ユーザーのリクエスト	モード	参照するドキュメント
「dev と prod の値セットを含む変数ライブラリを作成してください。」	authoring	references/authoring.md
「target_path 変数を取り込みパイプラインに接続してください。」	consumption	references/consumption.md
「デプロイ後に prod ワークスペースを prod 値セットに切り替えてください。」	operations	references/operations.md
「Git の差分に値セットの切り替えが表示されなかったのはなぜですか？」	operations	references/operations.md
「Boolean フラグ変数を追加してから、ノートブックで読み取ってください。」	authoring、次に consumption	両方を一度に 1 つずつ