关于 spark-consumption-cli
面向 Microsoft Fabric 数据工程的命令行技能，帮助执行 Lakehouse Livy 会话管理和 Spark 数据探索。它提供 Fabric REST API、身份验证、资源发现及数据访问流程，并强调复用会话和动态发现资源。
主要功能
- 01发现 Fabric 工作区与项目
- 02管理 Lakehouse Livy 会话
- 03执行 Spark 语句并读取结果
- 04探索表结构与跨 Lakehouse 数据
- 05通过 OneLake 和 SQL/TDS 访问数据
- 06处理分页、长时操作与限流
适用场景
- 01在 Lakehouse 中运行 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和重试。代码片段中省略了此项，但仍须添加。
检查更新 — 每个会话仅执行一次（必须） 首次在一个会话中使用此技能时，必须先运行 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、架构探索、筛选和聚合时，应通过
sqlcmd使用 SQL Endpoint，而不是 Spark。仅当用户明确要求使用 PySpark、DataFrames 或 Spark 专属功能时，才使用此技能。 - 对 Delta 表使用 SQL Endpoint
- 对非结构化／JSON 数据或复杂 Python 分析使用 Livy
- 优先复用会话，而不是创建新会话
避免
- 硬编码工作区 ID
- 创建不必要的会话
- 不带 LIMIT 获取大量结果
- 混淆 Lakehouse Livy 会话与 Notebook Spark 会话 — 此技能涵盖 Lakehouse Livy 会话（
/lakehouses/{lhId}/livyapi/.../sessions下的公共 Livy API）。运行 Notebook 时通过 Jobs API（RunNotebook）在内部创建 Notebook Spark 会话，且不通过 Livy API 管理。如需将 Notebook 作为作业运行，请参阅 SPARK-AUTHORING-CORE.md § Notebook Execution & Job Management - 编写或生成 Notebook 单元格 — 要求编写
%%sql、%%configure、PySpark Notebook 单元格代码、部署 Notebook 或执行 Notebook 的提示词，都属于spark-authoring-cli，即使单元格会查询数据也是如此。
快速开始
环境设置
应用 COMMON-CORE.md 中的环境检测模式，以设置：
$FABRIC_API_BASE和$FABRIC_RESOURCE_SCOPE- 用于 Livy 操作的
$FABRIC_API_URL和$LIVY_API_PATH
身份验证：使用 COMMON-CLI.md 中「环境检测和 API 配置」部分的令牌获取方式
工作区和项发现
首选：使用 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 中的两种 Spark 会话 — 此技能管理通过公共 Livy API 端点（
/lakehouses/{lhId}/livyapi/.../sessions）创建的 Lakehouse Livy 会话。这些会话供远程客户端进行临时交互式操作。Notebook Spark 会话是另一种机制 — 运行 Fabric Notebook 时（通过门户或 Jobs APIRunNotebook）在内部创建，并通过 Notebook 生命周期管理，而不是通过 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 模式。大模型已了解 Python／Spark 语法 — 我们专注于 Fabric 集成、会话管理和 API 端点。
评论
支持 Markdown