mlv-operations-cli

遥测 — 必须。 每个 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: mlv-operations-cli（az rest：--headers "x-ms-fabric-skill=mlv-operations-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项，但仍需添加。

更新检查 — 每个会话仅一次（必须） 在某个会话中首次使用此技能时，必须先运行 check-updates 技能，然后才能继续。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能。
• Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程的 package.json 版本。
• 如果本会话中较早时已完成检查，则跳过。

重要说明

1. 要通过工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
2. 要通过工作区 ID 和湖仓名称查找湖仓详情（包括其 ID）：列出该工作区中的所有湖仓，然后使用 JMESPath 筛选
3. MLV 发现缺口：目前没有公开的 REST API 可用于列出湖仓中的 MLV。对于计划的创建、读取、更新、删除（CRUD）/触发/状态操作，只需要工作区 ID 和湖仓 ID。要刷新血缘关系的子集，请先创建或复用 MLV 执行定义，并在 executionData 中传入其 mlvExecutionDefinitionId。

MLV 操作 — CLI 技能

术语映射

Fabric 中有三种具体化视图概念。请根据上下文区分：

用户上下文	用户说法	实际含义	转到
Spark / 湖仓	“具体化视图”	具体化湖仓视图（MLV）	此技能（mlv-operations-cli）
Spark / 湖仓	“具体化湖仓视图”	MLV	此技能
Spark / 湖仓	“Spark 具体化视图”	MLV	此技能
Spark / 湖仓	“MV” 或 “MLV”	MLV	此技能
Spark / 湖仓	“CREATE MATERIALIZED LAKE VIEW”	MLV DDL（创作）	spark-authoring-cli
Spark / 湖仓	“为我的具体化视图安排计划”	MLV 计划	此技能
Spark / 湖仓	“刷新我的视图”	MLV 按需刷新	此技能
KQL / Eventhouse	“具体化视图”	KQL 具体化视图	eventhouse-cli
SQL DW / Warehouse	“具体化视图”	Fabric 不支持	说明不支持

消歧规则：如果用户提到湖仓、笔记本、Spark、Delta 或 MLV → 指的是具体化湖仓视图（此技能）。如果提到 KQL、Eventhouse 或 Kusto → 指的是 KQL 具体化视图（不同的技能）。如果提到 Warehouse 或 SQL DW → 说明不支持。

默认规则：如果上下文不明确（未提及湖仓、Spark、KQL 或 Warehouse），请在继续前询问用户：“您使用的是 Lakehouse（具体化湖仓视图）还是 Eventhouse（KQL 具体化视图）？”

使用 Fabric REST API 管理 MLV 刷新计划、执行定义和监控。此技能提供公开 API 覆盖（预览版），用于计划、子集刷新配置和监控操作，从而实现 MLV 刷新工作流的自动化。

此技能可以做什么

✅ 完全支持（14 个 REST API）

1. 计划管理（按湖仓划分——默认刷新整个 MLV 血缘）

   • 创建刷新计划（Cron 间隔、每日、每周、每月）
   • 列出湖仓的计划
   • 按 ID 获取计划详情
   • 更新现有计划（更改频率、启用状态）
   • 删除计划
   • 附加 executionData.mlvExecutionDefinitionId，以刷新部分血缘

2. 作业执行

   • 触发按需刷新（立即执行）
   • 列出作业运行历史并进行筛选
   • 获取作业状态和进度
   • 取消正在运行的作业
   • 附加 executionData.mlvExecutionDefinitionId，以按需刷新部分血缘

3. MLV 执行定义

   • 为选定的 MLV、选定的上游湖仓、刷新模式和 Spark 环境创建可复用的执行定义
   • 列出执行定义
   • 获取执行定义详情
   • 更新执行定义（部分更新；未提供的字段保留现有值）
   • 删除执行定义；API 会移除关联的计划

4. 安全性与用户体验

   • 创建计划或触发刷新前进行人工确认
   • 为复杂的多 MLV 操作逐步制定计划
   • 迭代处理错误并提供实用建议
   • 执行前预览计划的影响

