databricks-migration

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

重要说明

1. 根据工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 根据工作区 ID、项类型和项名称查找项详情（包括其 ID）：列出该工作区中此类型的所有项，然后使用 JMESPath 进行筛选
3. Fabric 中没有 dbutils.widgets 的直接等效项——请使用笔记本参数（单元格标记 parameters）；notebookutils.runtime.context 是执行元数据，而非参数存储。如果展示上下文字段，请使用已记录的名称，例如 currentWorkspaceId、currentWorkspaceName、currentNotebookId、currentNotebookName、isForPipeline 和 isForInteractive；activityId 是 Livy 作业 ID
4. dbutils.library（运行时库安装）没有等效项——请使用 Fabric Environments 进行可复现的库管理
5. 默认将每个 Unity Catalog catalog 映射到启用了架构的 Lakehouse。这样可以保留源端的 schema.table 层级，并由 Lakehouse 表示 catalog；只有在有意将多个 catalog 合并到一个 Lakehouse 时才会发生冲突
6. 对于需求说明不充分的工作区级迁移，在建议 Fabric 拓扑之前，先就资产清单、工作负载拓扑、安全性、数据位置和运行时约束提出有针对性的问题
7. 已完成的 Fabric 迁移不得在双运行时分支或 try/except 保护中保留可执行的 dbutils.* 调用——应彻底替换这些调用和 Databricks 路径

Databricks → Microsoft Fabric 迁移

前置知识

执行迁移任务前，请阅读以下配套文档：

• COMMON-CORE.md — Fabric REST API 模式、身份验证、令牌受众、项发现
• COMMON-CLI.md — az rest、az login、令牌获取，以及通过 CLI 使用 Fabric REST
• SPARK-AUTHORING-CORE.md — 笔记本部署、Lakehouse 创建、Spark 作业执行

有关笔记本和 Lakehouse 的创建，请参阅 spark-cli。 有关 Fabric Warehouse DDL/DML 编写，请参阅 sqldw-cli。

---

目录

主题	参考
迁移编排器	migration-orchestrator.md
迁移工作负载映射	§ 迁移工作负载映射
完整的 dbutils → notebookutils 映射	dbutils-to-notebookutils.md
Unity Catalog → Fabric Lakehouse 架构	catalog-migration.md
迁移前后代码模式	code-patterns.md
集群配置 → Fabric Spark 池	§ 集群配置 → Fabric Spark 池
Databricks 作业 → Spark 作业定义	§ Databricks 作业 → Spark 作业定义
Delta Sharing → Fabric 外部数据共享和 OneLake 快捷方式	§ Delta Sharing → Fabric 外部数据共享和 OneLake 快捷方式
MLflow → Fabric ML 实验	§ MLflow → Fabric ML 实验
迁移后验证和测试	validation-testing.md
迁移注意事项和故障排除	migration-gotchas.md
多笔记本迁移协议	§ 多笔记本迁移协议
故障报告	§ 故障报告
必须 / 优先 / 避免	§ 必须 / 优先 / 避免
身份验证和令牌获取	COMMON-CORE.md § 身份验证
Lakehouse 管理	SPARK-AUTHORING-CORE.md § Lakehouse 管理
笔记本管理	SPARK-AUTHORING-CORE.md § 笔记本管理

上下文加载指南

IMPORTANT — 仅加载所需内容。 不要预先读取所有资源文件。请加载当前执行阶段所需的特定文件：

适用情况	读取此文件
用户要求迁移工作区（完整编排）	migration-orchestrator.md
应用代码转换（dbutils、命名空间、路径）	dbutils-to-notebookutils.md + code-patterns.md
解决 Unity Catalog 命名空间冲突	catalog-migration.md
迁移后验证	validation-testing.md
排查故障或已知问题	migration-gotchas.md

---

迁移工作负载映射

