dataflows-cli

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

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を検索するには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用します。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を検索するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath フィルタリングを使用します。
3. スキルの使い分け：Fabric Dataflow Gen2 アイテムと Power Query M に関するすべての作業には dataflows-cli を使用します。Synapse／ADF のパイプラインとデータセットの JSON 変換には pipeline-migration、Spark ノートブックの変換には spark-cli、T-SQL の変換には sqldw-cli を使用します。

Fabric Dataflow Gen2 — CLI スキル

このスキルは、接続、Power Query M、出力先、保存済みの定義、更新履歴、Gen1 のアップグレードなど、Fabric Dataflow Gen2 アイテムを担当します。

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

セッションごとに1回読んでください。一度読んだファイルはコンテキストに保持されるため、後続のターンで再度読む必要はありません。references/<mode>/ 以下の詳細ファイルを開くのは、そのファイルの参照表の行が必要な内容に一致する場合に限り、該当する行のファイルだけを開いてください。

モードの選択

モード	リクエスト内容	トリガーの例	最初に読むファイル
authoring	接続、資格情報、保存前にプレビューする M の編集、出力先、updateDefinition など、データフローを作成または変更する	executeQuery preview、updateDefinition、接続の設定、supportedConnectionTypes、credentialType、出力先の追加	references/authoring.md
consumption	保存済みデータフローの定義、パラメーター、更新履歴を読み取る、または保存済み／アドホックの読み取り専用 M クエリを実行して Arrow を解析する	getDefinition、executeQuery saved query、アドホッククエリ、Arrow IPC、更新履歴	references/consumption.md
upgrade	Gen1 データフローを save-as と再バインドによって Gen2.1 にアップグレードする、またはアップグレードの準備状況／リスクを評価する	Gen1 Gen2 の準備状況、saveAsNativeArtifact、Gen1 データフローのクローン、アップグレードのリスク評価	references/upgrade.md

モード境界のルール

consumption は読み取り専用です。updateDefinition の前に M を検証するためのプレビュー実行、および機能の検索（supportedConnectionTypes、credentialType）は、同じ executeQuery 呼び出しを行う場合でも authoring に属します。エンドポイントではなく、目的に基づいて分類してください。

リクエストが複数のモードにまたがる場合は、それぞれの作業を1つずつ処理し、着手する前に各リファレンスを読んでください。この表を読んでもモードが不明な場合は、推測せず、簡潔な確認質問を1つしてください。

Terminal write -- 省略してはならない手順

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

モード	Terminal write
authoring	M、接続、出力先を永続化するには、POST /v1/workspaces/{ws}/dataflows/{id}/updateDefinition を実行します。新しいデータフローの場合は、先に POST /v1/workspaces/{ws}/items（または /dataflows）が必要です。executeQuery はプレビューであり、何も書き込みません。ユーザーが更新を依頼した場合は、さらに POST .../jobs/instances?jobType=Refresh を実行します。
consumption	なし -- このモードは読み取り専用です
upgrade	saveAsNativeArtifact で Gen2.1 アーティファクトを作成し、その後再バインドします。準備状況レポートだけでは何もアップグレードされません。

タスクの完了を報告する前に、最後の呼び出しが成功を返したことを確認してください。また、リファレンスに読み戻しが記載されている場合は、アーティファクトを読み戻して変更が反映されたことを確認してください。

upgrade の世代境界 -- 絶対に停止（必須）

Save-as は Gen1 から Gen2.1 への場合にのみ実行できます。実行の依頼で、ソースが Gen2 の場合、またはソースの世代が特定されていない場合は、公開されている save-as エンドポイントもインプレースアップグレードエンドポイントも利用できないことを伝え、API 呼び出しの前に停止してください。これは、Gen1 の候補を見つけて分類することを目的とした、読み取り専用の準備状況スキャンを妨げるものではありません。

「最も近いエンドポイントを選んで続行する」を、定義をエクスポートしてコピーを作成する許可として解釈してはいけません。代わりに authoring に切り替えて実行してもいけません。また、何も変更してはいけません。意図する結果を確認し、明示的な承認を求めてください。

consumption の報告

