hdinsight-migration

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

重要说明

1. 根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
2. 根据工作区 ID、项类型和项名称查找项详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 筛选
3. HDInsight 没有 mssparkutils 或 dbutils 的等效功能 — notebookutils 是即将推出的全新功能
4. HiveContext 和 SQLContext 是 Spark 1.x/2.x 的旧版 API — Fabric 仅使用 Spark 3.x SparkSession
5. wasb:// 路径已弃用，且需要 Storage Account 密钥或 SAS — 请改用 OneLake 快捷方式
6. Fabric 无法直接读取 hdfs://，也无法为其创建快捷方式。其 Pipeline HDFS 连接器仅支持 Anonymous 身份验证；请先将 Kerberos 源导出或桥接到受支持的存储。

HDInsight → Microsoft Fabric 迁移

前置知识

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

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

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

---

目录

主题	参考
迁移工作负载映射	§ 迁移工作负载映射
SparkSession 和 Context API 变更	§ SparkSession API 变更
WASB / ABFS → OneLake 路径迁移	path-migration.md
Hive DDL → Delta Lake / Lakehouse 架构	hive-to-delta.md
Oozie → Fabric Pipelines	§ Oozie → Fabric Pipelines
引入 notebookutils	§ 引入 notebookutils
迁移前后代码模式	code-patterns.md
Spark 配置差异	§ Spark 配置差异
必须 / 优先 / 避免	§ 必须 / 优先 / 避免
身份验证和令牌获取	COMMON-CORE.md § 身份验证
Lakehouse 管理	SPARK-AUTHORING-CORE.md § Lakehouse 管理

---

迁移工作负载映射

HDInsight 组件	Fabric 目标	备注
Spark cluster（笔记本、脚本）	Fabric Spark（Lakehouse / Notebooks / SJD）	没有持久化集群——Starter Pool 或 Custom Pool 可按需提供 Spark
Hive / HiveServer2	Lakehouse SQL Endpoint + Lakehouse schemas	Delta Lake 替代 Hive metastore；schemas 提供等效的命名空间
HBase	Fabric Warehouse 或 Azure Cosmos DB（与 Fabric 分开）	HBase 没有直接对应的 Fabric 服务——需评估工作负载的访问模式
Oozie workflows	Fabric Data Pipelines	将 Oozie 操作映射到 Fabric 活动；参见 § Oozie → Fabric Pipelines
YARN Resource Manager	Fabric Spark 监控（Spark UI、Monitoring Hub）	没有 YARN——Fabric 自动管理计算资源
Ambari	Fabric Monitoring Hub + Admin Portal	集群运行状况、容量和作业监控
WASB / ABFS 存储	OneLake Shortcuts → abfss://[email protected]/	参见 path-migration.md
Ranger 策略	Fabric 工作区角色 + OneLake 数据访问角色	将 Ranger 行/列筛选器映射到 Lakehouse 行级安全性
Livy REST 服务	Fabric Livy API	兼容的终结点——参见 SPARK-AUTHORING-CORE.md

---

SparkSession 和 Context API 更改

HDInsight Spark 集群通常使用旧版 Spark 1.x / 2.x API 风格。请将以下用法全部替换为统一的 SparkSession：

旧版 HDInsight 模式	Fabric Spark 3.x 替代方式
from pyspark import SparkContext; sc = SparkContext()	无需执行——sc = spark.sparkContext（已预先实例化）
from pyspark.sql import HiveContext; hc = HiveContext(sc)	无需执行——spark 会话通过 Delta schemas 支持 Hive 兼容的 SQL
from pyspark.sql import SQLContext; sqlc = SQLContext(sc)	无需执行——直接使用 spark.sql(...)
SparkSession.builder.enableHiveSupport().getOrCreate()	在 Fabric 中无需执行——spark 已预先创建并可用
sc.textFile("wasb://[email protected]/path")	spark.read.text("abfss://[email protected]/lh.Lakehouse/Files/path")
sqlContext.sql("CREATE TABLE ... STORED AS ORC")	Delta DDL 等效写法请参见 hive-to-delta.md