Databricks 组件	Fabric 目标	严重程度	说明
通用型群集（笔记本、REPL）	Fabric Notebook（Starter Pool 或 Custom Pool）	信息	没有持久化群集——Fabric 会在会话开始时预配计算资源
作业群集（自动化作业）	Spark Job Definition (SJD)	信息	SJD 与作业群集上的 Databricks Jobs 一一对应
Unity Catalog	Fabric Lakehouse（启用架构，每个目录一个）	信息	启用架构的 Lakehouse 可保留 schema.table；默认每个目录一个 Lakehouse 的方式不会产生冲突——参见 catalog-migration.md
Databricks Repos（由 Git 支持的笔记本）	Fabric Git Integration	信息	将工作区连接到 Azure DevOps 或 GitHub；笔记本会同步
Delta Live Tables (DLT)	Fabric Notebooks + Data Pipelines	阻碍	没有 DLT 的等效功能——将 DLT 数据集重写为带参数的笔记本单元格，并使用管道进行编排
Databricks SQL Warehouses	Fabric Warehouse 或 Lakehouse SQL Endpoint	信息	SQL 仓库会话 → Warehouse（用于写入）或 SQL Endpoint（只读）
MLflow Tracking	Fabric ML Experiments	信息	Fabric 支持 MLflow SDK——参见 § MLflow
Delta Sharing	OneLake Shortcuts + Fabric external data sharing	警告	参见 § Delta Sharing → Fabric External Data Sharing and OneLake Shortcuts
Databricks Feature Store	Lakehouse/Delta 表上的特征工程 + MLflow	警告	Fabric 没有可直接替代的托管 Feature Store；请在 Lakehouse 中将特征表重新创建为 Delta 表，并通过笔记本/MLflow 管理特征。在确定方案前，请核实 Fabric 当前的特征存储路线图
dbutils（所有子模块）	notebookutils（大多数子模块）	信息	完整映射请参见 dbutils-to-notebookutils.md
Scala 笔记本	Fabric Notebook（Spark/Scala）	警告	支持 Scala；将单元格魔法 %scala 替换为 %%spark，并重写 Databricks 专属 API/库
R 笔记本	Fabric Notebook（SparkR）	警告	支持 SparkR；将单元格魔法 %r 替换为 %%sparkr，验证软件包是否可用，并重写 Databricks 专属 API

严重程度定义

级别	含义	操作
阻碍	未经重新设计或用户决策，无法在 Fabric 中运行	停止——告知用户并要求解决
警告	可以迁移，但需要验证或进行架构决策	迁移时添加审核标记
信息	直接替换级别的变更	自动迁移

---

dbutils → notebookutils 快速参考

完整的 API 并排对照表请参阅 dbutils-to-notebookutils.md。主要映射如下：

dbutils 调用	notebookutils 对应项	兼容性说明
dbutils.fs.ls(path)	notebookutils.fs.ls(path)	可直接替换
dbutils.fs.cp(src, dest)	notebookutils.fs.cp(src, dest)	可直接替换
dbutils.fs.mv(src, dest)	notebookutils.fs.mv(src, dest, create_path, overwrite=False)	⚠️ 签名不同 — 请参阅 dbutils-to-notebookutils.md
dbutils.fs.rm(path, recurse)	notebookutils.fs.rm(path, recurse)	可直接替换
dbutils.fs.mkdirs(path)	notebookutils.fs.mkdirs(path)	可直接替换
dbutils.fs.put(path, contents)	notebookutils.fs.put(path, contents)	可直接替换
dbutils.fs.head(path, maxBytes)	notebookutils.fs.head(path, max_bytes)	⚠️ 默认值不同 — Python/Scala 为 100 KB，R 为 64 KB。请参阅 dbutils-to-notebookutils.md
dbutils.fs.mount(...)	notebookutils.fs.mount(source, mountPoint, extraConfigs=None)	✅ 支持 — 支持 Microsoft Entra（默认）、accountKey 或 sasToken 身份验证。对于跨工作区/持久共享，建议使用 OneLake Shortcuts
dbutils.secrets.get(scope, key)	notebookutils.credentials.getSecret(keyVaultUrl, secretName)	scope → Key Vault URL；key → 密钥名称
dbutils.notebook.run(path, timeout, args)	notebookutils.notebook.run(name, timeout, args)	path → notebook name（相对于工作区）
dbutils.notebook.exit(value)	notebookutils.notebook.exit(value)	可直接替换
dbutils.widgets.get(name)	请参阅 § Widgets Migration	没有直接对应项
dbutils.library.install(...)	运行时不可用 — 请使用 Fabric Environments	dbutils.library.restartPython() → notebookutils.session.restartPython()
dbutils.data.summarize(df)	display(df.summary())	使用 display() 或 pandas describe()

