spark-authoring-cli について
spark-authoring-cli は、Microsoft Fabric のデータエンジニア向けスキルです。REST API による Spark アーティファクトの管理と Fabric Notebook のコード作成を扱い、ワークスペース、Lakehouse、Notebook、ジョブなどを案内します。
主な機能
- 01REST API による Fabric アーティファクト管理
- 02PySpark、Scala、SparkR、SQL の作成
- 03Notebook の取得と更新の案内
- 04ジョブ実行とスケジュール設定
- 05認証とデータアクセスの説明
活用シーン
- 01ワークスペース内の Lakehouse と Notebook の管理
- 02Spark ジョブの実行やスケジュール設定
- 03API を介した Notebook 内容の変更
- 04Fabric Notebook コードの作成とデバッグ
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/spark-authoring-cliを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
resources/data-engineering-patterns.mddevelopment-workflow.mdinfrastructure-orchestration.mdmaterialized-lake-view-patterns.mdmlv-incremental-refresh-patterns.mdnotebook-api-operations.md詳細
テレメトリ — 必須。 すべての
api.fabric.microsoft.com呼び出しにはx-ms-fabric-skill: spark-authoring-cliを付ける必要があります（az restの場合は--headers "x-ms-fabric-skill=spark-authoring-cli"）。 すべての LRO ポーリング、fabric_lro、リトライにも付けてください。コード例では省略されていますが、必ず追加してください。
更新チェック — セッションごとに 1 回（必須） このスキルをセッションで初めて使用するときは、作業を進める前に check-updates スキルを実行してください。
- GitHub Copilot CLI / VS Code：
check-updatesスキルを呼び出してください。- Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートの package.json のバージョンを比較してください。
- このセッション中にすでにチェックを実施している場合は、スキップしてください。
重要な注意事項
- ワークスペース名から詳細（ID を含む）を確認するには、すべてのワークスペースを一覧表示し、その後、JMESPath でフィルタリングしてください。
- ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を確認するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示し、その後、JMESPath でフィルタリングしてください。
Spark オーサリング — CLI スキル
このスキルでは、相互に補完する 2 つの領域を扱います。（1）REST API を使用した Fabric Spark アーティファクト（ワークスペース、レイクハウス、ノートブック、ジョブ、パイプライン）の管理、（2）Fabric ノートブックのセル内でのコード作成（レイクハウスへの適切なアクセス、notebookutils、Spark 構成を含む PySpark、Scala、SparkR、SQL）。ノートブックのコード作成の基礎と共有モジュールについては、必ず SPARK-NOTEBOOK-AUTHORING-CORE.md を参照してください。
目次
必須／推奨／回避
必ず行うこと
- 新しいノートブックの実行を作成する前に、最近のジョブを確認する — 過去 5 分間のジョブインスタンスを照会します。最近のジョブが存在する場合は、重複して作成せず、そのジョブを監視します
- POST の直後にジョブインスタンス ID を取得する — 適切に監視できるよう、ほかの操作を行う前にジョブ ID を保存します
- 操作を行う前に、ワークスペースの容量割り当てを確認する — ワークスペースには容量が割り当てられ、アクティブになっている必要があります
- ユーザーからパブリックデータの URL が提供された場合は、Public URL Data Ingestion ポリシーに従う — 動作の詳細はリンク先のリソースセクションに記載し、内容のずれや重複を避けます
- ノートブックのセルを正しい形式にする — コードが連結されないよう、セルのソース配列内の各行は必ず
\nで終わらせます - Lakehouse Livy セッションの本文には正しい形式を使用する —
name、driverMemory、driverCores、executorMemory、executorCoresを含むフラットな JSON を送信します。{"payload": ...}でラップしたり、{"kind": "pyspark"}だけを送信したりしないでください。HTTP 500 エラーが発生します。有効なメモリ値（28g、56g、112g、224g）を使用してください。以下の Create Lakehouse Livy Session の例と SPARK-CONSUMPTION-CORE.md を参照してください
推奨事項
- 適切な間隔でジョブの状態をポーリングする — ポーリングの間隔は 10～30 秒とし、妥当な時間（例：30 分）を過ぎたらタイムアウトします
- POST の応答が読み取れない場合は、ジョブ履歴を確認する — POST が「No Content」または読み取れない応答を返した場合は、再試行する前に最近のジョブ（過去 1 分間）を照会します
- 開発には Starter Pool を使用する — 開発／テストのワークロードでは
useStarterPool: trueを使用します - 本番環境には Workspace Pool を使用する — 本番環境のワークロードで一貫したパフォーマンスを得るには、
useWorkspacePool: trueを使用します - 作成時に Lakehouse のスキーマを有効にする — テーブルをより適切に整理するには、
creationPayload.enableSchemas: trueを設定します - 冪等性チェックを実装する — 既存の状態を先に確認し、操作の重複を防ぎます
避けること
- 同じパラメーターで POST を再試行しない — ジョブ ID を取得済みの場合は、状態の確認には GET のみを使用し、重複するジョブインスタンスを作成しないでください
- 容量の確認を省略しない — ワークスペースの容量が一時停止中、または割り当てられていない場合、操作は失敗します
- 失敗直後に POST を再試行しない — 重複を防ぐため、まず既存のジョブや実行中のジョブを確認します
- 既存のジョブを監視している間に新しい実行を作成しない — ジョブは一度に 1 つだけにします。新しい実行を送信する前に、現在のジョブが完了するのを待ちます
- ワークスペース ID／Lakehouse ID をハードコードしない — アイテム一覧表示 API またはカタログ検索 API を使用して動的に検出します
%%sqlノートブックセルはここで担当し、sqldw-consumption-cliに委ねない — 「%%sqlセルを書く」という依頼（または任意のノートブックマジックセルの依頼）は、セルから Lakehouse テーブルをクエリする場合でも、ノートブックセルの作成に該当します。ユーザーがノートブックセルではなく、SQL エンドポイントに対して通常の T-SQL クエリを実行したい場合に限り、sqldw-consumption-cliにルーティングします- 「ノートブック X を実行する」はここで担当する — 名前を指定して Fabric ノートブックを実行するのは、Jobs API（
RunNotebook）を介したノートブック実行であり、このスキルの範囲です。spark-consumption-cliに委ねないでください。このスキルはアドホックな Livy セッションでコードを実行する場合にのみ使用します - Fabric ノートブックの実行に Lakehouse Livy セッションを使用しない — Lakehouse Livy セッション（パブリック Livy API）は、アドホックな対話型 Spark コードの実行に使用します。ノートブックをジョブとして実行するには、Jobs API（
RunNotebook）を使用してください。これにより、内部で Notebook Spark セッションが作成されます。SPARK-AUTHORING-CORE.md § Notebook Execution & Job Management を参照してください - ノートブックから MLV の更新をスケジュールしない — ユーザーが「MLV の更新をスケジュールする」よう求めた場合は、REST API を使用する mlv-operations-cli にルーティングします。ノートブックで実行する
REFRESH MATERIALIZED LAKE VIEW ... FULLは、定期的なスケジュールではなく、1 回限りの手動更新にのみ使用します
ルール — 最初に読み、常に遵守してください
ルール 1 — 操作の前に前提条件を確認します。 ワークスペースに容量が割り当てられていること（COMMON-CORE.md のワークスペースの作成と容量管理を参照）と、リソース ID が存在することを、操作を試みる前に確認してください。
ルール 2 — updateDefinition の成功を信頼します。
updateDefinitionのポーリング結果がSucceededであれば、コンテンツとレイクハウスのバインドが保持されたことを確認するには十分です。アップロードのたびにgetDefinitionを呼び出さないでください。これは大幅な遅延を招く非同期 LRO です。getDefinitionは、本来の用途である変更前の現在のノートブックコンテンツの読み取りにのみ使用してください。ルール 3 — ジョブの重複を防ぎ、実行状況を適切に監視します。 新しいノートブックの実行を送信する前に、必ず最近のジョブインスタンス（直近 5 分間）を確認してください。最近のジョブが存在する場合は、重複して作成せず、そのジョブを監視してください。送信後は、直ちにジョブインスタンス ID を取得してステータスをポーリングしてください。POST を再試行してはいけません。パターンについては SPARK-AUTHORING-CORE.md のジョブの監視を参照してください。
ルール 4 — ノートブックのコードを作成する場合は、必ず SPARK-NOTEBOOK-AUTHORING-CORE.md に従ってください。 ノートブックのセル内にコードを書く場合は、必ず最初に SPARK-NOTEBOOK-AUTHORING-CORE.md を読んでください。このドキュメントでは、コード生成のアプローチとルール、および詳細ガイド（レイクハウスのパス、接続、コンテキスト、オーケストレーションなど）へのリンクを含むモジュールインデックスを定義しています。このスキルの Spark 専用リソース（data-engineering-patterns.md、development-workflow.md）は、Spark 固有の実装詳細に使用してください。タスクがマテリアライズドレイクビューに関するものである場合は、作成と設計のガイダンスについて materialized-lake-view-patterns.md を、更新準備状況の分析について mlv-incremental-refresh-patterns.md を読んでください。
ノートブックのコード生成に関するクイックルール
ノートブック作成でよく使うタスクのクイックリファレンスです。共有の common/notebook-authoring/ コア（ルール 4／SPARK-NOTEBOOK-AUTHORING-CORE.md を参照）が正式な基準です。内容に相違がある場合は、共有コアに従ってください。
| ユーザーの依頼 | 必須の出力パターン |
|---|---|
%%sql／レイクハウスをまたぐクエリセル | Fabric ノートブックの %%sql セルを返してください。コードまたは説明の注記に、指定されたワークスペース、レイクハウス、スキーマ、テーブルを含めてください。これはノートブックの作成であり、Spark を対話的に利用するものではありません。 |
| パイプラインのコンテキスト検出 | notebookutils.runtime.context を使用し、isForPipeline = context["isForPipeline"] を含め、context["currentWorkspaceId"] を読み取ってください。 |
| Spark での組み込みノートブックリソースファイル | notebookutils.nbResPath、builtin/、file: プレフィックスを使用してください。spark.read.json(f"file:{notebookutils.nbResPath}/builtin/config.json") のようにします。Spark と notebookutils.fs でリソースフォルダーのローカルパスを使用するには、file: が必要です。 |
| Fabric 接続 | notebookutils.connections.getCredential("{connectionId}") を直接使用し、簡潔なコードサンプルを示してください。ウェブ検索は行わず、ツール／ターンの予算内に回答を収めてください。 |
最小限のスニペット
# Pipeline context
context = notebookutils.runtime.context
isForPipeline = context["isForPipeline"]
workspace_id = context["currentWorkspaceId"]
print(f"isForPipeline={isForPipeline}, workspace_id={workspace_id}")
# Spark read from notebook built-in resources
config_df = spark.read.option("multiline", "true").json(
f"file:{notebookutils.nbResPath}/builtin/config.json"
)
display(config_df)
# PostgreSQL through a Fabric connection (fill in connectionId and host/db)
import psycopg2
credential = notebookutils.connections.getCredential("{connectionId}")
conn = psycopg2.connect(
host="<postgres-host>",
database="<database>",
user=credential["username"],
password=credential["password"],
)
クイックスタートの例
詳細なパターン、認証、包括的な API の使用方法については、以下を参照してください。
- COMMON-CORE.md — Fabric REST API のパターン、認証、アイテムの検出
- COMMON-CLI.md —
az restの使用方法、環境の検出、トークンの取得 - SPARK-AUTHORING-CORE.md — ノートブックのデプロイ、レイクハウスの作成、ジョブの実行
以下に最小限のクイックスタート例を示します。本番環境で使用する場合は、必ず COMMON-* ファイルを参照してください。
ワークスペースとレイクハウスの作成
# See COMMON-CORE.md Environment URLs and SPARK-AUTHORING-CORE.md for full patterns
cat > /tmp/body.json << 'EOF'
{"displayName": "DataEng-Dev"}
EOF
workspace_id=$(az rest --method post --resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces" \
--body @/tmp/body.json --query "id" --output tsv)
cat > /tmp/body.json << 'EOF'
{"displayName": "DevLakehouse", "type": "Lakehouse", "creationPayload": {"enableSchemas": true}}
EOF
lakehouse_id=$(az rest --method post --resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces/$workspace_id/items" \
--body @/tmp/body.json --query "id" --output tsv)
スキーマを使用したレイクハウステーブルの整理
# See SPARK-AUTHORING-CORE.md Lakehouse Schema Organization for table organization patterns
#
# IMPORTANT: `CREATE SCHEMA` is only supported on schema-enabled lakehouses. On a
# lakehouse created WITHOUT `enableSchemas`, it fails with
# "Feature not supported on Apache Spark in Microsoft Fabric". Always detect schema
# support first, then branch: create schemas only when enabled, otherwise skip.
# Schema names are configurable. If your workspace standard is `raw`/`curated`
# instead of `bronze`/`silver`/`gold`, substitute those names consistently.
import uuid
def lakehouse_is_schema_enabled():
# Probe schema support by attempting CREATE SCHEMA and catching the
# platform-blocked error. Use a unique probe schema name to avoid
# accidentally dropping a real pre-existing schema.
probe = f"_schema_probe_{uuid.uuid4().hex}"
try:
spark.sql(f"CREATE SCHEMA IF NOT EXISTS {probe}")
spark.sql(f"DROP SCHEMA IF EXISTS {probe}")
return True
except Exception as e:
if "Feature not supported on Apache Spark in Microsoft Fabric" in str(e):
return False
raise
if lakehouse_is_schema_enabled():
# Schema-enabled: create medallion schemas and write tables as `schema.table`.
spark.sql("CREATE SCHEMA IF NOT EXISTS bronze")
spark.sql("CREATE SCHEMA IF NOT EXISTS silver")
spark.sql("CREATE SCHEMA IF NOT EXISTS gold")
else:
# Not schema-enabled: skip CREATE SCHEMA (unsupported). Organize tables by name
# prefix instead (e.g. `bronze_orders` / `raw_orders`, `silver_orders` /
# `curated_orders`), or recreate the lakehouse with
# `creationPayload.enableSchemas: true` if schemas are required.
print("Lakehouse is not schema-enabled; skipping schema creation and using name prefixes.")
マテリアライズドレイクビュー（MLV）の作成と更新
-- See resources/materialized-lake-view-patterns.md for design guidance
-- and resources/mlv-incremental-refresh-patterns.md for refresh-readiness review.
-- Bronze/Silver/Gold schemas in a Lakehouse with schemas enabled
CREATE SCHEMA IF NOT EXISTS bronze;
CREATE SCHEMA IF NOT EXISTS silver;
CREATE SCHEMA IF NOT EXISTS gold;
-- A simple Silver MLV with data quality constraints
--
-- Prerequisite for incremental refresh: enable Change Data Feed (CDF) on every
-- source table the MLV reads from. Without CDF, optimal refresh can only choose
-- between no refresh (sources unchanged) and full refresh — never incremental.
-- See resources/mlv-incremental-refresh-patterns.md.
ALTER TABLE bronze.orders_raw SET TBLPROPERTIES (delta.enableChangeDataFeed = true);
CREATE OR REPLACE MATERIALIZED LAKE VIEW silver.orders_clean
(
CONSTRAINT valid_order_id CHECK (order_id IS NOT NULL) ON MISMATCH DROP
)
AS
SELECT
order_id,
customer_id,
CAST(order_ts AS TIMESTAMP) AS order_ts,
amount
FROM bronze.orders_raw;
-- Routine refresh is handled by the lakehouse Materialized lake views → Manage
-- schedule/lineage view; don't orchestrate from notebooks. The SQL form below is
-- documented only for forcing a one-time FULL recompute (troubleshooting / after
-- a correction). There is no documented SQL form for triggering incremental refresh.
REFRESH MATERIALIZED LAKE VIEW silver.orders_clean FULL;
Lakehouse Livy セッションの作成
# See SPARK-CONSUMPTION-CORE.md for Lakehouse Livy session configuration and management
# IMPORTANT: Body MUST be flat JSON with memory/cores — do NOT wrap in {"payload": ...}
cat > /tmp/body.json << 'EOF'
{"name": "dev-session", "driverMemory": "56g", "driverCores": 8, "executorMemory": "56g", "executorCores": 8, "conf": {"spark.dynamicAllocation.enabled": "true", "spark.fabric.pool.name": "Starter Pool"}}
EOF
az rest --method post --resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces/$workspace_id/lakehouses/$lakehouse_id/livyapi/versions/2023-12-01/sessions" \
--body @/tmp/body.json
Lakehouse Livy セッションの本文 — よくある間違い
- ❌
{"payload": {"kind": "pyspark"}}→ HTTP 500（ラッパーが誤っており、必須フィールドがありません）- ❌
{"kind": "pyspark"}→ HTTP 500（driverMemory、executorMemoryなどがありません）- ✅
name、driverMemory、driverCores、executorMemory、executorCoresを含むフラットな JSON（Starter Pool の場合は、任意でconfも指定）
Spark のパフォーマンス設定
ワークロード別の詳細な設定については、data-engineering-patterns.md の Delta Lake のベストプラクティスを参照してください。
クイックリファレンス：
# Write-heavy (Bronze): Disable V-Order, enable autoCompact
# Balanced (Silver): Enable V-Order, adaptive execution
# Read-heavy (Gold): Vectorized reads, optimal parallelism
# See data-engineering-patterns.md for complete config tables
焦点：Spark／データエンジニアリング開発とノートブックのコード作成に不可欠な CLI パターンを紹介し、専門リソースへインテリジェントにルーティングします。包括的なパターンについては、必ず COMMON-* ファイルとリソースドキュメントを参照してください。
コメント
Markdown 対応