eventschemaset-cli

遥测 — 强制要求。 每次调用 api.fabric.microsoft.com 都必须携带 x-ms-fabric-skill: eventschemaset-cli（az rest：--headers "x-ms-fabric-skill=eventschemaset-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了该标头——仍需添加。

重要说明

1. 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选
3. 技能消歧：对于 EventSchemaSet 目录项（事件类型和消息架构），使用 eventschemaset-cli。Eventstream 是另一种项——用于实时引入和路由的数据管道；对此使用 eventstream-cli。Eventhouse / KQL Database 又是另一种不同的项；对此使用 eventhouse-cli。

Fabric Event Schema Set — CLI 技能

此技能负责 Fabric Event Schema Set：编写目录（创建、重命名、覆盖定义、删除），以及只读检查和解码其 eventTypes 与 schemas。

预览版：Fabric EventSchemaSet 项及其 REST 操作目前处于预览版——其行为、响应结构和可用性可能会发生变化。所有操作文档均说明仅支持委托（用户）身份（不支持服务主体和托管身份），但由于该项处于预览版，SP/MI 访问可能成功，具体取决于租户。建议以用户身份运行 az login；如果使用 SP/MI 时遇到 401/403，请改用委托用户身份。

这是一个模式分发器，不包含任何操作流程。请从下表中选择与请求匹配的模式，然后在执行任何命令之前，使用文件读取工具从头到尾阅读相应的 references/<mode>.md 文件。该文件包含端点、负载结构、模板和注意事项；未阅读就采取行动会导致负载和结果错误。

模式选择

模式	请求内容	示例触发词	先阅读此文件
authoring	创建、重命名/重新描述、覆盖 Event Schema Set 的定义，或删除它（Create、Update、UpdateDefinition、Delete）	创建事件架构集，更新事件架构集定义，向事件架构集添加事件类型，重命名事件架构集，删除事件架构集	references/authoring.md
consumption	列出或搜索 Event Schema Set、检查项属性，或解码定义以枚举其 eventTypes 和 schemas	列出事件架构集，检查事件架构集，解码事件架构集定义，获取架构版本，列出业务事件	references/consumption.md

模式边界规则

consumption 只能发起只读调用（List、Get、GetDefinition）。任何更改状态的操作（Create、Update、UpdateDefinition、Delete）都必须使用 authoring 模式：说明这一点，阅读 references/authoring.md，然后继续。

如果请求确实涉及多种模式（例如先解码当前定义，再覆盖它），请一次处理一个模式，并在开始相应部分之前阅读每个参考文件。如果阅读此表后仍无法确定模式，请提出一个简短的澄清问题，不要猜测。

终端写入——不可跳过的步骤

阅读参考文档并规划更改，并不代表任务已完成。编写模式必须以一次更改状态的调用结束。如果你没有发出该调用，就没有任何内容被持久化——请明确说明这一点，而不要声称已成功。

模式	终端写入
authoring	为执行所请求的更改而调用 POST .../eventSchemaSets、PATCH .../eventSchemaSets/{id}、POST .../eventSchemaSets/{id}/updateDefinition 或 DELETE .../eventSchemaSets/{id}。编写请求正文并展示给用户，并不等于执行了请求。
consumption	无——此模式为只读模式

Create 和 UpdateDefinition 可能会返回 202 Accepted（LRO）：捕获 Location 标头并轮询，直到状态为 Succeeded，然后再报告成功。如果参考文档说明需要回读，请回读产物以证明更改已生效。

共享要点（所有模式）

先解析工作区和项；所有模式都依赖这一步。

任务	参考文档	说明
在 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 受众、Shell 转义、令牌过期

规则

必须

• 在执行任何操作前，先从上表中选择且仅选择一种模式。
• 在该模式的第一条命令之前，先从头到尾阅读 references/<mode>.md，并将其作为你的第一次工具调用。只完整读取一次：不要重新打开，不要再次 grep，也不要逐页浏览。你已经有该文件。
• 对加载的所有其他文件（包括共享的 common/*.md 文件）也遵循只读一次的规则：只打开实际需要的文件，每个文件从头到尾读取一次，不要 grep 或重新打开已加载的文件。
• 通过列出并筛选来解析工作区和项 ID，绝不能猜测 GUID。
• 请求跨越模式边界时，明确宣布模式切换。
• 执行破坏性操作和覆盖操作前必须确认——Delete 是永久操作（使用 ?hardDelete=true），UpdateDefinition 会替换整个定义。如果请求已明确指出目标项和破坏性／覆盖操作（例如“删除 Event Schema Set X”“将 X 的定义覆盖为……”），该指示即为确认：回显已解析的 displayName + id 以供审计，然后执行唯一一次写入。仅当目标或意图含糊时才暂停并单独询问是／否确认（例如“清理我的工作区”、未明确指定对象的“第一个”或批量／通配符删除）。
• 将参考文档视为操作说明，而非最终交付物。阅读后，运行文档中说明的命令以操作实时工作区，并报告真实结果。

优先

• 选择满足请求的最精简模式。
• 只阅读一个模式参考文档。只有当请求确实跨越多个模式时才加载第二个，并在加载前说明。
• 优先使用委派的用户身份（az login）；遇到 401／403 时，从 SP／MI 回退到用户身份。
• 在首次回复中说明你选择的模式，让用户可以纠正你。

避免

• 仅凭此调度器采取行动——它有意省略了操作细节。
• 只总结参考内容，而不执行其中的操作。
• 重新读取或重新搜索已加载的参考内容；这会浪费轮次和令牌。
• 在只读使用模式下修改任何内容。
• 将 EventSchemaSet 与 Eventstream 或 Eventhouse 混淆（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要读取的参考内容
“列出我的 Analytics 工作区中的所有 Event Schema Set。”	consumption	references/consumption.md
“在 Analytics 中创建一个名为 orders-catalog 的 Event Schema Set。”	authoring	references/authoring.md
“解码 orders-catalog 的定义，并告诉我它的事件类型和架构。”	consumption	references/consumption.md
“向 orders-catalog 添加一个 BusinessEventType 事件 OrderPlaced（JSON）。”	authoring	references/authoring.md
“从 Analytics 中删除 orders-catalog-old Event Schema Set。”	authoring	references/authoring.md