Widgets 迁移

dbutils.widgets 在 Fabric 中没有直接对应项。请改用以下模式：

用例	Fabric 模式
从父 notebook 传递参数	将子 notebook 中的一个单元格标记为参数单元格（notebook UI：单元格“...”菜单 →“Mark cell as parameters”）。父 notebook 调用 notebookutils.notebook.run("child", arguments={"param": "value"}) — 运行时，引擎会在参数单元格下方插入一个新单元格，以覆盖默认值
由 Pipeline 驱动的参数化	使用相同的参数单元格机制；Fabric Pipeline notebook 活动通过其 Base parameters 设置提供覆盖值
集中管理跨 notebook 配置	使用 notebookutils.variableLibrary.getLibrary("<name>") 从 Variable Library 项读取值（部署 Pipeline 会按阶段激活相应的值集）
在 notebook 中进行交互式选择	使用带输入单元格的 display()、IPython widgets（仅限 Python）或 Fabric Data Activator

注意：notebookutils.runtime.context 不会公开参数值。它用于执行元数据（工作区/notebook/活动/用户 ID、Pipeline 与交互式执行标记等）。请参阅 dbutils-to-notebookutils.md § Runtime Context。

集群配置 → Fabric Spark 池

Databricks 集群概念	Fabric Spark 对应项	说明
通用集群（交互式）	Starter Pool	自动预配；无需配置；适用于笔记本
作业集群（作业专用，一次性使用）	附加到 SJD 的 Custom Pool（或 Starter Pool）	在 Fabric 容量设置中配置节点大小和自动缩放
节点类型（例如 Standard_DS3_v2）	Fabric 节点大小（Small/Medium/Large/X-Large/XX-Large）	按 vCore/内存比例进行映射
自动缩放的工作节点最小值/最大值	Custom Pool 的最小/最大节点设置	可在工作区 Spark 设置中配置
集群设置中的 spark.conf	Fabric Environment Spark 属性	移至 Environment 项；附加到工作区或笔记本
init_scripts（集群初始化）	Fabric Environment 安装脚本	并非完全等同——仅支持安装库
Databricks Runtime 版本	Fabric Runtime（1.1 = Spark 3.3，1.2 = Spark 3.4，1.3 = Spark 3.5）	选择匹配的 Spark 版本；测试已弃用的 API
Photon 加速器	Fabric Native Execution Engine (NEE)	在工作区 Spark 设置中启用；向量化执行方式类似 Photon

---

Databricks Jobs → Spark 作业定义

Databricks Jobs 概念	Fabric SJD 对应项	说明
包含单个笔记本任务的作业	引用笔记本的 SJD	附加默认 Lakehouse；通过 SJD 参数传递参数
多任务作业（任务 DAG）	编排多个 SJD/笔记本的 Fabric Data Pipeline	Pipeline 活动对应作业任务；依赖关系 = 活动依赖关系
作业计划（cron）	Pipeline 计划触发器	Cron 表达式 → Pipeline 中的循环触发器
作业参数	SJD 默认参数或笔记本单元格参数	笔记本中的参数单元格会在运行时注入
每个任务的作业集群	附加到 SJD 的池	每个 SJD 都可以独立指定其 Spark 池
Databricks Workflows	Fabric Data Pipelines	支持条件、循环和失败分支的完整 DAG 编排

SJD 创建和笔记本部署请委托给 spark-cli。

---

Delta Sharing → Fabric 外部数据共享和 OneLake 快捷方式

