pipeline-migration

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

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を調べるには、すべてのワークスペースを一覧表示してから、JMESPath でフィルタリングします
2. ワークスペース ID、項目の種類、項目名から項目の詳細（ID を含む）を調べるには、そのワークスペース内の該当する種類の項目をすべて一覧表示してから、JMESPath でフィルタリングします
3. Fabric に「Dataset」項目の種類はありません。データセットのプロパティはすべて、アクティビティの typeProperties にインライン化されます
4. リンクされたサービスは Fabric の接続に対応します。パイプラインのアクティビティ JSON では、アクティビティの linkedService ブロックにある referenceName に Fabric 接続の表示名を使用します（接続 GUID ではありません）。接続 GUID は Fabric REST API の呼び出しでのみ使用します
5. ノートブックアクティビティは SynapseNotebook から TridentNotebook に変更され、ノートブックは名前ではなくGUIDで参照します
6. Synapse のグローバルパラメーターは Fabric の変数ライブラリ項目になり、@pipeline().libraryVariables.<name> として参照します。変数ライブラリの Number 型はパイプラインで使用できません。Synapse の Float／Double は、ランタイムとの互換性を保つため String にマッピングされます
7. Validation アクティビティの種類は Fabric に存在しないため、GetMetadata と IfCondition に書き換える必要があります
8. トリガーは意図的にこのスキルの対象外です。移行後に Fabric でスケジュールを手動で再作成してください
9. SSIS パッケージの実行、SHIR 専用コネクタ、Databricks アクティビティは保留対象です。pipeline-gotchas.mdを参照してください

Synapse Pipelines → Microsoft Fabric Data Factory の移行

前提知識

以下の関連ドキュメントでは、Fabric REST の一般的なパターンを説明しています。最初にまとめて読まないでください。このスキルのリソースファイルに記載されていないパターンが特定のフェーズで必要な場合にのみ参照してください。

• COMMON-CORE.md — Fabric REST API の一般的なパターン、認証とトークンのオーディエンス、JMESPath による項目の検出
• COMMON-CLI.md — az rest／az login の CLI パターン、認証の手順、パイプラインの実行／スケジュール操作
• ITEM-DEFINITIONS-CORE.md — DataPipeline と VariableLibrary の項目定義構造（pipeline-content.json、variables.json）
• SPARK-AUTHORING-CORE.md — Fabric ノートブック項目の作成（Fabric にノートブック項目がまだ存在しない場合に必要）

移行におけるノートブック側（パイプラインアクティビティから呼び出されるノートブック）には、関連する synapse-migration スキルを使用して、ノートブックのコンテンツ自体を移行してください。

---

目次

トピック	参照
移行前の評価（最初に実施）	pipeline-assessment.md
移行オーケストレーター	pipeline-orchestrator.md
API 主導の移行ワークフロー	§ API 主導の移行ワークフロー
アクティビティの種類のマッピング	activity-mapping.md
ノートブックアクティビティの移行（主な対象）	notebook-activity-migration.md
リンクされたサービス → 接続	linked-service-to-connection.md
データセットのインライン化	dataset-inlining.md
グローバルパラメーター → 変数ライブラリ	global-parameters-to-variable-library.md
パイプラインの注意点と保留中のアクティビティ	pipeline-gotchas.md
検証とテスト	validation-testing.md
移行レポート	migration-report.md

コンテキスト読み込みガイド

重要 — 必要なものだけを読み込んでください。 すべてのリソースファイルを最初に読まないでください。

場合	このファイルを読む
ユーザーが移行前に評価、範囲、または計画を求めている	pipeline-assessment.md
ユーザーがパイプラインワークスペース全体の移行を求めている	pipeline-orchestrator.md
ユーザーがアクティビティの種類のマッピング、またはサポート対象外のアクティビティについて尋ねている	activity-mapping.md
ユーザーに SynapseNotebook アクティビティがある（最も一般的）	notebook-activity-migration.md
ユーザーがリンクされたサービスや接続について尋ねている	linked-service-to-connection.md
ユーザーがデータセットを使用する Copy、Lookup、または GetMetadata について尋ねている	dataset-inlining.md
ユーザーが変換するグローバルパラメーターを使用している	global-parameters-to-variable-library.md
ユーザーが SSIS、SHIR、Databricks、またはその他の阻害要因に直面している	pipeline-gotchas.md
移行後の検証	validation-testing.md
移行の概要を作成する	migration-report.md