在 Fabric 笔记本中，spark（SparkSession）和 sc（SparkContext）已预先实例化——迁移后的笔记本顶部不要调用 SparkContext() 或 SparkSession.builder...getOrCreate()。

---

Oozie → Fabric Pipelines

将 Oozie 工作流操作映射到 Fabric Data Pipeline 活动：

Oozie 操作类型	Fabric Pipeline 活动	备注
<spark> 操作	Notebook activity 或 Spark Job Definition activity	通过笔记本单元格参数或 SJD 参数传递参数
<hive> 操作	针对 Lakehouse SQL Endpoint 的 Script activity（SQL）	将 HiveQL 转换为 Spark SQL 或 Delta SQL
<shell> 操作	Azure Function activity 或 Web activity	必须重构 Shell 脚本；Fabric Pipelines 不支持直接执行 Shell
<java> 操作	Azure Batch activity（外部）或重构为 PySpark	必须重写 Java MapReduce 作业
<sqoop> 操作	Copy Data activity（Fabric Data Factory 连接器）	Sqoop 导入/导出可映射为使用 JDBC 源/接收器的 Fabric Copy Data
<coordinator>（基于时间的计划）	Pipeline schedule trigger	在管道触发器中设置重复周期；支持类 cron 表达式
<coordinator>（由数据触发）	Storage Event trigger	OneLake 文件到达时触发

在映射管道活动后，将笔记本和 SJD 的创建工作委托给 spark-cli。

---

介绍 notebookutils

HDInsight Spark 没有内置的实用工具框架，无法提供与 mssparkutils 或 dbutils 等效的功能。迁移到 Fabric 时，请引入 notebookutils 来执行常见操作：

操作	旧版 HDInsight 方法	notebookutils 等效方法
列出文件	dbutils（不适用）/ HDFS CLI	notebookutils.fs.ls("abfss://...")
复制文件	HDFS API / shutil	notebookutils.fs.cp(src, dest)
读取机密	Azure Key Vault REST 调用	notebookutils.credentials.getSecret(keyVaultUrl, secretName)
获取笔记本上下文	不可用	notebookutils.runtime.context — 返回工作区 ID、笔记本 ID 等
运行子笔记本	不可用	notebookutils.notebook.run("notebook_name", timeout, {"param": "value"})
使用值退出笔记本	sys.exit()	notebookutils.notebook.exit("value")
挂载存储	在 spark-defaults.conf 中配置 WASB	OneLake 快捷方式（无需运行时挂载）

---

Spark 配置差异

HDInsight 概念	Fabric Spark 等效项	迁移操作
spark-defaults.conf（群集范围）	Fabric Spark 工作区设置 + Environment 项	将配置属性移至 Environment，或在笔记本中使用 %%configure
%%configure 魔法命令	%%configure 魔法命令 — 完全相同	无需更改
YARN 队列 / 资源分配	Fabric Spark 池节点大小和自动缩放设置	将队列 SLA 映射到自定义池配置
Ambari 服务配置（HDFS、YARN 调优）	不适用 — Fabric 管理基础设施	移除；专注于应用级 Spark 配置
HDInsight Spark 版本（例如 Spark 2.4）	Fabric Runtime 1.3 = Spark 3.5（最新版）	测试已弃用 API 的移除情况（例如 HiveContext、RDD 风格的 ML）
Conda 环境 / bootstrap.sh	带自定义库的 Fabric Environment 项	在 Fabric Environment 中重建 conda/pip 依赖项
hive-site.xml（元存储连接）	无需配置 — Delta Lake 在 Fabric 中就是元存储	移除元存储配置；使用 Lakehouse 架构来组织命名空间

---