Databricks Delta Sharing 模式	Fabric 对应项
提供方发布 Delta 共享	使用 Fabric 外部数据共享跨租户共享 Fabric 数据，或创建指向 Delta 数据所在位置 ADLS Gen2 的 OneLake 快捷方式
接收方读取共享数据	将外部数据共享接受到 Lakehouse（Fabric 会创建只读 OneLake 快捷方式），或创建指向可访问 ADLS Gen2 数据的直接 OneLake 快捷方式
组织内跨工作区共享表	指向另一工作区 Lakehouse 表的 OneLake 快捷方式——无需复制数据
跨租户共享	Fabric 外部数据共享——接收方租户通过快捷方式实时、只读地就地访问

生成迁移工作负载映射时，请包含两种路径：用于访问 ADLS 或同一租户 OneLake 数据的直接 OneLake 快捷方式，以及用于原生跨租户接收方共享的 Fabric 外部数据共享。

---

MLflow → Fabric ML Experiments

Fabric ML Experiments 基于 MLflow SDK 构建，大多数代码都可以直接移植：

Databricks MLflow 模式	Fabric 对应项	迁移操作
mlflow.set_tracking_uri("databricks")	移除 — Fabric 会自动进行跟踪	在 Fabric 笔记本中删除此行
mlflow.set_experiment("/path/exp")	mlflow.set_experiment("experiment_name")	仅使用名称（不要使用路径）；Fabric 会创建 Experiment 项
mlflow.log_metric(...)	mlflow.log_metric(...) — 完全相同	无需更改
mlflow.log_artifact(...)	mlflow.log_artifact(...) — 完全相同	无需更改
mlflow.autolog()	mlflow.autolog() — 完全相同	无需更改
mlflow.register_model(...)	mlflow.register_model(...) — 完全相同	Fabric ML 提供 Model Registry
Databricks Model Serving	Azure ML Online Endpoints 或 Fabric Data Activator	Fabric 目前尚无直接的模型服务功能 — 请使用 Azure ML

---

必须 / 优先 / 避免

必须执行

• 在制定工作区拓扑方案前先盘点情况 — 对于未提供工作负载清单、依赖项、安全要求、数据位置或运行时限制的工作区范围请求，先提出有针对性的澄清问题，并给出有条件的选项，再选择 Fabric 设计方案
• 根据 dbutils-to-notebookutils.md 中的映射替换所有 dbutils.* 调用 — Fabric 笔记本中无法使用 dbutils
• 将 dbutils.fs.mount() 迁移为 notebookutils.fs.mount()（✅ 支持 — 默认使用 Microsoft Entra，也可使用来自 Key Vault 的 accountKey / sasToken）。对于跨工作区或持久共享，优先使用 OneLake Shortcuts。务必在 try/finally 中将 mount() 与 unmount() 配对使用 — Fabric 挂载不会在会话结束时自动释放
• 将 dbutils.secrets.get(scope, key) 替换为 notebookutils.credentials.getSecret(keyVaultUrl, secretName) — 密钥范围映射到 Azure Key Vault URL
• 使用笔记本的 parameters cells 重新设计基于小组件的参数传递（单元格“...”菜单 →“Mark cell as parameters”）；使用 notebookutils.variableLibrary 集中管理跨笔记本配置。notebookutils.runtime.context 不会公开参数值
• 将 dbutils.library.install*() 替换为 Fabric Environments — 生产环境不支持运行时安装库。dbutils.library.restartPython() 对应 notebookutils.session.restartPython()（仅适用于 Python / PySpark）
• 有意映射 Unity Catalog 命名空间 — 默认每个 catalog 使用一个启用了 schema 的 Lakehouse，以保留 schema.table；只有在将多个 catalog 整合到一个 Lakehouse 时，才需要用户批准命名策略。请参阅 catalog-migration.md
• 将 Databricks 集群 init 脚本映射到 Fabric Environments — 集群级库安装必须迁移到 Environment 项

优先考虑

