synapse-migration

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: synapse-migration（az rest の場合は --headers "x-ms-fabric-skill=synapse-migration"）を付与する必要があります。 fabric_lro やリトライを含む、すべての LRO ポーリングにも付与してください。スニペットでは省略されていますが、必ず追加してください。

オフラインのレイクハウス成果物の高速パス — 最初に判断してください。 必要な入力とコントラクトがすべて提供されているライブ呼び出しなしのリクエストでは、高速パスのみを読み込み、migration-planning-reference.md、dedicated-pool-conversion.md、実装スクリプトは読み込まないでください。成果物と最終バイトのハッシュにはジェネレーターを1つ使用し、その後に検証ツールを1つ使用してください。生成ファイルを調べたり、後処理のスポットチェックを実行したりしないでください。オプションの null 以外のソース既定値には、すべて 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 のマッピングは、ビューには適用されません。ビューはスキーマオブジェクトのままにし、プロシージャは実行可能な %%sql 変換セルを含む、追跡可能な Spark SQL ノートブックにしてください。
7. 依存する ADF/Synapse 呼び出し元は条件付きの対象範囲であり、自動的に対象となるわけではありません。評価時に特定し、別途完全な依存関係範囲の承認を得て、ノートブックの準備完了後にのみ移行してください。パイプライン単体のリクエストは pipeline-migration にルーティングしてください。
8. 専用の Dedicated Pool ワークフローを実行する前に、dedicated-pool-execution-contracts.md にある対応するコントラクトを読んでください。そこに記載された検証、ハッシュ化、リクエスト本文、再開、完了時の表現に関する要件は必須です。
9. Lakehouse と Warehouse のパスは分けてください。ターゲットが不明な場合は、パス固有のリソースを読み込む前に確認してください。Lakehouse 変換ではソースの行を移動しません。Warehouse データ移行には、独自の明示的な同意ゲートと復元済みソースのコントラクトが必要です。
10. Fabric Warehouse をターゲットとする場合、Fabric が分散、ストレージ、インデックスを管理するため、DISTRIBUTION と CLUSTERED COLUMNSTORE INDEX の宣言全体を削除することを明示してください。ソース句のいずれかに軽く言及するだけでは不十分です。
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
大規模または複雑なストアドプロシージャ	完全なオフライン契約を作成するには、監査リソースだけを一度読み込み、実行ごとに生成ツールを1つ、検証ツールを1つ使用します。実装スクリプトや生成された出力は調査せず、検証が成功したら終了します	dedicated-pool-large-procedure-audit.md
Spark pool	構成とライブラリを 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 のフェーズは必ず報告してください。何も検出されなかった場合は、必要な対象 Lakehouse のバインドを維持したまま、NotApplicable (none discovered) と記載してください。

必要に応じてリファレンスを読み込む

すべてのファイルを事前に読み込まないでください。現在のフェーズで必要なリファレンスのみを読み込んでください。

必要な内容	リファレンス
ルーティング、フェーズの順序、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 を使用してください。共通の Fabric REST パターンについてのみ、COMMON-CORE.md を使用してください。

必須

• 保存済みストアドプロシージャのすべての入力コントラクト、ソースのデフォルト値、ソース側の判断、および承認済みのターゲットマッピングを維持します。
• ギャップの対応方針、ノートブック名、依存関係のグループ分け、およびターゲットワークスペースへの配置が明示的に承認されるまで、変換をブロックします。
• ソースの検出には SqlPackage／DMV、項目の管理には Fabric REST、Lakehouse スキーマおよび Delta の実行には Fabric Livy ステートメントを使用します。
• 選択した実行コントラクトで必須となる保守対象のバリデーターを実行します。場当たり的な JSON チェックやセル形状チェックで置き換えてはいけません。
• 実装リソースを読み込む前に、Lakehouse または Warehouse のターゲットを選択します。Warehouse のデータ移動ルールを Lakehouse アーティファクトの変換に適用してはいけません。
• 依存パイプラインのソース定義を保存する前に、再帰的に検査して、シークレットを含むプロパティや不確かなプロパティがないか確認します。見つかった場合は、アーティファクトを書き込んだりターゲットを変更したりせず、選択した完全な依存範囲をブロックします。
• ガイダンスのみの場合や事前承認の説明を含め、依存パイプラインに関するすべての応答で、次のように述べます。「正確なターゲット識別子 typeProperties.notebookId および typeProperties.workspaceId を指定した TridentNotebook アクティビティを使用し、入力を typeProperties.notebookParameters 経由で渡してください。」続けて、次のように述べます。「デプロイ後、各パイプラインを POST /v1/workspaces/{workspaceId}/items/{dataPipelineId}/getDefinition で読み戻し、正規化ハッシュと構造的なバインディングを検証してください。」
• Linked Service に関するすべての応答では、まず置き換え先の両方の分類を示します。外部データベース／サービスには Fabric Data Connections、ADLS Gen2／Blob ストレージには OneLake Shortcuts を使用します。そのうえで、どちらの分類が該当するかを特定します。
• mssparkutils は notebookutils に置き換え、Linked Services は適切な Fabric 接続クラスに置き換え、spark.read.synapsesql() はサポートされている OneLake または JDBC のパターンに置き換えます。
• ワークスペース ID と項目 ID は、パラメーターまたは Variable Libraries を通じて外部化します。
• フェーズのステータスは簡潔に保ち、長時間の操作では上限付きハートビートを送信し、オブジェクトごとのエビデンスをマニフェストに永続化します。

推奨

• データのコピーより OneLake Shortcuts を優先します。
• 再現性のあるライブラリと Spark 設定には Fabric Environments を使用します。
• 一斉切り替えではなく、依存関係の順序に沿った段階的な移行を優先します。
• 環境への昇格には、パラメーター化されたノートブックと Variable Libraries を使用します。
• 互換性のある Serverless SQL Pool の読み取りワークロードには、Lakehouse SQL Endpoint を使用します。

避けること

• アーティファクトの移行の一環として、生成されたノートブックやパイプラインを実行してはいけません。
• 選択した依存パイプラインの範囲を広げたり、その内部サブフローを pipeline-migration に振り分けたりしてはいけません。
• ターゲットの Fabric Warehouse に sqlcmd を使用してはいけません。Warehouse リソースで必要となる登録済みの SQL エンドポイントツールを使用します。
• 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 とフェーズ固有のリソースを読み込みます。