spark-cli

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

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を検索するには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用してください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を検索するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath フィルタリングを使用してください。
3. スキルの使い分け：ノートブックのセルコード（%%sql セルを含む）、名前を指定したノートブックの実行、Livy セッション、Spark の障害のトリアージ、およびマテリアライズド レイク ビューに関するすべて（定義の作成、増分更新の準備状況に関するクエリのレビュー、既存のビューのスケジュール設定、更新、監視、診断）には spark-cli を使用してください。Eventhouse 内の KQL マテリアライズド ビューには eventhouse-cli を使用してください。Warehouse または Lakehouse SQL エンドポイントに対する読み取り専用の T-SQL には sqldw-cli を使用してください。
4. 厳格なルーティング境界：このスキルから Eventhouse／KQL マテリアライズド ビューのリクエストを実行しないでください。eventhouse-cli にルーティングしてください。そのスキルを利用できない場合は、現在のスキルコンテキストではリクエストを完了できないことを伝え、Fabric API を呼び出したりアーティファクトを作成したりせずに終了してください。

Fabric Spark およびマテリアライズド レイク ビュー — CLI スキル

このスキルは、Fabric Spark のすべて（ノートブックのセル作成、ノートブックの実行、Livy セッションの分析、Spark の障害診断、マテリアライズド レイク ビューのライフサイクル全体）を担当します。

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

モードの選択

モード	リクエストの内容	該当する例	最初に読むファイル
authoring	ノートブックのセルコード（PySpark、Scala、SparkR、%%sql、%%configure）を記述する、ノートブックを名前で実行して通常の実行ステータスを報告する、マテリアライズド レイク ビューの定義を作成する、または増分更新の準備状況について MLV クエリをレビューする	ノートブックコードを記述、ノートブックのセルコード、%%sql セル、ノートブックを実行、ノートブックを実行、notebookutils、マテリアライズド レイク ビューを作成、この MLV クエリは増分更新に対応していますか	references/authoring.md
consumption	Lakehouse Livy セッションで対話型のアドホック PySpark を実行する。ノートブックは使用しません	Livy セッションを作成、Livy で計算を実行、PySpark、DataFrame の分析、複数のレイクハウスにまたがるテーブルの結合、Delta のタイムトラベル	references/consumption.md
operations	FAILED、異常、スロットリング、または低速の Spark ノートブック／パイプライン／Livy の実行を診断する	ノートブックの失敗、Spark Livy の正常性、Spark OOM、ノートブックが遅い理由、ジョブの診断、430 スロットリング	references/operations.md
mlv	既存のマテリアライズド レイク ビューを検出または操作する：Spark SQL による検出、更新スケジュール、オンデマンド更新、実行履歴、キャンセル、更新失敗の分類	MLV を検出、マテリアライズド レイク ビューを一覧表示、MLV をスケジュール、MLV の実行履歴、更新をキャンセル、MLV の更新を開始、MLV の更新失敗を診断	references/mlv.md

モード境界ルール

モードは言語ではなく、成果物と結果によって決まります。ノートブックのセルは、セルが %%sql であっても常に authoring です。Livy セッションは常に consumption です。FAILED になった、または正常でない Spark の実行は operations です。成功した実行は authoring で報告します。Materialized Lake View では動詞によって決まります。定義の作成またはレビューは authoring で、既存の MLV の検出、スケジュール設定、更新、監視、診断は mlv です。検出を実行する必要がある場合は、references/mlv.md から検出コマンドを読んでから、Livy の場合は consumption に、ノートブックの場合は authoring に切り替えます。

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

最終書き込み -- 省略してはならないステップ

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

モード	最終書き込み
authoring	既存のノートブックの場合は、セルを保存するために POST .../notebooks/{id}/updateDefinition を実行します。新しいノートブックの場合は、まず POST /v1/workspaces/{ws}/items が必要です。実行リクエストの場合は、Jobs API を使用してジョブをトリガーします。セルのコードをチャットに出力しても、保存または実行したことにはなりません。
consumption	なし -- このモードは読み取り専用です
operations	なし -- このモードは読み取り専用です
mlv	オンデマンド更新の場合は POST /v1/workspaces/{ws}/lakehouses/{lakehouse}/jobs/refreshMaterializedLakeViews/instances を実行します。スケジュール設定のリクエストの場合は、スケジュールの作成／更新／削除の呼び出しを実行します。予定されるスケジュールを報告するだけでは、作成したことにはなりません。

