synapse-migration

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

离线 Lakehouse 构件快速路径——优先判断。 对于无需实时调用、且已提供完整输入和契约的请求，只加载快速路径；不要加载 migration-planning-reference.md、dedicated-pool-conversion.md 或实现脚本。使用一个生成器生成构件和最终字节哈希，然后使用一个验证器。不要检查生成的文件，也不要运行后续抽查。对于每个可选的非空源默认值，将 missingValueBehavior 设为 UseSourceDefault，并在验证前恢复该默认值。目标为 Warehouse 时，不要使用此路径；输入不完整和大型过程请求应使用各自的路径。

重要注意事项

1. 要通过工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选。
2. 要通过工作区 ID、项类型和项名称查找项详细信息（包括其 ID）：列出该工作区中此类型的所有项，然后使用 JMESPath 进行筛选。
3. 将源 Dedicated SQL Pool 视为只读。不要运行源 DDL、DML、存储过程，也不要创建示例对象。
4. Dedicated Pool 到 Lakehouse 的数据移动不在范围内。仅迁移架构和可执行代码构件；不要复制源行，也不要运行行级／业务结果等价性查询。单独的 Warehouse 路径仅可在独立获批的已还原导出副本上移动数据，并须遵循其自身的同意门槛和已还原源契约。
5. 对于 Dedicated Pool 到 Lakehouse 的请求，必须依次完成差距评估、明确的映射审批、清单创建、转换、部署和验证。只需将 dedicated-pool-to-lakehouse.md 作为路由指南读取一次，然后仅加载当前阶段的参考资料。
6. 存储过程的 1:1、N:1 和 N:N 映射绝不适用于视图。视图仍是架构对象；过程则会转换为可追踪的 Spark SQL 笔记本，其中包含可执行的 %%sql 转换单元。
7. 依赖项 ADF／Synapse 调用方属于有条件的范围，而非自动纳入范围。在评估期间发现它们，要求单独批准完整闭包，并且仅在笔记本就绪后迁移。独立的管道请求应路由至 pipeline-migration。
8. 执行专门的 Dedicated Pool 工作流之前，先阅读 dedicated-pool-execution-contracts.md 中对应的契约。该契约对验证、哈希、请求正文、续接和完成措辞的要求均为强制要求。
9. 将 Lakehouse 和 Warehouse 路径分开。如果目标不明确，在加载路径专属资源之前先询问。Lakehouse 转换绝不移动源行；Warehouse 数据迁移需要其自身的明确同意门槛和已还原源契约。
10. 对于 Fabric Warehouse 目标，必须明确说明完整的 DISTRIBUTION 和 CLUSTERED COLUMNSTORE INDEX 声明将被移除，因为 Fabric 会管理分布、存储和索引；仅简单提及这两个源子句并不足够。
11. 只有在证明副本不是原始生产源后，才能对单独获批的已还原导出副本运行设置 DDL 和 CETAS。

Synapse Analytics 到 Microsoft Fabric 迁移

核心工作流

1. 发现 Synapse 工作区，并对每个源工件进行分类。
2. 根据 workload-routing.md 选择目标。
3. 在转换前评估差距，包括运行时、库、连接性、T-SQL、安全性和容量限制。
4. 对会改变行为的决策、目标位置以及每个存储过程到笔记本的映射，获取批准。
5. 创建或更新 migration-manifest.json，并以原子方式持久化审批、每个对象的状态、哈希值和检查点。
6. 按依赖顺序转换和部署，仅加载当前阶段的资源。
7. 验证持久化的定义和工件；除非单独批准的工作流明确要求执行，否则不要执行生成的笔记本或管道。
8. 报告已完成、受阻、已跳过和待处理的对象，不得暴露凭据或敏感值。

如需编排整个工作区，请阅读 migration-orchestrator.md。如需将 Dedicated Pool 迁移到 Lakehouse，请使用 dedicated-pool-to-lakehouse.md 作为阶段路由器。若目标为 Warehouse，只加载匹配的 dw-* 资源。