consumption には Terminal write がないため、成果物は回答そのものです。このモードで executeQuery を実行する場合は、呼び出した操作名と、送信した QueryName をそのまま、結果と並べて記載してください。また、それが保存済みの shared メンバーか、永続化されていないアドホックな customMashupDocument かも明記してください。行だけでは、どの呼び出しによって得られた結果かユーザーには分かりません。

これは consumption のみに適用されます。authoring では、executeQuery は途中のプレビュー手順です。これについて追加の報告を挟まず、最後の書き込みに進んでください。

共通の必須事項（すべてのモード）

まずワークスペースとアイテムを解決してください。すべてのモードでこれが必要です。

タスク	リファレンス	備考
Fabric でのワークスペースとアイテムの検索	COMMON-CLI.md	必須 -- ワークスペースまたはアイテムの ID を解決する前に必ず読んでください
Fabric のトポロジと主要概念	COMMON-CORE.md	アイテムの種類、ワークスペース、容量
環境 URL	COMMON-CORE.md	ソブリンクラウド／非パブリッククラウドのホスト
認証とトークンの取得	COMMON-CORE.md	オーディエンスが誤っていると 401 が発生します。認証に関する問題があれば、まず読んでください
認証の手順	COMMON-CLI.md	az login のフローとトークンの取得
コアのコントロールプレーン REST API	COMMON-CORE.md	ページネーション、LRO のポーリング、レート制限
注意点とトラブルシューティング	COMMON-CLI.md	az rest のオーディエンス、シェルのエスケープ、トークンの有効期限

ルール

MUST

• 他の何よりも先に、上の表からモードをちょうど1つ選択してください。
• そのモードの最初のコマンドを実行する前に、最初のツール呼び出しとして references/<mode>.md を最後まで読んでください。1回だけ、1回の完全な読み込みで読んでください。再度開いたり、再度 grep したり、ページをめくったりしないでください。すでに手元にあります。
• ワークスペースとアイテムの id は、GUID を推測するのではなく、一覧表示とフィルタリングによって解決してください。
• リクエストが境界をまたぐ場合は、モードの切り替えを明示的にアナウンスしてください。
• リファレンスは指示として扱い、決して成果物として扱わないでください。読んだ後は、記載されているコマンドを実際のワークスペースに対して実行し、実際の結果を報告してください。リファレンスに書かれている内容を実行せずに引用しても、リクエストに応えたことにはなりません。
• Fabric が何をサポートしているかについての質問が成果物そのものである場合 -- サポートされる接続タイプ、コネクタのパラメーター、利用可能な資格情報の種類 -- は、リファレンス自体の一覧からではなく、リファレンスが示すエンドポイントから回答し、そのエンドポイントを回答内で明示してください。どのモードにいても同じです。どこから得た値なのかを述べなければ、読み手は実際の値と引用された値を区別できません。これは追加の手順ではなく、最終回答における文言です。
• ユーザーが求めたすべての成果物を、ユーザーが使った名前で作成してください。正しい API 呼び出しを実行することは、求められたレポートの代わりにはなりません。リクエストが成果物を指定している場合は、それを出力し、たとえ発見内容が「なし」や「該当なし」であっても、その見出しは維持してください。

PREFER

• リクエストを満たす最も狭いモード。
• モードのリファレンスをちょうど1つだけ読むこと。2つ目を読み込むのは、リクエストが本当に複数のモードにまたがる場合のみとし、その前にそう述べてください。
• 最初の応答で選択したモードを報告し、ユーザーが訂正できるようにすること。

AVOID

• このディスパッチャーだけに基づいて行動すること -- これは意図的に運用上の詳細を省略しています。
• リファレンスを実行する代わりに、その要約で回答すること。
• すでに読み込んだリファレンスを再度読んだり再度 grep したりすること。ターンとトークンを消費します。
• 読み取り専用モード中に何かを変更すること。
• このスキルがすでに担当している作業に対して別のスキルを読み込むこと（CRITICAL NOTES 3 を参照）。

Examples

User request	Mode	Reference to read
"Show me the refresh history and parameters of the SalesIngest dataflow."	consumption	references/consumption.md
"Preview this M query, then save it into the SalesIngest dataflow definition."	authoring	references/authoring.md
"Is my Gen1 dataflow ready to upgrade to Gen2.1?"	upgrade	references/upgrade.md