spark-consumption-cli について
Microsoft Fabric のデータエンジニアリング向けコマンドラインスキルで、Lakehouse Livy セッション管理と Spark によるデータ探索を扱います。Fabric REST API、認証、リソース検索、データアクセスの手順を示し、セッションの再利用と動的なリソース検索を促します。
主な機能
- 01Fabric ワークスペースとアイテムの検索
- 02Lakehouse Livy セッションの管理
- 03Spark ステートメントの実行と結果取得
- 04スキーマと Lakehouse 間データの探索
- 05OneLake と SQL/TDS によるデータアクセス
- 06ページネーション、長時間処理、スロットリングへの対応
活用シーン
- 01Lakehouse での PySpark 分析
- 02対話型 Livy セッションの再利用や終了
- 03ワークスペースと Lakehouse アイテムの検索
- 04テーブル、スキーマ、ワークスペース間データの調査
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/spark-consumption-cliを入力して読み込まれたか確認します。
詳細
テレメトリ — 必須です。
api.fabric.microsoft.comへのすべての呼び出しにはx-ms-fabric-skill: spark-consumption-cli（az restの場合は--headers "x-ms-fabric-skill=spark-consumption-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 フィルタリングを使用します。
データエンジニアリングの使用量 — CLI スキル
目次
必須／推奨／回避
必ず行うこと
- 新しいセッションを作成する前に、既存のアイドル状態のセッションを確認します
- 動的なワークスペース／レイクハウスの検出を使用します
- COMMON-CLI.md の API パターンに従います
推奨事項
- シンプルなレイクハウスクエリには sqldw-consumption-cli を使用します — レイクハウスの Delta テーブルに対する行数の確認、SELECT、スキーマの調査、フィルタリング、集計には、Spark ではなく
sqlcmd経由で SQL Endpoint を使用します。ユーザーが PySpark、DataFrame、または Spark 固有の機能を明示的に要求した場合にのみ、このスキルを使用してください。 - Delta テーブルには SQL Endpoint を使用します
- 非構造化データ／JSON データや複雑な Python 分析には Livy を使用します
- セッションの新規作成よりも再利用を優先します
回避すること
- ワークスペース ID のハードコード
- 不要なセッションの作成
- LIMIT を指定しない大規模な結果セット
- Lakehouse Livy セッションと Notebook Spark セッションの混同 — このスキルの対象は Lakehouse Livy セッション（
/lakehouses/{lhId}/livyapi/.../sessionsのパブリック Livy API）です。Notebook Spark セッションは、Jobs API（RunNotebook）を使ってノートブックを実行する際に内部で作成され、Livy API では管理されません。ノートブックをジョブとして実行する方法については、SPARK-AUTHORING-CORE.md § Notebook Execution & Job Management を参照してください - ノートブックのセルの記述や生成 —
%%sql、%%configure、PySpark のノートブックセルコード、ノートブックのデプロイ、またはノートブックの実行を求めるプロンプトは、セルでデータをクエリする場合も含め、spark-authoring-cliの対象です。
クイックスタート
環境のセットアップ
COMMON-CORE.md の Environment Detection Pattern を適用して、以下を設定します。
$FABRIC_API_BASEと$FABRIC_RESOURCE_SCOPE- Livy 操作用の
$FABRIC_API_URLと$LIVY_API_PATH
認証：トークンの取得には、COMMON-CLI.md の Environment Detection and API Configuration を使用します
ワークスペースとアイテムの検出
推奨：COMMON-CLI.md のアイテム検出パターン（Fabric 内での項目の検索）を使用して、名前でワークスペースとアイテムを検索します。
代替方法（ワークスペースがすでに分かっている場合）：
# List workspaces
az rest --method get --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces" --query "value[].{name:displayName, id:id}" --output table
read -p "Workspace ID: " workspaceId
# List lakehouses in workspace
az rest --method get --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/items?type=Lakehouse" --query "value[].{name:displayName, id:id}" --output table
read -p "Lakehouse ID: " lakehouseId
Lakehouse Livy セッションの管理
Fabric における 2 種類の Spark セッション — このスキルが管理するのは、パブリック Livy API エンドポイント（
/lakehouses/{lhId}/livyapi/.../sessions）経由で作成される Lakehouse Livy セッションです。これらは、リモートクライアント向けのアドホックな対話型セッションです。Notebook Spark セッションは別の仕組みです。Fabric Notebook の実行時（ポータルまたは Jobs API のRunNotebook経由）に内部で作成され、ノートブックのライフサイクルを通じて管理されます。Livy API では管理されません。
# Check for existing idle Lakehouse Livy session (avoid resource waste)
sessionId=$(az rest --method get --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions" --query "sessions[?state=='idle'][0].id" --output tsv)
# Create if none available - FORCE STARTER POOL USAGE
if [[ -z "$sessionId" ]]; then
cat > /tmp/body.json << 'EOF'
{
"name":"analysis",
"driverMemory":"56g",
"driverCores":8,
"executorMemory":"56g",
"executorCores":8,
"conf": {
"spark.dynamicAllocation.enabled": "true",
"spark.fabric.pool.name": "Starter Pool"
}
}
EOF
sessionId=$(az rest --method post --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions" --body @/tmp/body.json --query "id" --output tsv)
echo "⏳ Waiting for starter pool session to be ready..."
# With starter pools, this should be 3-5 seconds
timeout=30 # Reduced from 90s since starter pools are fast
while [ $timeout -gt 0 ]; do
state=$(az rest --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions/$sessionId" --query "state" --output tsv)
if [[ "$state" == "idle" ]]; then
echo "✅ Session ready in starter pool!"
break
fi
echo " Session state: $state (${timeout}s remaining)"
sleep 3
timeout=$((timeout - 3))
done
fi
データ探索（Fabric 固有のパターン）
# Execute statement (LLM knows Python/Spark syntax)
cat > /tmp/body.json << 'EOF'
{
"code": "spark.sql(\"SHOW TABLES\").show(); df = spark.table(\"your_table\"); df.describe().show()",
"kind": "pyspark"
}
EOF
az rest --method post --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions/$sessionId/statements" --body @/tmp/body.json
Fabric の主なパターン
| パターン | コード | 使用例 |
|---|---|---|
| テーブルの検出 | spark.sql("SHOW TABLES") | 利用可能なテーブルを一覧表示する |
| 複数のレイクハウス間でのクエリ | spark.sql("SELECT * FROM other_workspace.table") | ワークスペースをまたいでクエリする |
| Delta の機能 | df.history(), df.readVersion(1) | タイムトラベル、バージョン管理 |
| スキーマの進化 | df.printSchema() | 構造を把握する |
Lakehouse Livy セッションのクリーンアップ
# Clean up idle Lakehouse Livy sessions (optional)
az rest --method get --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions" --query "sessions[?state=='idle'].id" --output tsv | xargs -I {} az rest --method delete --resource "$FABRIC_RESOURCE_SCOPE" --url "$FABRIC_API_URL/workspaces/$workspaceId/lakehouses/$lakehouseId/$LIVY_API_PATH/sessions/{}"
焦点：このスキルでは、Fabric 固有の REST API パターンを提供します。LLM はすでに Python／Spark の構文を把握しているため、Fabric との統合、セッション管理、API エンドポイントに重点を置いています。