---

API 駆動型の移行ワークフロー

認証

ターゲット	トークンのオーディエンス
Synapse Data Plane（パイプライン、データセット、リンクされたサービス）	https://dev.azuresynapse.net
Synapse ARM（グローバルパラメーター、ワークスペースのプロパティ）	https://management.azure.com
Fabric REST API（パイプライン、接続、Variable Library の作成）	https://api.fabric.microsoft.com

az account get-access-token --resource <audience> --query accessToken -o tsv を使用してトークンを取得します。

Synapse Data-Plane API リファレンス

操作	エンドポイント
すべてのパイプラインを一覧表示	GET https://{ws}.dev.azuresynapse.net/pipelines?api-version=2020-12-01
パイプライン定義を取得	GET https://{ws}.dev.azuresynapse.net/pipelines/{name}?api-version=2020-12-01
すべてのデータセットを一覧表示	GET https://{ws}.dev.azuresynapse.net/datasets?api-version=2020-12-01
データセット定義を取得	GET https://{ws}.dev.azuresynapse.net/datasets/{name}?api-version=2020-12-01
すべてのリンクされたサービスを一覧表示	GET https://{ws}.dev.azuresynapse.net/linkedservices?api-version=2020-12-01
リンクされたサービスを取得	GET https://{ws}.dev.azuresynapse.net/linkedservices/{name}?api-version=2020-12-01
ワークスペースを取得（グローバルパラメーター）	GET https://management.azure.com/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.Synapse/workspaces/{ws}?api-version=2021-06-01

Fabric API リファレンス

操作	エンドポイント
接続を一覧表示	GET https://api.fabric.microsoft.com/v1/connections
接続を作成	POST https://api.fabric.microsoft.com/v1/connections
パイプラインアイテムを作成	POST https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items
パイプライン定義を更新	POST https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items/{id}/updateDefinition
パイプライン定義を取得	POST https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items/{id}/getDefinition
Variable Library を作成	POST https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items（type: VariableLibrary）
ワークスペース内のノートブックを一覧表示	GET https://api.fabric.microsoft.com/v1/workspaces/{wsId}/notebooks

---

評価モード（任意ですが推奨）

Fabric で項目を作成する前に、パイプライン評価を実行して、範囲、複雑さ、阻害要因を把握してください。評価は読み取り専用です。Synapse API のみを照会し、Markdown レポートを生成します。

Copilot のワークフロー — Python スクリプトファイルは不要です：

1. ユーザーに「Synapse ワークスペースの名前は何ですか？」と尋ねます。
2. az account show と az synapse workspace show を使用して、サブスクリプション ID とリソースグループを自動検出します。
3. ターミナルから評価コードをインラインで実行します。
4. レポート全体の出力をチャットに直接表示します。

使用するタイミング	アクション
ユーザーが移行を決定する前に、移行範囲を把握したい場合	ワークスペース名を尋ねる → pipeline-assessment.md を読み込む → インラインで実行
ユーザーが「移行できるものとできないものは何ですか？」と尋ねた場合	評価を実行し、エグゼクティブサマリーのセクションを提示する
ユーザーが移行計画またはスコープ定義書を求めた場合	評価を実行し、レポートをチャットに表示する
ユーザーがすでに移行を決定している場合	評価を省略し、以下の移行フェーズに進む

レポートをディスクにも保存するには、generate_assessment_report() に output_path=f"pipeline-assessment-{SYNAPSE_WS}.md" を渡します。生成される PipelineAssessment オブジェクトは、pipeline-orchestrator.md の移行スクリプトに直接渡して利用できます。

---

移行モード（インライン — スクリプトファイルは不要）

Copilot はターミナルから直接移行を実行します。保存または手動実行する Python ファイルはありません。

ユーザーに尋ねる情報：

1. Synapse ワークスペース名（評価をすでに実行している場合は再利用）
2. Fabric ワークスペース名
3. 移行するパイプライン — 特定の名前、またはすべてを対象とする場合は *
4. Fabric 内で各パイプライン名の末尾に追加する名前の接尾辞（任意。例：_migrated） — 元の名前を維持する場合は空欄のままにします

その他の情報はすべて自動検出されます：