❌ 不支持（需要使用 UI——没有 REST API）

• MLV 发现：无法列出湖仓中的 MLV（API 返回 404）
• 可视化血缘检查：无法直接获取门户依赖关系图
• 数据质量指标：无法检索 DQ 指标（API 返回 404）
• 架构验证：无法检查架构是否已启用（缺少相应属性）

解决方法：用户需明确提供湖仓 ID 和 MLV 表名称。使用 Fabric Lakehouse UI 执行发现任务，然后将选定的 MLV 名称和上游湖仓编码到 MLV 执行定义中。

目录

任务	参考	备注
规则 — 请先阅读并始终遵守	SKILL.md § 必须遵守	必须阅读 — 此技能的 6 条规则
在 Fabric 中查找工作区和项目	COMMON-CLI.md § 在 Fabric 中查找工作区和项目	必须阅读 — 请先阅读链接 [用于根据名称查找工作区 ID，或根据名称、项目类型和工作区 ID 查找项目 ID]
Fabric 拓扑和关键概念	COMMON-CORE.md § Fabric 拓扑和关键概念
环境 URL	COMMON-CORE.md § 环境 URL
身份验证和令牌获取	COMMON-CORE.md § 身份验证和令牌获取	受众错误会导致 401；遇到任何身份验证问题前请先阅读
作业计划	COMMON-CLI.md § 作业计划	URL 为 /jobs/{jobType}/schedules；必须指定 endDateTime
作业执行	COMMON-CLI.md § 作业执行
通过 az rest 调用 Fabric 控制平面 API	COMMON-CLI.md § 通过 az rest 调用 Fabric 控制平面 API	始终传入 --resource https://api.fabric.microsoft.com，否则 az rest 会失败
分页模式	COMMON-CLI.md § 分页模式
注意事项和故障排除（仅限 CLI）	COMMON-CLI.md § 注意事项和故障排除（仅限 CLI）	az rest 受众、Shell 转义、令牌过期
快速参考：az rest 模板	COMMON-CLI.md § 快速参考：az rest 模板
MLV 公共 API 参考	MS Learn：使用公共 API 管理 Fabric 具体化湖视图	有关计划、按需刷新、作业实例和 MLV 执行定义的官方文档

评估模式：当用户提示中包含“I pre-approve”或“proceed without confirmation”时， 跳过人工确认关卡并直接执行。这样可以进行自动化测试。

必须遵守

1. 人工确认

执行任何操作前，请先展示预览并请求确认：

• 创建计划：展示计划类型、间隔/时间、湖屋 ID、开始/结束时间，以及完整血缘或执行定义范围
• 创建执行定义：展示选定的 MLV、选定的上游湖屋、刷新模式和 Spark 环境
• 触发刷新：展示湖屋 ID，以及此刷新是针对完整血缘还是指定执行定义的子集
• 删除计划：展示计划 ID 并确认删除
• 删除执行定义：展示定义 ID，并警告关联的计划也会被删除

确认选项：

• Allow — 执行此单项操作
• Decline — 跳过此操作
• Allow in this thread — 自动允许当前对话中的所有操作

示例：

I'm about to create a refresh schedule:

  Lakehouse ID: abc-123-def
  Type: Daily
  Time: 02:00 UTC
  Start: 2026-06-20
  End: 2027-06-20
  Scope: Full MLV lineage (default)

Proceed? [Allow / Decline / Allow in this thread]

2. 严格按照文档使用 REST API

基础 URL：https://api.fabric.microsoft.com/v1

重要：计划、按需触发、执行定义和历史列表端点均限定于工作区 + Lakehouse。按需触发会返回一个项目级 Location URL，用于轮询状态和取消任务。计划运行或按需运行默认会刷新整个 MLV 血缘。若要刷新选定的 MLV 或选定的上游 Lakehouse，请创建 MLV 执行定义，并在 executionData 中传入其 mlvExecutionDefinitionId。