范围路由

请求	操作	加载
完整的 Synapse 工作区迁移	执行分阶段发现和迁移	migration-orchestrator.md
将 Dedicated SQL Pool 架构/代码迁移到 Lakehouse	执行严格的评估到验证工作流。对于仅供指导的笔记本发布，明确说明：“存储过程在发布前已从 T-SQL 转换为 Spark SQL。”	dedicated-pool-to-lakehouse.md
仅供指导的 Dedicated Pool 增量部署强化	直接根据专门的检查清单作答；不要搜索脚本或加载阶段资源。说明：“对于包含特殊字符的列，请仅在获得批准后有选择地启用 Delta columnMapping。”	dedicated-pool-execution-contracts.md
大型或复杂的存储过程	如需完整的离线契约，只读取一次审计资源，使用一个仅限本次运行的生成器和一个验证器，不检查实现脚本或生成的输出，并在验证成功后停止	dedicated-pool-large-procedure-audit.md
Spark 池	将配置和库转换为 Fabric Environment	spark-pool-migration.md
Lake Database 或 HMS	创建或绑定目标 Lakehouse	lake-database-migration.md 或 external-hms-migration.md
笔记本或 Spark Job Definition	移植代码、绑定、参数和运行时设置	spark-item-migration.md
Linked Service	对于外部服务，选择 Fabric Data Connection；对于 ADLS Gen2/Blob，选择 OneLake Shortcut	connectivity-migration.md
已批准的依赖存储过程调用方	笔记本回读后，运行保留闭包的内部子流程	dedicated-pool-dependent-pipelines.md
独立管道迁移	委派	pipeline-migration
Dedicated SQL Pool 迁移到 Fabric Warehouse	执行源提取、DDL 兼容性检查、审批、可选数据、安全和验证流程	dw-source-and-extraction.md，然后加载相应的 dw-* 阶段资源
独立的 Fabric Warehouse 管理	委派	sqldw-cli
Synapse Link	使用 Fabric Mirroring；此处不涉及	—

始终报告 Lake Database/HMS 阶段。如果未发现任何内容，请标记为 NotApplicable (none discovered)，同时保留所需的目标 Lakehouse 绑定。

按需加载参考资料

不要预加载所有文件。仅加载当前阶段所需的参考资料：

需求	参考资料
路由、阶段顺序、API 受众、快速示例、故障排查或迁移后交接	workload-routing.md
Dedicated Pool 执行变体和响应契约	dedicated-pool-execution-contracts.md
Dedicated Pool 发现	dedicated-pool-discovery.md
差距评估和映射审批	dedicated-pool-gap-assessment.md
过程转换和笔记本结构	dedicated-pool-conversion.md
架构/笔记本部署	dedicated-pool-deployment.md
Dedicated Pool 验证	dedicated-pool-validation.md
运行时/库兼容性	feature-parity.md 和 library-compatibility.md
mssparkutils 和连接器重构	utility-api-mapping.md、connector-refactoring.md 和 code-patterns.md
容量规划	capacity-sizing.md
Dedicated Pool 到 Warehouse 的源发现和提取	dw-source-and-extraction.md
Warehouse DDL 兼容性和部署	dw-ddl-compatibility.md
单独审批的 Warehouse 数据迁移	dw-data-migration.md
Warehouse 安全性和验证	dw-security-validation.md
验证、报告和生产就绪情况	validation-testing.md、migration-report.md 和 security-governance.md

仅在阶段资源未涵盖共享身份验证和 az rest 操作时，才使用 COMMON-CLI.md。仅使用 COMMON-CORE.md 中的共享 Fabric REST 模式。

必须