必须 / 优先 / 避免

必须执行

• 将所有 wasb:// / wasbs:// 路径替换为 OneLake abfss:// 路径或 OneLake 快捷方式 — wasb:// 需要存储帐户密钥，这不是 Fabric 首选的身份验证模式
• 替换 HiveContext、SQLContext 和独立的 SparkContext() — 在 Fabric 笔记本中使用预先实例化的 spark 会话
• 将 Hive DDL（STORED AS ORC、LOCATION、TBLPROPERTIES）迁移到 Delta Lake DDL — 参见 hive-to-delta.md
• 引入 notebookutils，用于文件系统操作、机密检索和子笔记本编排；这些场景在 HDInsight 中可能使用自定义脚本或直接 API 调用
• 将 Oozie XML 工作流替换为 Fabric Data Pipelines — 参见 § Oozie → Fabric Pipelines
• 将库管理方式调整为 Fabric Environments — 移除 bootstrap.sh、conda 环境和面向生产工作负载的运行时 %pip install 模式
• 将 hdfs:// 视为仅适用于源群集的协议 — 导出或引入数据到 ADLS Gen2 或 OneLake；不要声称网关能为 Fabric 仅支持 Anonymous 的 HDFS 连接器添加 Kerberos 支持

优先采用

• 优先使用 OneLake 快捷方式，而非复制数据 — 将现有 ADLS Gen2 容器挂载为快捷方式，避免迁移期间重新引入数据
• 对从 Hive ORC/Parquet 迁移的所有表使用 Delta Lake — ACID 保证、时间旅行和架构强制执行有助于提高数据质量
• 使用 Fabric Starter Pool 进行初始迁移验证 — 无需承担池配置开销，且会话启动速度快
• 使用 Lakehouse 架构（数据库命名空间）来组织迁移后的 Hive 数据库 — 在单个 Lakehouse 中为每个 Hive 数据库创建一个架构
• 在迁移期间采用 Medallion 架构来重构迁移后的数据层 — 让 Bronze/Silver/Gold 分层与 Hive 原始数据 → 已验证的 Delta 数据 → Gold 服务数据模式相对应

避免

• 不要在 Fabric 笔记本中使用 SparkContext() 或 HiveContext() 构造函数——它们与预实例化的 spark 会话冲突，并会导致错误
• 不要使用 hive-site.xml 或外部 Hive 元存储配置——Fabric 基于 Delta Lake 的 Lakehouse 本身就是元存储
• 不要假设 YARN 队列映射可以直接对应到 Fabric 池——请根据 Fabric Spark 池的 SLA 重新设计资源分配
• 不要尝试在 Fabric 中直接运行 Oozie Shell 操作或 Java MapReduce 作业——必须对其进行重构（参见 § Oozie → Fabric Pipelines）
• 不要在生产笔记本中使用 %sh 魔法命令执行文件系统操作——请使用 notebookutils.fs.*，以确保可移植性并使用基于 OneLake 令牌的身份验证

---

示例

完整的迁移前后示例请参见 code-patterns.md。以下是关键速查内容：

旧版上下文 → Fabric 预实例化会话

# HDInsight (remove entirely)
from pyspark.sql import HiveContext
hc = HiveContext(sc)

# Fabric — use pre-instantiated spark directly
df = spark.sql("SELECT * FROM sales.fact_orders")

WASB 路径 → OneLake 路径（创建快捷方式后）

# HDInsight
df = spark.read.parquet("wasb://[email protected]/orders/")

# Fabric
df = spark.read.parquet("Files/raw/orders/")

Hive DDL → Delta DDL

-- HDInsight
CREATE TABLE sales_db.fact_orders (...) STORED AS ORC LOCATION 'wasb://...';

-- Fabric
CREATE SCHEMA IF NOT EXISTS sales_db;
CREATE TABLE sales_db.fact_orders (...) USING DELTA;