• 将 Fabric Native Execution Engine (NEE) 作为 Photon 的对应方案 — 在工作区 Spark 设置中启用，以便在 Delta Lake 上进行向量化执行
• 对于已存在于 ADLS Gen2 中的 Delta 表，优先使用 OneLake Shortcuts，而非复制数据 — 直接指向数据，无需重新载入
• 使用 Fabric Git Integration 替代 Databricks Repos — 将工作区连接到 ADO 或 GitHub，以便对笔记本进行版本控制
• 使用 Fabric ML Experiments 延续 MLflow 工作流 — 跟踪代码只需少量更改（移除 set_tracking_uri）
• 重构迁移的 Databricks catalog 时优先采用 Medallion architecture — 将 Unity Catalog 的 bronze、silver、gold schema 对应到不同的 Fabric Lakehouse
• 迁移交互式笔记本工作流时优先使用 Starter Pool — 无需等待集群启动，避免 Databricks 作业集群中常见的痛点

避免

• 在缺少源清单和迁移约束时，不要规定一刀切的工作区拓扑
• 不要在 Fabric 笔记本中导入 dbutils 或尝试执行 dbutils = ... 赋值——导入尝试会失败并报 ModuleNotFoundError，而未解析的 dbutils 引用会引发 NameError；始终使用 notebookutils
• 不要在运行时检测保护条件（try/except、if IS_DATABRICKS）后保留 dbutils.* 调用——应直接将这些调用和 Databricks 路径替换为 notebookutils 和 Fabric 路径
• 不要假设 Unity Catalog 治理策略会自动迁移——必须在 Fabric 中使用工作区角色和 Lakehouse 权限重新配置 RBAC、行级安全和列屏蔽
• 不要在生产 Fabric 笔记本中于运行时使用 %pip install——应使用 Fabric Environments 稳定、按版本管理库
• 不要尝试原样移植 Delta Live Tables（DLT）管道——Fabric 没有 DLT 的对应功能；应改写为由 Fabric Pipelines 编排的参数化笔记本
• 不要依赖 Databricks 专属的 Spark 配置（例如 spark.databricks.*）——这些配置是专有的，在 Fabric 中会被静默忽略或引发错误
• 不要使用 DBFS 路径（dbfs:/...）——Fabric 中没有 DBFS；所有路径都必须使用 OneLake abfss:// 路径或相对于 Lakehouse 的路径

---

多笔记本迁移协议

对于包含 >3 个笔记本的工作区，或大小 >5KB 的单个笔记本，应一次处理一个笔记本（枚举 → 导出 → 转换 → 汇总 → 部署 → 发布），以避免上下文溢出。跟踪每个笔记本的状态生命周期（inventory → analyzed → converted → deployed → validated，或 failed）。

完整协议、状态定义和逐笔记本摘要架构：migration-orchestrator.md § Phase 2。

---

失败报告

当迁移无法完成时（权限失败、无法解决的阻塞项，例如 DLT 或操作系统级初始化脚本、没有用户选定策略的命名空间冲突，或重复的 API 失败），应生成结构化失败报告，不要悄无声息地放弃。报告应记录 phase_reached、blockers[]（item / pattern / reason / recommendation）、partial_success 计数和 next_steps。

完整的报告架构和停止条件：migration-orchestrator.md § Failure Reporting。

---

示例

完整映射请参阅 dbutils-to-notebookutils.md 和 code-patterns.md。以下是关键速查项：

dbutils.fs → notebookutils.fs

# Databricks
dbutils.fs.ls("/mnt/bronze/orders/")
dbutils.fs.cp("/mnt/raw/file.csv", "/mnt/archive/file.csv")

# Fabric (replace DBFS/mount paths with OneLake relative paths)
notebookutils.fs.ls("Files/bronze/orders/")
notebookutils.fs.cp("Files/raw/file.csv", "Files/archive/file.csv")

dbutils.secrets → notebookutils.credentials

# Databricks
pwd = dbutils.secrets.get(scope="prod", key="db-password")

# Fabric (scope → Key Vault URL, key → secret name)
pwd = notebookutils.credentials.getSecret("https://myvault.vault.azure.net/", "db-password")

Unity Catalog 命名空间 → Lakehouse 架构

# Databricks
df = spark.read.table("prod.silver.customers")

# Fabric (ProdLakehouse represents the source catalog and is attached as context)
df = spark.read.table("silver.customers")