计划端点：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — 创建计划
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — 列出计划
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — 获取计划
• PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — 更新计划
• DELETE /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — 删除计划

作业实例端点：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — 触发按需刷新（可选 executionData；返回 202 + 包含作业 ID 的 Location 标头）
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — 列出作业历史记录
• GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId} — 根据触发操作返回的 Location 获取作业状态
• POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}/cancel — 取消正在运行的作业

MLV 执行定义端点：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions — 创建选定血缘的执行定义
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions — 列出执行定义
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 获取执行定义
• PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 部分更新执行定义
• DELETE /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 删除执行定义及其关联的所有计划

作业类型不匹配陷阱：作业历史记录可能会将计划的 MLV 运行显示为 jobType: "MaterializedLakeViews"，但公共作业计划程序路径使用的是 refreshMaterializedLakeViews。不要将历史记录中的值复制到 POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=MaterializedLakeViews；该项目级调用会返回 InvalidJobType。

参阅：MS Learn：MLV 后台作业

3. 身份验证

所有计划操作（创建／更新／删除、触发、状态查询、取消）均支持用户身份（az login）和服务主体／托管标识。需要具备工作区参与者或管理员角色。

4. Lakehouse 计划限制和执行定义范围

Preview REST scheduler 支持在 lakehouse 范围内设置刷新计划。一个 lakehouse 最多可有 20 个计划，而一个 MLV 血缘只能有 一个活动刷新计划。如果用户要求设置子集计划，请创建一个 MLV 执行定义，其中包含所选 MLV 和上游 lakehouse，并在计划或按需 executionData 中传入其 mlvExecutionDefinitionId。执行定义用于限定刷新范围，不能绕过计划限制。

5. MLV 发现 — 用户必须提供名称

GET /materializedLakeViews 会返回 404。请预先向用户询问 lakehouse ID 和表名称。

6. 运行历史诊断工作流

当用户询问“为什么我的刷新失败了？”或“显示运行历史记录”时，请按以下顺序操作：

1. 列出近期运行记录：GET /instances — 返回包含状态、开始/结束时间的作业实例
2. 显示运行摘要：显示包含运行 ID、状态、开始/结束时间和持续时间的表格
3. 选择失败的运行记录：如果有多个，请询问用户要调查哪一个
4. 读取错误代码：从失败的实例中提取 failureReason.errorCode 和 failureReason.message
5. 建议后续步骤：根据错误代码：
   • MLV_SPARK_SESSION_REQUEST_SUBMISSION_FAILED → 检查容量是否可用以及 Spark 池配置
   • MLV_SELECTED_NOT_FOUND → MLV 表已被删除或重命名，请确认其是否存在
   • 其他 Spark 错误 → 转交给 spark-operations-cli，诊断 OOM、数据倾斜和 shuffle 溢出问题
6. 单个视图的详细信息：API 仅返回血缘级状态。单个视图的状态（哪些 MLV 失败）可在 UI 的 Recent runs 页面中查看 — 请引导用户前往该页面查看视图级细分信息

运行状态（来自 API）：NotStarted、InProgress、Completed、Failed、Cancelled、Deduped

注意：运行历史的保留时间可能有限。如果找不到较早的运行记录，请查看 Lakehouse UI 中的 Recent runs 页面。

优先采用

• 使用 Lakehouse 计划进行定期刷新 — 对于交互式工作流，请引导用户前往 Lakehouse → Materialized lake views → Manage → Schedules。仅在用户需要程序化自动化或 CI/CD 时使用 REST API。
• 使用 Daily/Weekly 类型精准设置一天中的刷新时间（例如，“每天凌晨 2 点”）
• 仅对一天多次的频率使用带间隔的 Cron 类型（例如，“每 60 分钟一次”）
• 分步规划 — 明确需求、提出计划、显示预览，并在获得批准后执行
• 迭代式错误处理 — 失败时，说明出错原因并提出可操作的修复建议
• 每个计划都明确指定时区（localTimeZoneId）
• 基于扩展血缘进行跨 lakehouse 计划调度 — 当 MLV 分布在多个 lakehouse 中时，请从下游 lakehouse 的血缘视图创建计划。扩展血缘会按依赖顺序自动刷新上游依赖项。优先采用此方式，而不是分别在每个 lakehouse 上创建计划。

