eventhouse-cli

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

重要说明

1. 要根据工作区名称查找工作区详细信息（包括其 ID）：先列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项类型和项名称查找项详细信息（包括其 ID）：先列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选
3. 技能消歧：对于以 KQL 表达或存储在 KQL 数据库中的内容，使用 eventhouse-cli。对于流式拓扑，使用对应的 eventstream-cli 模式；对于针对 Warehouse 或 Lakehouse SQL 终结点的 T-SQL，使用对应的 sqldw-* 技能。

Fabric Eventhouse / KQL 数据库 — CLI 技能

此技能负责 Fabric Eventhouse 和 KQL 数据库：架构与引入管理，以及只读 KQL 分析。

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

模式选择

模式	适用请求	示例触发词	请先阅读
authoring	运行 KQL 管理命令（.create、.alter、.ingest、.drop）、策略、映射、函数或物化视图	创建 kql 表、kql 引入、kql 保留策略、kql 函数、物化视图、kql 映射	references/authoring.md
consumption	运行只读 KQL（where、summarize、join、render）、使用 .show 发现架构，或监控引入状况	kql 查询、查询 eventhouse、时间序列 kql、show tables kql、浏览 eventhouse	references/consumption.md

模式边界规则

consumption 只能执行只读 KQL 和 .show 命令。任何会改变状态的点命令（.create、.alter、.ingest、.drop、.set-or-append）都必须使用 authoring 模式：说明这一点，阅读 references/authoring.md，然后继续。

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

参考索引

请先阅读模式参考；只有任务需要时，才打开下面的主题文件。此处列出了所有参考资料，请从此表中阅读，不要通过其他参考资料中的链接跳转过去。

参考资料	何时阅读
references/authoring.md	任何 authoring 请求——从这里开始
references/authoring-core.md	需要了解创作任务背后的功能矩阵、表/架构、引入、策略、外部表或权限详情时
references/authoring-advanced-operations.md	需要了解具体化视图、存储函数、更新策略、架构演进或监控创作操作时
references/authoring-scripts.md	需要可直接运行的脚本来创建并引入数据、部署架构、导出或配置策略时——从 scripts/ 运行这些脚本，不要阅读它们
references/consumption.md	任何 consumption 请求——从这里开始
references/consumption-discovery-queries.md	需要用于发现架构、表或引入运行状况的 .show 查询时
EVENTHOUSE-CONSUMPTION-CORE.md	连接基础知识、架构发现与安全性、监控、性能最佳实践或常见 KQL 查询模式——编写 KQL 前必须阅读

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

阅读参考资料并规划更改并不代表完成任务。每种变更模式都必须以一次状态变更调用收尾。如果未执行该调用，就没有内容被持久化——请明确说明这一点，不要报告成功。

模式	终端写入
authoring	POST .../v1/rest/mgmt，携带字面量 .create-merge table（或等效的 CREATE TABLE）、.alter 或 .ingest 命令。编写 KQL 管理命令并展示给用户，不代表已经执行。
consumption	无——此模式为只读

报告任务完成前，请确认终端调用已成功返回；若参考资料要求读取回查，还需读取该产物以证明更改已生效。

通用要点（适用于所有模式）

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

任务	参考资料	备注
在 Fabric 中查找工作区和项目	COMMON-CLI.md	必须——解析任何工作区或项目 ID 之前都要阅读
Fabric 拓扑与关键概念	COMMON-CORE.md	项目类型、工作区、容量
环境 URL	COMMON-CORE.md	主权云 / 非公有云主机
身份验证与令牌获取	COMMON-CORE.md	audience 错误会导致 401；遇到任何身份验证问题前都要阅读
身份验证方法	COMMON-CLI.md	az login 流程和令牌获取
核心控制平面 REST API	COMMON-CORE.md	分页、LRO 轮询、速率限制
常见问题与故障排除	COMMON-CLI.md	az rest audience、Shell 转义、令牌过期

规则

MUST

• 在做任何其他事情之前，先从上面的表格中选择且仅选择一种模式。
• 将 references/<mode>.md 从头到尾完整读完，作为你的第一个工具调用，且要在该模式的第一个命令之前完成。只读一次，一次性完整读取：不要重新打开它，不要再次 grep 它，也不要翻页浏览它。你已经拥有它了。
• 对你加载的每一个其他文件都应用同样的只读一次原则，包括嵌套的 references/<mode>/*.md 子参考文件和共享的 common/*.md 文件：只打开你真正需要的那些，每个都从头到尾只读一次，并且绝不 grep 或重新打开你已经加载过的文件。
• 通过列出和筛选来解析工作区和条目 id，绝不要靠猜测 GUID。
• 当请求跨越边界时，明确宣布模式切换。
• 将参考文档视为指令，绝不是交付物。读完之后，针对实时工作区运行文档中记载的命令，并报告真实结果。引用参考文档的内容而不去执行它，并不能回答请求。

PREFER

• 满足请求的最窄模式。
• 只读取一个模式参考文档。仅当请求确实跨越多种模式时才加载第二个，并在加载之前说明这一点。
• 在你的第一次回复中报告你选择的模式，以便用户可以纠正你。

AVOID

• 仅凭这个调度器就采取行动——它有意省略了操作细节。
• 用参考文档的摘要来作答，而不是执行它。
• 重新读取或重新 grep 你已经加载过的参考文档；这会消耗轮次和 token。
• 在只读模式下改动任何内容。
• 为这个族已经负责的工作加载不同的技能（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要读取的参考文档
"How many events arrived per hour in the last day in the Telemetry eventhouse?"	consumption	references/consumption.md
"Create a KQL table for the sensor feed and a 30-day retention policy."	authoring	references/authoring.md
"Show me the tables in the KQL database and their row counts."	consumption	references/consumption.md