• 保留每个存储过程的输入契约、源默认值、源端决策和已批准的目标映射。
• 在明确批准差异处置方案、笔记本名称、依赖分组和目标工作区位置之前，阻止转换。
• 使用 SqlPackage/DMV 发现源端信息，使用 Fabric REST 管理项，使用 Fabric Livy 语句执行 Lakehouse 架构和 Delta 操作。
• 运行所选执行契约要求的受维护验证器；绝不能用临时 JSON 检查或单元格形状检查替代。
• 在加载实现资源之前选择 Lakehouse 或 Warehouse 目标；绝不能将 Warehouse 数据移动规则用于 Lakehouse 构件转换。
• 在持久化任何依赖管道源定义之前，递归检查其中是否包含机密或不确定属性；如果发现任何此类属性，则阻止整个所选闭包，不写入构件，也不修改目标。
• 在每条依赖管道响应中，包括仅提供指导的响应和审批前说明，都要注明："Use a TridentNotebook activity with exact target identities typeProperties.notebookId and typeProperties.workspaceId, and pass inputs through typeProperties.notebookParameters." 然后注明："After deployment, read back each pipeline with POST /v1/workspaces/{workspaceId}/items/{dataPipelineId}/getDefinition and validate its canonical hash and structural bindings."
• 对于每条 Linked Service 响应，首先说明两种替代方案：外部数据库/服务使用 Fabric Data Connections，ADLS Gen2/Blob 存储使用 OneLake Shortcuts；然后指出适用的类别。
• 将 mssparkutils 替换为 notebookutils，将 Linked Services 替换为正确的 Fabric 连接类别，并将 spark.read.synapsesql() 替换为受支持的 OneLake 或 JDBC 模式。
• 通过参数或 Variable Libraries 将工作区 ID 和项 ID 外部化。
• 保持阶段状态简洁，为长时间运行的操作发送有界心跳，并在清单中持久化每个对象的证据。

优先

• 优先使用 OneLake Shortcuts，而不是复制数据。
• 使用 Fabric Environments 实现可复现的库和 Spark 设置。
• 优先采用增量、按依赖顺序进行的迁移，而不是一次性切换。
• 使用参数化笔记本和 Variable Libraries 推广环境。
• 对兼容的 Serverless SQL Pool 读取工作负载，优先使用 Lakehouse SQL Endpoint。

避免

• 不要在构件迁移期间执行生成的笔记本或管道。
• 不要扩大所选依赖管道闭包，也不要将该内部子流转交给 pipeline-migration。
• 不要使用 sqlcmd 连接目标 Fabric Warehouse；应使用 Warehouse 资源要求的已注册 SQL Endpoint 工具。
• 不要原样保留 Synapse 分布/存储提示、PolyBase DDL、Linked Service 连接字符串或池级库安装模式。
• 不要使用目标笔记本编排迁移本身。
• 不要硬编码工作区 ID、项 ID、凭据、连接字符串或特定环境的路径。

示例

提示词：“将此 Dedicated SQL Pool DACPAC 迁移到 Fabric Lakehouse，并转换存储过程。”

**响应行为：**先评估差距，展示完整的“存储过程到笔记本”映射及工作区放置方案并征得批准，创建清单，在不移动源行的情况下转换已批准的架构和代码工件，验证已持久化的定义，并报告已解析的 Lakehouse 和工件证据。

提示词：“将此 ADF 管道迁移到 Fabric。”

**响应行为：**转交给 pipeline-migration。只有当管道是在当前进行的 Dedicated Pool 到 Lakehouse 迁移中发现的、明确获批的依赖调用方时，才在此处处理。

提示词：“将此 Dedicated SQL Pool 迁移到 Fabric Warehouse。”

**响应行为：**由 synapse-migration 处理此迁移，评估 DDL 兼容性，移除不受支持的分布和列存声明，征得资源预配许可，并就任何已还原源数据的迁移另行征求许可。

对于代码转换和边缘情况，请加载 workload-routing.md 和特定阶段的资源，而不要扩展主要说明。