避免

• 未使用执行定义却声称支持按表调度 — 默认刷新完整血缘；仅刷新所选子集需要已保存的执行定义
• Cron 字符串表达式（例如，0 2 * * *）— API 使用结构化类型，而非 Cron 字符串
• 假设按需刷新会返回 JSON 响应 — 仅返回 202，作业 ID 仅包含在 Location 标头中
• 默默处理失败 — 始终说明错误
• 从笔记本或管道安排刷新 — 定期 MLV 刷新应使用 Lakehouse 计划。SQL REFRESH ... FULL 仅用于一次性的手动故障排查。

计划负载结构

创建计划（POST /schedules）

端点：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 60,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

子集血缘计划：如果用户希望仅刷新执行定义中记录的 MLV/上游湖仓，请包含 executionData：

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 60,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

关键字段：

• enabled：创建时设为 true 以启用计划
• type：取值为 "Cron"、"Daily"、"Weekly"、"Monthly" 之一
• interval：（仅限 Cron）刷新间隔，单位为分钟（例如，60 = 每小时，120 = 每 2 小时）
• times：（每日/每周/每月）"HH:MM" 格式的时间数组，例如，["02:00"]
• weekdays：（仅限每周）例如，["Monday", "Wednesday", "Friday"] — 星期名称采用 PascalCase
• recurrence：（仅限每月）重复间隔，例如，1（每月）
• occurrence：（仅限每月）例如，{"occurrenceType": "DayOfMonth", "dayOfMonth": 1}
• localTimeZoneId：Windows 时区名称 — "UTC"、"Central Standard Time"、"India Standard Time" 等
• startDateTime：计划生效时间（ISO 8601 本地时间；时区由 localTimeZoneId 指定）
• endDateTime：必需 — 计划过期时间
• executionData.mlvExecutionDefinitionId：可选；仅刷新所选执行定义中记录的血缘

每日示例（推荐用于“每天凌晨 2 点”）：