• az account show と az synapse workspace show を使用したサブスクリプション ID とリソースグループ
• 表示名でフィルターした GET /v1/workspaces による Fabric ワークスペース ID
• GET /v1/workspaces/{wsId}/notebooks による Fabric 内のノートブック GUID（SynapseNotebook → TridentNotebook に必要）
• GET /v1/connections による Fabric 内の接続名（データセットがリンクされたサービスを参照している場合）

インラインで完全に自動化される処理：

• ✅ SynapseNotebook → TridentNotebook — 種類の名前変更、GUID の検索、sparkPool／sessionConfiguration の削除、タイムアウトを最大 12 時間に修正
• ✅ 互換性のあるすべてのアクティビティの種類 — 軽微なプロパティ調整を加えてそのまま処理
• ✅ データセットをアクティビティの typeProperties にインライン化
• ✅ グローバルパラメーターの式を @pipeline().libraryVariables.<name> に書き換え
• ✅ パイプライン JSON の組み立てと REST による Fabric へのデプロイ

Copilot は開始前に確認し、次の場合は一時停止して報告します：

• SynapseNotebook アクティビティが参照するノートブックが、Fabric ワークスペースにまだ存在しない
• データセットを使用するアクティビティが参照するリンクされたサービスに対して、Fabric 接続が存在しない

完全なインライン実行ツールについては、pipeline-orchestrator.md を読み込んでください。

---

移行フェーズ（順番に実行）

フェーズ	移行元	移行先	リソース
フェーズ 0	パイプラインアクティビティから参照される Synapse ノートブック	Fabric ノートブック	synapse-migration スキル
フェーズ 1	Synapse グローバルパラメーター	Fabric Variable Library	global-parameters-to-variable-library.md
フェーズ 2	Synapse リンクされたサービス	Fabric 接続	linked-service-to-connection.md
フェーズ 3	Synapse データセット	アクティビティにインライン化	dataset-inlining.md
フェーズ 4	Synapse パイプラインアクティビティ	Fabric パイプラインアクティビティ	activity-mapping.md + notebook-activity-migration.md
フェーズ 5	組み立て済みのパイプライン JSON	Fabric DataPipeline アイテム	pipeline-orchestrator.md
最終	—	検証	validation-testing.md

フェーズ 0 はフェーズ 4 より先に実施する必要があります：TridentNotebook アクティビティを記述する前に Fabric ノートブックの GUID が必要です。 フェーズ 2 はフェーズ 3 より先に実施する必要があります：インライン化したデータセットで参照する前に、接続名が存在している必要があります。

---

アクティビティタイプのクイックリファレンス

マッピング表全体、移行前後の例、および保留の判断については、activity-mapping.md を参照してください。

Synapse アクティビティ	Fabric の同等機能	ステータス
SynapseNotebook	TridentNotebook	✅ 移行済み — notebook-activity-migration.md を参照
Copy	Copy	✅ 移行済み — データセットをインライン化
Lookup	Lookup	✅ 移行済み — データセットをインライン化
GetMetadata	GetMetadata	✅ 移行済み — データセットをインライン化
Validation	GetMetadata + IfCondition	✅ 移行済み — 2 つのアクティビティに分割
ForEach	ForEach	✅ 互換
IfCondition	IfCondition	✅ 互換
Switch	Switch	✅ 互換
Until	Until	✅ 互換
Wait	Wait	✅ 互換
Fail	Fail	✅ 互換
SetVariable	SetVariable	✅ 互換
AppendVariable	AppendVariable	✅ 互換
ExecutePipeline	ExecutePipeline	✅ 互換 — workspaceId を追加
WebActivity	WebActivity	✅ 互換
Script	Script	✅ 互換 — 接続参照を更新
Delete	Delete	✅ 移行済み — データセットをインライン化
Filter	Filter	✅ 互換
SparkJobDefinition（Synapse SJD）	SparkJobDefinition	✅ GUID 参照を更新
HDInsightSpark	TridentNotebook または SparkJobDefinition	⚠️ 書き換えが必要
AzureMLBatchExecution	WebActivity	⚠️ REST 呼び出しとして書き換え
AzureFunctionActivity	WebActivity	⚠️ 書き換えが必要 — 関数 URL とキーを使用
DatabricksNotebook	⛔ 保留	pipeline-gotchas.md を参照
DatabricksSparkJar	⛔ 保留	pipeline-gotchas.md を参照
DatabricksSparkPython	⛔ 保留	pipeline-gotchas.md を参照
ExecuteSSISPackage	⛔ 保留	pipeline-gotchas.md を参照
AzureBatch	⛔ 保留	Fabric に同等機能なし
Custom	⛔ 保留	Fabric に同等機能なし

