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:// パスは非推奨で、ストレージアカウントキーまたは 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 — ノートブックのデプロイ、レイクハウスの作成、Spark ジョブの実行

ノートブックとレイクハウスの作成については、spark-cli を参照してください。 Fabric Warehouse の DDL/DML 作成については、sqldw-cli を参照してください。

---

目次

トピック	参照
移行対象ワークロードの対応表	§ 移行対象ワークロードの対応表
SparkSession とコンテキスト API の変更	§ SparkSession API Changes
WASB / ABFS → OneLake パスの移行	path-migration.md
Hive DDL → Delta Lake / レイクハウスのスキーマ	hive-to-delta.md
Oozie → Fabric パイプライン	§ Oozie → Fabric Pipelines
notebookutils の導入	§ notebookutils の導入
移行前後のコードパターン	code-patterns.md
Spark の構成の違い	§ Spark Configuration Differences
必須／推奨／回避	§ Must / Prefer / Avoid
認証とトークンの取得	COMMON-CORE.md § Authentication
レイクハウスの管理	SPARK-AUTHORING-CORE.md § Lakehouse Management

---

移行ワークロードマップ

HDInsight コンポーネント	Fabric の移行先	備考
Spark クラスター（ノートブック、スクリプト）	Fabric Spark（Lakehouse／Notebooks／SJD）	永続クラスターはありません。Starter Pool または Custom Pool がオンデマンドで Spark を提供します
Hive／HiveServer2	Lakehouse SQL Endpoint + Lakehouse スキーマ	Delta Lake が Hive metastore を置き換え、スキーマが同等の名前空間を提供します
HBase	Fabric Warehouse または Azure Cosmos DB（Fabric とは別）	HBase に Fabric の直接的な同等機能はありません。ワークロードのアクセスパターンを評価してください
Oozie ワークフロー	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 スキーマを介して 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	シェルスクリプトはリファクタリングが必要です。Fabric Pipelines ではシェルを直接実行できません
<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 構成に注力します
HDI Spark バージョン（例：Spark 2.4）	Fabric Runtime 1.3 = Spark 3.5（最新）	非推奨 API の削除に備えてテストします（例：HiveContext、RDD スタイルの ML）
Conda 環境／bootstrap.sh	カスタムライブラリを含む Fabric Environment アイテム	Conda／pip の依存関係を Fabric Environment に再作成します
hive-site.xml（メタストア接続）	不要 — Fabric では Delta Lake がメタストアです	メタストアの構成を削除し、名前空間の整理には 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 を参照してください
• HDInsight でカスタムスクリプトや API の直接呼び出しを使用していた箇所では、ファイルシステム操作、シークレットの取得、子ノートブックのオーケストレーションに notebookutils を導入します
• Oozie XML ワークフローを Fabric Data Pipelines に置き換えます — § Oozie → Fabric Pipelines を参照してください
• ライブラリ管理を Fabric Environments に合わせます — 本番ワークロードでは、bootstrap.sh、Conda 環境、ランタイムの %pip install パターンを削除します
• hdfs:// はソースクラスター専用として扱います — ADLS Gen2 または OneLake にエクスポートするか取り込みます。ゲートウェイによって Fabric の匿名認証専用 HDFS コネクタに Kerberos サポートが追加されると主張してはいけません

推奨

• データのコピーより OneLake ショートカットを優先します — 移行時の再取り込みを避けるため、既存の ADLS Gen2 コンテナーをショートカットとしてマウントします
• Hive ORC／Parquet から移行するすべてのテーブルに Delta Lake を使用します — ACID 保証、タイムトラベル、スキーマの適用により、データ品質が向上します
• 初期の移行検証には Fabric Starter Pool を使用します — プール構成のオーバーヘッドがなく、セッションをすばやく開始できます
• 移行した Hive データベースの整理には、データベース名前空間となる Lakehouse スキーマを使用します — 1 つの Lakehouse 内で Hive データベースごとに 1 つのスキーマを作成します
• 移行中に移行データ層を再構成するには メダリオンアーキテクチャを使用します — Bronze／Silver／Gold を、Hive の生データ → 検証済み Delta → 提供用 Gold のパターンに合わせます

避けるべきこと

• Fabric のノートブックでは、SparkContext() または HiveContext() コンストラクターを使用しないでください。事前にインスタンス化された spark セッションと競合し、エラーが発生します。
• hive-site.xml や外部の Hive メタストア設定を使用しないでください。Fabric の Delta Lake ベースの Lakehouse がメタストアそのものです。
• YARN のキューマッピングが Fabric のプールにそのまま適用できると想定しないでください。Fabric Spark プールの SLA に基づいて、リソース割り当てを再設計してください。
• Oozie のシェルアクションや Java MapReduce ジョブを Fabric で直接実行しようとしないでください。これらはリファクタリングが必要です（§ Oozie → Fabric パイプラインを参照）。
• 本番環境のノートブックでは、ファイルシステム操作に %sh マジックを使用しないでください。移植性と OneLake のトークンベース認証のために、notebookutils.fs.* を使用してください。

---

例

変更前と変更後の例については、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;