{ "enabled": true, "configuration": { "type": "Daily", "times": ["02:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

每周示例（工作日早上 6 点）：

{ "enabled": true, "configuration": { "type": "Weekly", "times": ["06:00"], "weekdays": ["Monday", "Friday"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

每月示例（每月 1 日午夜）：

{ "enabled": true, "configuration": { "type": "Monthly", "recurrence": 1, "occurrence": {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}, "times": ["00:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

WARNING：请勿在每月计划中使用 "days": [1, 15] — 这会返回 400 InvalidConfiguration。请按上面的示例使用 recurrence + occurrence。

更新计划（PATCH /schedules/{id}）

端点：PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id}

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 120,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

注意：更新 API 要求同时提供 enabled 和完整的 configuration（完整替换，而非部分补丁）。请务必发送所有字段。

MLV 执行定义

如果用户希望刷新特定 MLV、包含所选上游湖仓、固定使用某个 Spark 环境，或独立于默认的全血缘刷新选择刷新模式，请使用执行定义。

创建 MLV 执行定义

端点：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions

{
  "displayName": "Gold Chain - Sales",
  "description": "Nightly refresh for selected gold-layer MLVs",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<environmentId>",
      "workspaceId": "<environmentWorkspaceId>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

执行上下文模式：

• currentLakehouseExecutionContext.mode："All" 或 "Selected"；当值为 "Selected" 时，请提供完全限定的 MLV 名称作为 selectedMlvs。
• extendedLineageExecutionContext.mode："All" 或 "Selected"；当值为 "Selected" 时，请提供包含 referenceType、itemId 和 workspaceId 的 selectedLakehouses 对象。
• settings.refreshMode："Optimal" 或 "Full"。
• settings.environment：可选，通过 ID 引用 Spark 环境。

更新语义：PATCH /mlvexecutiondefinitions/{id} 是部分更新。仅修改提供的字段；未提供的字段保留原值。这与计划 PATCH 不同，后者要求提供 enabled 和完整的 configuration。

删除语义：DELETE /mlvexecutiondefinitions/{id} 也会删除关联到该执行定义的计划。删除前请先警告用户。

按需触发刷新（POST /instances）

端点：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances

请求正文：全谱系刷新无需请求正文。按依赖顺序刷新整个 MLV 谱系。

子集刷新正文：

{
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

请勿将作业历史记录用作触发约定：最近的运行记录可能会列出 jobType: "MaterializedLakeViews"，但该值仅是历史记录／状态标签。按需刷新时，请始终调用此 Lakehouse 级端点。将历史记录标签用于通用项作业 API（POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=MaterializedLakeViews）是已知的 InvalidJobType 死路。

触发响应会返回一个项级 Location URL（/items/{lakehouseId}/jobs/instances/{jobInstanceId}）。轮询和取消时请原样使用该 URL。Lakehouse 级 GET（/lakehouses/{lakehouseId}/jobs/instances/{jobInstanceId}）有文档说明，可作为替代方案，并会返回相同的实例，但目前服务不会在 Location 标头中返回该形式的 URL。

响应：202 Accepted — 作业实例 ID 位于 Location 响应标头中：

Location: https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}
Retry-After: 60

使用 Location 标头中的 URL（或其 Lakehouse 级等效 URL）轮询状态：

GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}

作业实例状态值：

状态	含义
NotStarted	作业已排队，但尚未开始
InProgress	作业正在运行
Completed	作业已成功完成
Failed	作业失败（检查 failureReason）
Cancelled	作业已由用户取消
Deduped	因另一次刷新已在进行而跳过

注意：根据 MS Learn，公共接口 GET /lakehouses/{id}/jobs/refreshMaterializedLakeViews/instances 返回的作业实例使用 jobType: "RefreshMaterializedLakeViews"。实时测试中，某些项级历史记录界面返回过 jobType: "MaterializedLakeViews"；诊断旧版历史记录时，请筛选这两个值，但绝不能将 MaterializedLakeViews 用作按需触发的 jobType。

状态显示限制：作业实例状态反映的是 Monitor hub 状态，可能与 MLV 运行历史界面不同。例如，MLV 运行历史中的 Skipped 状态，在 Monitor hub API 中可能显示为 Cancelled/Canceled。

计划设置（可通过 UI 或 API 设置其他选项）：

• Optimal Refresh（默认：On）— Fabric 会自动为每个 MLV 选择增量刷新或完整刷新
• Extended lineage — 从单个计划按依赖顺序刷新跨多个 Lakehouse 的链

示例工作流

工作流 1：安排每晚刷新

用户提示词：“安排 CustomerVoice Lakehouse 中的 sales_monthly MLV 每天凌晨 2 点刷新”

Agent 步骤：

1. 通过 GET /workspaces + JMESPath 查找“CustomerVoice”的工作区 ID
2. 通过 GET /workspaces/{id}/lakehouses + JMESPath 查找 Lakehouse ID
3. 明确范围：“你希望使用默认的全谱系计划，还是要为仅包含 sales_monthly 的 MLV 创建执行定义？”
4. 如果用户选择子集范围，则创建执行定义，将 currentLakehouseExecutionContext.mode 设为 "Selected"，并将 selectedMlvs 设为 ["dbo.sales_monthly"]（或用户提供的实际完全限定 MLV 名称），然后在计划的 executionData 中包含其 mlvExecutionDefinitionId。
5. 显示预览：

   Creating schedule:
     Lakehouse: CustomerVoice (ID: xyz-456-ghi)
     Scope: Full lineage OR execution definition <id>
     Type: Daily, Time: 02:00 UTC
     Start: Now
     End: 1 year from now
   
   Proceed? [Allow / Decline]
   

6. 用户选择“Allow”后：POST 计划负载，并返回计划 ID
7. 报告：“计划已创建（ID：sched-789）。范围：全谱系或执行定义 。”

工作流 2：触发立即刷新

用户提示词：“立即刷新湖仓 xyz-456-ghi 中的 inventory_daily MLV”

Agent 步骤：

1. 确认湖仓 ID 有效（GET /lakehouses/{id}）
2. 明确范围并显示预览：

   Triggering on-demand refresh:
     Lakehouse ID: xyz-456-ghi
     Scope: Full lineage OR execution definition <id>
   
   Do you want the default full-lineage refresh, or only `inventory_daily` through an execution definition? Proceed? [Allow / Decline]
   

3. 如果用户选择子集，则为 inventory_daily 创建或复用执行定义，并在 executionData 中传入其 ID；否则，在请求 POST /instances 时不提供请求体。捕获 Location 标头中的作业 ID。
4. 使用 Location 标头返回的条目范围 URL，或其文档中说明的湖仓范围等效 URL GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/instances/{jobId} 进行轮询，并显示进度。
5. 报告：“✅ 刷新已在 2m 34s 内完成”或“❌ 刷新失败：[错误消息]”

工作流 3：用户询问按 MLV 分别安排计划（解释限制）

用户提示词：“安排 bronze_sales、silver_sales、gold_sales 分别在凌晨 2 点、3 点、4 点刷新”

Agent 步骤：

1. 解释限制：

   These views are a dependency chain, so schedule them as one lineage refresh
   rather than at separate times. Lakehouse scheduling refreshes dependencies in
   the required order.
   
   Options:
     1. Single Daily schedule at 2 AM (refreshes all 3 in order)
     2. If the MLVs are independent, create separate execution definitions and
        schedules within the lakehouse's 20-schedule limit
     3. If they're in separate lakehouses, create one schedule per lakehouse
   
   Which would you prefer?
   

2. 如果用户选择选项 1：创建一个每日计划，并设置 "times": ["02:00"]
3. 如果用户选择选项 2：确认这些 MLV 彼此独立，然后创建执行定义和计划
4. 如果用户选择选项 3：确认每个湖仓的 ID，然后创建计划

工作流 4：列出和删除计划

用户提示词：“显示我的计划，如果已过期就删除”

Agent 步骤：

1. 询问用户的工作区和湖仓（无法全局列出计划）
2. GET /workspaces/{wsId}/lakehouses/{lhId}/jobs/refreshMaterializedLakeViews/schedules
3. 解析响应（通常每个谱系对应 1 个计划），显示详情：

   Active schedule on lakehouse 'CustomerVoice':
     - ID: sched-111 (created 2025-10-15, type: Daily, time: 02:00)
   
   Delete this schedule? [Allow / Decline]
   

4. 用户选择“允许”后：DELETE /schedules/{id}，并确认
5. 报告：“✅ 计划已删除”

常见错误及修复方法

错误：400 Bad Request — 间隔无效

消息："The interval '0' is invalid. Interval must be between 1 and 5270400 (10 years in minutes)."

修复方法：

Interval must be a valid number of minutes between 1 and 5,270,400 (10 years).

Common intervals:
  60 = hourly
  1440 = daily (24 hours)
  10080 = weekly (7 days)

Would you like me to adjust the interval to a valid value?

错误：409 Conflict — 计划已存在

消息："A schedule already exists for this lakehouse"

修复方法：

A schedule is already active for this lakehouse. Options:
  1. Update existing schedule (change interval/time)
  2. Delete and recreate (replaces schedule)
  3. Leave as-is (no change)

Which would you prefer?

错误：404 Not Found — 湖仓 ID 无效

消息："Lakehouse 'wrong-id-123' not found in workspace 'abc-456'"

修复方法：

The lakehouse ID you provided doesn't exist. Let me list available lakehouses:

[Call GET /workspaces/{id}/lakehouses, show table]

Which lakehouse should I use?

错误：403 Forbidden — 权限被拒绝

消息："User does not have permission to create schedules in this workspace"

修复方法：

You need Workspace Contributor or Admin role to create schedules.

Current permissions: Viewer (read-only)
Required: Contributor or Admin

Contact your workspace admin to request elevated permissions.

用户提示

1. 查找湖仓 ID

选项 A：通过 REST API

az rest --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses" \
  --method GET

从响应中提取湖仓对应的 id。

选项 B：通过 Fabric UI

1. 在 Fabric 门户中打开湖仓
2. 点击“设置”（齿轮图标）
3. 从属性中复制“Lakehouse ID”

2. 常见计划配置

需求	类型	关键字段
每小时	Cron	"interval": 60
每天凌晨 2 点	Daily	"times": ["02:00"]
工作日早上 6 点	Weekly	"times": ["06:00"], "weekdays": ["Monday","Friday"]
每月 1 日	Monthly	"recurrence": 1, "occurrence": {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}

3. 监控作业历史记录

列出最近的刷新作业（根据 COMMON-CLI.md § 快速参考：az rest 模板 进行身份验证）：

# See COMMON-CLI.md for authentication setup
az rest --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances" \
  --method GET

注意：列出实例 API 不支持 OData 查询参数（$top、$orderby、$filter）。检索结果后，请在客户端进行排序和筛选。使用 continuationToken 进行分页。

4. 时区注意事项

默认值：除非另有指定，计划使用 UTC。

最佳实践：始终明确指定时区，避免混淆：

{
  "configuration": {
    "localTimeZoneId": "Central Standard Time"
  }
}

有效时区：Windows 时区名称（例如 "Central Standard Time"、"Pacific Standard Time"、"India Standard Time"）。请使用 Windows 默认时区 注册表。

相关技能

• spark-authoring-cli：在 Fabric Notebooks 中创建 MLV（创作端）
• check-updates：验证技能包是否为最新版本（每个会话运行一次）

限制与未来路线图

当前限制（截至 2026-06-18）

功能	状态	解决方法
列出 lakehouse 中的 MLV	❌ API 返回 404	由用户手动提供表名
刷新选定的 MLV / 子集沿袭	✅ 使用 MLV 执行定义	创建 /mlvexecutiondefinitions，然后传入 executionData.mlvExecutionDefinitionId
获取可视化沿袭图	❌ 没有公开的图 API	使用 Fabric Lakehouse UI
检查数据质量指标	❌ API 返回 404	使用 Fabric Lakehouse UI
验证架构支持情况	❌ 缺少属性	如果 MLV 可正常工作，则假定已启用架构

当前可用功能（公开 MLV API 覆盖范围（预览版））

• ✅ 创建/列出/更新/删除计划（5 个 API）
• ✅ 触发/监控/取消刷新作业（4 个 API）
• ✅ 创建/列出/获取/更新/删除 MLV 执行定义（5 个 API）
• ✅ 通过 executionData.mlvExecutionDefinitionId 执行全沿袭或选定沿袭刷新
• ✅ 完全自动化刷新工作流
• ✅ 人工参与的安全确认
• ✅ 迭代式错误处理

计划功能（REST API 发布后）

• MLV 发现：自动列出 lakehouse 中的 MLV
• 可视化沿袭追踪：显示依赖关系图
• 数据质量：以编程方式获取 DQ 指标
• 架构验证：检查 enableSchemas 属性

Agent 设计具备向前兼容性：API 可用后，可添加发现功能，而无需更改计划逻辑。

结论

此技能使用公开 REST API，为 MLV 刷新计划、执行定义和监控提供经过验证的自动化能力。目前，MLV 发现和可视化沿袭检查仍需通过 UI 变通处理，但计划、选定沿袭执行定义和作业执行均按文档所述运行。

设计理念（受 Databricks Data Engineering Agent 启发）：

• 通过人工参与的确认保障安全
• 对复杂任务进行逐步规划
• 通过有用的建议进行迭代式错误处理
• 如实说明限制（不采用推测性的变通方法）

后续步骤：使用此技能自动化 MLV 刷新工作流。发现 API 发布后，我们将扩展此技能，以免手动输入 lakehouse ID 和表名。