dataflows-cli

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

关键说明

1. 要通过工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
2. 要通过工作区 ID、项类型和项名称查找项详情（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 筛选
3. 技能消歧：对于每个 Fabric Dataflow Gen2 项目和 Power Query M 相关事项，使用 dataflows-cli。Synapse / ADF 管道和数据集 JSON 转换使用 pipeline-migration；Spark 笔记本转换使用 spark-cli；T-SQL 转换使用 sqldw-cli。

Fabric Dataflow Gen2——CLI 技能

此技能专用于 Fabric Dataflow Gen2 项目：连接、Power Query M、输出目标、已保存定义、刷新历史记录和 Gen1 升级。

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

每个会话只需阅读一次。已阅读的文件会保留在上下文中，因此后续轮次无需重新阅读；仅当 references/<mode>/ 下的文件符合该文件参考表中仍需处理的某一行时，才打开对应的更深层文件，并且只打开该行对应的文件。

模式选择

模式	适用于请求……	示例触发词	首先阅读此文件
authoring	创建或更改数据流：连接、凭据、保存前预览 M 编辑、输出目标、updateDefinition	executeQuery 预览、updateDefinition、连接设置、supportedConnectionTypes、credentialType、添加输出目标	references/authoring.md
consumption	读取已保存的数据流：定义、参数、刷新历史记录，或运行已保存/临时的只读 M 查询并解析 Arrow	getDefinition、executeQuery 已保存查询、临时查询、Arrow IPC、刷新历史记录	references/consumption.md
upgrade	通过另存为和重新绑定，将 Gen1 数据流升级到 Gen2.1，或评估升级准备情况/风险	Gen1 Gen2 准备情况、saveAsNativeArtifact、克隆 Gen1 数据流、升级风险评估	references/upgrade.md

模式边界规则

consumption 为只读模式。用于在 updateDefinition 之前验证 M 的预览运行，以及任何功能查询（supportedConnectionTypes、credentialType），都属于 authoring，即使它们调用相同的 executeQuery 也是如此——应根据意图分类，而不是根据端点。

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

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

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

模式	终端写入
authoring	调用 POST /v1/workspaces/{ws}/dataflows/{id}/updateDefinition，以持久化 M、连接和输出目标；新建 dataflow 时，必须先调用 POST /v1/workspaces/{ws}/items（或 /dataflows）。executeQuery 只是预览，不会写入任何内容。如果用户要求刷新，还要调用 POST .../jobs/instances?jobType=Refresh。
consumption	无——此模式为只读
upgrade	调用 saveAsNativeArtifact 创建 Gen2.1 工件，然后重新绑定。仅生成就绪情况报告并不会升级任何内容。

在报告任务完成之前，请确认终端调用已成功返回；如果参考资料要求读回，还要读回该工件，以证明更改已生效。

upgrade 代际限制——硬性停止（必须遵守）

另存为操作仅适用于从 Gen1 升级到 Gen2.1。对于源为 Gen2 或源代际尚未确定的执行请求，请说明目前没有公开的另存为或原地升级端点，并在进行任何 API 调用前停止。此限制不适用于只读就绪情况扫描；该扫描旨在发现并分类 Gen1 候选项。

不要将“选择最接近的端点并继续”理解为允许导出定义并创建副本；不要改用 authoring 来完成此操作，也不要进行任何变更。请用户澄清预期结果并明确批准。

consumption 报告要求

consumption 不执行终端写入，因此交付内容就是答案本身。当此模式运行 executeQuery 时，请注明调用的操作名称，并在结果旁逐字注明发送的 QueryName，同时说明它是已保存的 shared 成员，还是未持久化的临时 customMashupDocument。仅凭行数据无法判断产生这些数据的调用。

此要求仅适用于 consumption。在 authoring 中，executeQuery 是中间预览步骤——不要围绕它增加报告环节；应继续执行终端写入。

通用要点（所有模式）

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

任务	参考资料	说明
在 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 转义、令牌过期

规则

MUST

• 在执行任何操作前，必须从上表中准确选择一种模式。
• 作为第一个工具调用，完整阅读 references/<mode>.md，然后才能执行该模式下的第一条命令。只需完整阅读一次：不要重新打开、再次 grep 或分段翻阅。你已经拿到了它。
• 通过列出并筛选来解析工作区和项目 ID，绝不能猜测 GUID。
• 请求跨越模式边界时，必须明确宣布切换模式。
• 将参考文件视为操作说明，而不是交付物。阅读后，必须针对实时工作区执行其中记录的命令，并报告实际结果。只引用参考文件内容而不执行命令，不能算作回答请求。
• 如果交付内容是关于 Fabric 支持什么的问题——例如支持的连接类型、连接器参数或可用的凭据类型——必须依据参考文件指定的终端节点作答，而不是依据参考文件本身的列表，并在答案中注明该终端节点。无论处于哪种模式，除非说明数据来源，否则读者无法判断某个值是实时数据还是引用内容。这是最终答案中的措辞要求，不是额外步骤。
• 必须按用户使用的名称生成其要求的所有产物。执行了正确的 API 调用，并不能代替用户要求的报告：如果请求指定了交付物，就必须输出，并保留其标题，即使结果是“无”或“不适用”。

PREFER

• 选择能够满足请求的最窄模式。
• 只阅读一个模式的参考文件。只有请求确实跨越多个模式时，才加载第二个，并在加载前说明原因。
• 在首次回复中说明所选模式，让用户有机会纠正。

AVOID

• 仅依据此分发说明采取行动——其中有意省略了操作细节。
• 以概述参考文件代替执行操作。
• 重新阅读或再次 grep 已经加载的参考文件；这会浪费轮次和令牌。
• 在只读模式下进行任何修改。
• 为此技能已有的工作加载其他技能（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要阅读的参考文件
“显示 SalesIngest dataflow 的刷新历史记录和参数。”	consumption	references/consumption.md
“预览此 M 查询，然后将其保存到 SalesIngest dataflow 定义中。”	authoring	references/authoring.md
“我的 Gen1 dataflow 是否已准备好升级到 Gen2.1？”	upgrade	references/upgrade.md