---

必須／推奨／回避

必ず実施

• パイプラインより先にノートブックを移行してください — Fabric TridentNotebook アクティビティでは名前ではなくノートブック GUID が必要です。まず synapse-migration スキルを使用してください
• パイプライン JSON の作成前に Fabric 接続を作成してください — Synapse のリンクされたサービス名は Fabric では接続参照になります。データセットをインライン化する前に接続名が必要です
• すべてのデータセット定義をインライン化してください — Fabric Data Factory には Dataset アイテムタイプがありません。すべてのアクティビティで inputs／outputs のデータセットプロパティを埋め込む必要があります
• 変数ライブラリの作成後、@pipeline().globalParameters.<name> を @pipeline().libraryVariables.<name> に置き換えてください
• Validation アクティビティを GetMetadata と IfCondition の組み合わせに置き換えてください — Fabric にはアクティビティタイプとして Validation がありません
• 移行したノートブックアクティビティから sparkPool と sessionConfiguration を削除してください — プールの選択とセッション構成は、ノートブックにアタッチされた Fabric Environment で設定します

推奨

• 開発／テスト／本番環境には、値セットを含む変数ライブラリを使用してください — 環境の昇格には、パイプラインレベルのパラメーターの代わりに、環境固有の値セットを使って @pipeline().libraryVariables.<name> を使用します
• TridentNotebook アクティビティでは、ハードコードされた値よりパラメーター化された notebookParameters を使用してください — Synapse のパラメーター化されたノートブックのパターンに準じます
• 移行したパイプライン全体を実行する前に、ノートブックアクティビティを個別にテストしてください — ノートブック GUID は最もよくある失敗の原因です
• 該当する場合は、Copy アクティビティのソース／シンクに OneLake Lakehouse を使用してください — OneLake 内のデータに外部接続が不要になります

避けるべきこと

• TridentNotebook アクティビティでノートブックを名前で参照しないでください — Fabric ワークスペースのノートブック一覧にある GUID を使用してください
• Synapse のトリガーを引き継がないでください — このスキルでは移行されません。パイプラインの検証後に Fabric でスケジュールを再作成してください
• 最初に pipeline-gotchas.md を読まずに、SSIS、Databricks、AzureBatch のアクティビティを移行しようとしないでください — これらには手動での対応が必要です
• パイプライン JSON にワークスペース／アイテムの GUID をハードコードしないでください — パイプライン JSON を編集せずに環境を昇格できるよう、変数ライブラリのエントリまたはパイプラインパラメーターを使用してください
• 移行後に @pipeline().globalParameters 構文を使用しないでください — この式パスは Fabric には存在しません。移行したすべてのグローバルパラメーターには、@pipeline().libraryVariables を介してアクセスする必要があります

---

移行時の注意点 — クイックリファレンス

トラブルシューティングの詳細は、pipeline-gotchas.md をご覧ください。