タスクの完了を報告する前に、最終呼び出しが成功を返したことを確認します。また、リファレンスに読み戻しの手順が記載されている場合は、成果物を読み戻して変更が反映されたことを確認します。

共通の必須事項（全モード）

まずワークスペースとアイテムを特定します。すべてのモードで必要です。

タスク	リファレンス	注意事項
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 のオーディエンス、シェルでのエスケープ、トークンの有効期限

ルール

必須

• ほかのことを始める前に、上の表からモードを必ず1つだけ選択します。
• 「データをセットアップして」のような曖昧な依頼は、スコープが不十分だと判断します。ユーザーが求めている成果物、ソース、宛先、結果を確認します。既存のノートブックやジョブを見つけて実行し、意図を推測してはいけません。
• そのモードの最初のコマンドを実行する前に、最初のツール呼び出しとして references/<mode>.md を最初から最後まで読みます。一度の完全な読み取りで済ませ、再度開いたり、もう一度 grep したり、ページごとに読んだりしてはいけません。すでに読み取り済みです。
• 読み取りは一度だけという同じルールを、ネストされた references/<mode>/*.md のサブリファレンスや共有 common/*.md ファイルを含め、読み込むほかのすべてのファイルにも適用します。実際に必要なファイルだけを開き、それぞれを最初から最後まで一度だけ読み、読み込み済みのファイルを grep したり再度開いたりしてはいけません。
• ワークスペース ID とアイテム ID は、推測で GUID を指定せず、一覧表示して絞り込んで特定します。
• Eventhouse／KQL のマテリアライズドビューに関する依頼は、ルーティングした時点で終了します。利用できない関連スキルは対応を妨げる境界であり、そのワークロードを直接実装する許可ではありません。
• 依頼が境界をまたぐ場合は、モードを切り替えることを明示します。
• リファレンスは指示として扱い、成果物として扱ってはいけません。読み取り後、記載されたコマンドをライブワークスペースに対して実行し、実際の結果を報告します。リファレンスの内容を引用するだけでは、依頼に回答したことになりません。

推奨

• 依頼を満たす、最も範囲の狭いモードを選択します。
• モードのリファレンスは1つだけ読むのが原則です。依頼が実際に複数のモードにまたがる場合に限り2つ目を読み、その前に理由を伝えます。
• 最初の応答で選択したモードをユーザーに伝え、必要であれば訂正できるようにします。

避けること

• このディスパッチャーだけを根拠に行動すること。運用上の詳細は意図的に省かれています。
• リファレンスの要約で回答し、実行しないこと。
• 読み取り済みのリファレンスを再読したり、再度 grep したりすること。ターンとトークンを無駄にします。
• 読み取り専用モードで何かを変更すること。
• この一連の作業を担当する別のスキルを読み込むこと（CRITICAL NOTES 3 を参照）。
• 担当スキルが利用できない場合に、未対応の依頼を生の REST 呼び出しで実行しようとすること。担当スキルの名前を伝えて終了し、spark-cli の範囲外で Fabric アーティファクトを作成するなど、独自の方法で対応してはいけません。

例

ユーザーの依頼	モード	読み取るリファレンス
「ブロンズテーブルを読み込み、シルバーの Delta テーブルに書き込むノートブックのセルを作成してください。」	authoring	references/authoring.md
「Livy セッションを作成し、レイクハウス内の個別顧客数を数えてください。」	consumption	references/consumption.md
「ノートブックの実行が OOM で失敗しました。原因を調べてください。」	operations	references/operations.md
「このマテリアライズドレイクビューのクエリは、増分更新に対応できる状態ですか？」	authoring	references/authoring.md
「スキーマ silver 内の MLV を一覧表示する Spark SQL コマンドを教えてください。」	mlv	references/mlv.md
「レイクハウス MLV のリネージュを毎晩更新するようスケジュールし、実行履歴を表示してください。」	mlv	references/mlv.md