#	フラグ ID	問題	重大度	解決方法の概要
PG1	NOTEBOOK_GUID_NOT_FOUND	TridentNotebook アクティビティの作成時に、ノートブックが Fabric にまだ移行されていません	高	まず synapse-migration スキルを実行し、GET /v1/workspaces/{wsId}/notebooks から GUID を取得します
PG2	DATASET_NOT_INLINED	アクティビティが名前付きデータセットを参照したままです（Fabric では無効です）	高	dataset-inlining.md のパターンを適用し、データセットのプロパティをアクティビティのソース／シンクに埋め込みます
PG3	GLOBAL_PARAM_EXPRESSION	移行後のパイプラインに @pipeline().globalParameters.<name> 式が残っています	高	Variable Library の作成後、@pipeline().libraryVariables.<name> に置き換えます
PG4	VALIDATION_ACTIVITY_UNSUPPORTED	パイプライン JSON に Validation アクティビティの種類が残っています	高	GetMetadata + IfCondition に書き換えます — activity-mapping.md をご覧ください
PG5	SHIR_CONNECTOR_PARKED	アクティビティがセルフホスト統合ランタイムを使用するリンクされたサービスを使っています	中	Fabric でオンプレミスデータゲートウェイを設定する必要があります。pipeline-gotchas.md をご覧ください
PG6	SSIS_ACTIVITY_PARKED	ExecuteSSISPackage アクティビティは移行できません	高	保留 — Fabric に相当する機能はありません。代替案については pipeline-gotchas.md をご覧ください
PG7	DATABRICKS_ACTIVITY_PARKED	Databricks アクティビティの種類に Fabric ネイティブの相当機能がありません	高	保留 — 回避策として WebActivity 経由で Databricks REST API を使用します。pipeline-gotchas.md をご覧ください
PG8	SPARKPOOL_REF_ORPHANED	TridentNotebook アクティビティに sparkPool／targetBigDataPool の参照が残っています	中	sparkPool と sessionConfiguration ブロックを削除します。プールの設定は Fabric Environment に属します
PG9	EXECUTE_PIPELINE_NO_WORKSPACE	ExecutePipeline アクティビティで、参照先のパイプラインの workspaceId が指定されていません	中	typeProperties に workspaceId を追加します。同じワークスペース内の子パイプラインでも必須です。省略すると実行時に失敗します
PG10	LINKED_SERVICE_NO_CONNECTION	リンクされたサービスに対応する Fabric Connection がありません	高	手動または API 経由で接続を作成し、埋め込み済みデータセットの接続参照を更新します

---

移行後：次のステップ

パイプラインの移行後は、以下の関連スキルやツールに引き継ぎます。

タスク	スキル／ツール
ノートブックの内容を移行する（mssparkutils → notebookutils、リンクされたサービス）	synapse-migration スキル
移行したパイプラインをスケジュールする	COMMON-CLI.md § ジョブのスケジュール設定
パイプラインの実行を監視する	Fabric ワークスペース → Monitor ハブ
新しい Fabric パイプラインを構築する	ITEM-DEFINITIONS-CORE.md § DataPipeline をご覧ください
パイプラインの実行後に、移行した Lakehouse データを調べる	spark-cli または sqldw-cli スキル

---

例

SynapseNotebook → TridentNotebook アクティビティ（移行前／移行後）

{
  "name": "Run_Notebook",
  "type": "SynapseNotebook",
  "typeProperties": {
    "notebook": {"referenceName": "MyNotebook", "type": "NotebookReference"},
    "sparkPool": {"referenceName": "BigPool", "type": "BigDataPoolReference"}
  }
}

移行後（GET /v1/workspaces/{wsId}/notebooks から取得した GUID）：

{
  "name": "Run_Notebook",
  "type": "TridentNotebook",
  "typeProperties": {
    "notebookId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "workspaceId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
  }
}

グローバルパラメーター式の書き換え

Before (Synapse):  @pipeline().globalParameters.batchDate
After (Fabric):    @pipeline().libraryVariables.batchDate

データセットのインライン化：Copy アクティビティ — データセット参照 → 接続の表示名

Synapse データセット InputBlobDataset（インライン化後に削除されます）：

{
  "type": "AzureBlob",
  "linkedServiceName": {"referenceName": "AzureBlobLinkedService"},
  "typeProperties": {"folderPath": "input/", "fileName": "data.csv"}
}

Synapse Copy アクティビティ（移行前 — データセットを名前で参照）：

{
  "name": "CopyData", "type": "Copy",
  "inputs": [{"referenceName": "InputBlobDataset", "type": "DatasetReference"}],
  "typeProperties": {"source": {"type": "BlobSource"}, "sink": {"type": "BlobSink"}}
}

移行後（AzureBlobLinkedService の接続の表示名は My ADLS Connection）：

{
  "name": "CopyData", "type": "Copy",
  "typeProperties": {
    "source": {"type": "BlobSource", "storeSettings": {"type": "AzureBlobStorageReadSettings"}},
    "sink":   {"type": "BlobSink",   "storeSettings": {"type": "AzureBlobStorageWriteSettings"}}
  },
  "linkedService": {"referenceName": "My ADLS Connection", "type": "LinkedServiceReference"}
}

移行前／移行後の詳しい例については、activity-mapping.md と notebook-activity-migration.md をご覧ください。