チュートリアル: PowerShell を使用して Azure Data Factory パイプラインを Fabric パイプラインにアップグレードする

Microsoft.FabricPipelineUpgrade PowerShell モジュールを使用して、Azure Data Factory (ADF) パイプラインを Microsoft Fabric に移行できます。このチュートリアルでは、特定の手順、スクリーンショット、トラブルシューティング手順を使用して移行を実行するためのすべての手順の例を示します。より一般的で簡潔なガイドについては、概要を参照してください。

アップグレードの準備方法
ADF パイプラインを Fabric パイプラインにアップグレードする方法
アラートの読み取りと処理

[前提条件]

開始するには、次の前提条件があることを確認してください。

テナント: ADF ワークスペースと Fabric ワークスペースは、同じ Microsoft Entra ID テナント内にある必要があります。
ファブリック: アクティブな Fabric サブスクリプションを持つテナントアカウント - アカウントを無料で作成します。
ファブリックワークスペースの推奨事項 (省略可能): パフォーマンスを最大限に高めるには、ADF と同じリージョンに新しい Fabric ワークスペースを使用することをお勧めします。
アクセス許可: 移行するADFワークスペースとアイテムへの読み取りアクセスおよび書き込むFabricワークスペースでの共同作成者以上の権限。
ネットワークと認証: マシン (対話型またはサービスプリンシパル) から Azure と Fabric の両方にサインインできることを確認します。

アップグレードの準備

パイプラインのアップグレードを開始する前に、環境に必要なツールとモジュールがあることを確認します。

PowerShell 7.4.2 (x64) 以降
FabricPipelineUpgrade モジュール

PowerShell 7.4.2 (x64) 以降をインストールする

コンピューターに PowerShell 7.4.2 以降が必要です。

PowerShell のダウンロード

FabricPipelineUpgrade モジュールをインストールしてインポートする

PowerShell 7 (x64) を開きます。
[スタート] メニューを選択し、 PowerShell 7 を検索し、アプリのコンテキストメニューを開き、[ 管理者として実行] を選択します。
管理者特権の PowerShell ウィンドウで、PowerShell ギャラリーからモジュールをインストールします。
```
Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck
```
モジュールをセッションにインポートします。
```
Import-Module Microsoft.FabricPipelineUpgrade
```
署名または実行ポリシーエラーが表示された場合は、次のコマンドを実行し、モジュールをもう一度インポートします。
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

インストールの検証

次のコマンドを実行して、モジュールが正しく読み込まれたかどうかを確認します。

Get-Command -Module Microsoft.FabricPipelineUpgrade

モジュールコマンドの出力のスクリーンショット。

PowerShell ウィンドウを開いたままにします。アップグレードに使用します。

初めてのアップグレード

サンプルパイプラインを作成し、プロセスのチュートリアルとして Fabric にアップグレードします。

単純な ADF パイプラインを作成する

Azure Data Factory Studio でパイプラインを作成し、待機アクティビティを追加します。名前は何でもかまいませんが、このチュートリアルでは pipeline1 を使用します。

PowerShell 環境を準備する

PowerShell ウィンドウで、 <your subscription ID> の値を置き換え、PowerShell で次のコマンドを実行してサインインし、サブスクリプションを設定します。
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```
次のコマンドを実行して、セッションのセキュリティで保護された ADF トークンを格納します。
```
$adfSecureToken = (Get-AzAccessToken -ResourceUrl "https://management.azure.com/").Token
```
PowerShell ウィンドウで、 <your subscription ID>、 <your Resource Group Name>、 <your Factory Name>の値を置き換えて、次のコマンドを実行します。
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName "pipeline1" -AdfToken $adfSecureToken
```
ヒント

複数のパイプラインを含むデータファクトリの場合は、 -PipelineName パラメーターを除外することで、すべてのパイプラインを一度にインポートできます。

このコマンドは、Azure Data Factory からパイプラインと関連する成果物を読み込み、最初の "アップグレードの進行状況" の JSON を作成します。

{
  "state": "Succeeded",
  "alerts": [],
  "result": {
    "importedResources": {
      "type": "AdfSupportFile",
      "adfName": "testdatafactory,
      "pipelines": {
        "pipeline1": {
          "name": "pipeline1",
          "type": "Microsoft.DataFactory/factories/pipelines",
          "properties": {
            "activities": [
              {
                "name": "Wait1",
                "type": "Wait",
                "dependsOn": [],
                "userProperties": [],
                "typeProperties": {
                  "waitTimeInSeconds": 1
                }
              }
            ],
            ],
            "policy": {
              "elapsedTimeMetric": {}
            },
            "annotations": [],
            "lastPublishTime": "2025-09-09T02:46:36Z"
          },
          "etag": "aaaaaaaa-bbbb-cccc-1111-222222222222"
        }
      },
      "datasets": {},
      "linkedServices": {},
      "triggers": {}
    }
  },
  "resolutions": []
}

これらのフィールドの意味

state: 状態を表示します。 [成功] と表示される場合は、問題ありません。
アラート: 問題や追加情報を一覧表示します。
result: 結果が表示されます。ここでは、importedResources に ADF アーティファクトが一覧表示されます。
解決策: ADF のリンクされたサービスをファブリック接続にマッピングするために使用されます (後のセクション)。

ADF パイプラインをファブリックパイプラインに変換する

PowerShell ウィンドウで、先ほど実行した Import-AdfFactory コマンドを実行し、 | を追加してから、ConvertTo-FabricResources コマンドを行の末尾に追加します。

完全なコマンドは次のようになります。
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName  "pipeline1" -AdfToken $adfSecureToken | ConvertTo-FabricResources
```

コマンドを実行します。次のような応答が表示されます。

{
  "state": "Succeeded",
  "alerts": [],
  "result": {
    "exportableFabricResources": [
      {
        "resourceType": "DataPipeline",
        "resourceName": "pipeline1",
        "resolve": [],
        "export": {
          "name": "pipeline1",
          "properties": {
            "activities": [
              {
                "name": "Wait1",
                "type": "Wait",
                "dependsOn": [],
                "userProperties": [],
                "description": null,
                "typeProperties": {
                  "waitTimeInSeconds": 1
                }
              }
            ]
          },
          "annotations": []
        }
      }
    ]
  },
  "resolutions": []
}

引き続き標準のアップグレードの進行状況が表示されますが、結果フィールドに exportableFabricResources が含まれるようになりました。それは期待されています。Fabric リソースをエクスポートする準備が整いました。

後で解像度フィールドについて学びます。現時点では、エクスポートフィールドには、待機アクティビティを含む Fabric パイプラインが表示されます。

ここで停止した場合、このコマンドは What-If のように機能します。このコマンドは、アップグレードによって作成される内容を示し、変更を加える前にアップグレードを検証するのに適した方法です。

Fabric ワークスペースから情報を収集する

Fabric パイプラインをエクスポートする前に、Fabric ワークスペースからいくつかの詳細が必要になります。空のテキストファイルを開いて、後で必要になる値をコピーします。

Microsoft Fabric UX を開き、Data Factory ワークスペースに移動します。
ワークスペース ID を見つけて、テキストファイルにコピーします。
次の PowerShell コマンドを実行して、ファブリックアクセストークンを取得し、セッション用に格納します。
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
ヒント

アクセストークンは約 1 時間後に期限切れになります。その場合は、コマンドをもう一度実行します。 Export-FabricResources がトークンの有効期限エラーを返した場合、トークンの有効期限が切れたことがわかります。

ファブリックパイプラインをエクスポートする

収集したすべての詳細を次のコマンドに結合します。

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline1" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

次に、テキストドキュメントから PowerShell ウィンドウにコマンドをコピーし、コマンドを実行します。

次のような応答が表示されます。

{
    "state": "Succeeded",
    "alerts": [],
    "result": {
      "exportedFabricResources": {
        "pipeline1": {
          "type": "DataPipeline",
          "workspaceId": "<your Workspace ID>",
          "id": "<The GUID of your new Pipeline>,
          "displayName": "pipeline1",
          "description": null
        }
      }
    }
  }

これは、それが機能したことを意味します! exportedFabricResources セクションには、新しいパイプラインとその ID が表示されます。次に、Fabric UX で Fabric ワークスペースを開きます。ページを更新すると、一覧に pipeline1 が表示されます。それを開くと、あなたが期待するものが正確に見つかります!

2 回目のアップグレード: データをコピーする

この 2 回目のアップグレードは最初のアップグレードとよく似ていますが、いくつかの新しい概念が導入されています。

データセットとリンクされたサービス
解決策

現在、Fabric Pipeline Upgrader は限られたデータセットセットをサポートしているため、Azure Blob Storage 接続と JSON データセットを使用します。詳しく見てみましょう。

ADF Studio で、Azure Blob Storage 内のあるフォルダーから別のフォルダーに JSON ファイルをコピーするパイプラインを作成します。このパイプラインを "pipeline2" と Azure Blob Storage 接続 "BlobStore1" と呼びますが、ここでも任意の名前を使用できます。

前と同じ What-If コマンドを実行してパイプラインをインポートし、移行の結果を確認します。必ずパイプライン名を更新してください。

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources

出力では、パイプラインは以前と似ていますが、2 つの exportableFabricResource を含む詳細が追加されました。

接続用の 1 つ
パイプライン用の 1 つ

出力の [接続 ] セクションの例を次に示します。

{
    "resourceName": "BlobStore1",
    "resourceType": "Connection",
    "resolve": [
    {
        "type": "LinkedServiceToConnectionId",
        "key": "BlobStore1",
        "targetPath": "id",
        "hint": {
        "linkedServiceName": "BlobStore1",
        "connectionType": "AzureBlobStorage",
        "datasource": "...",
        "template": {
            "type": "LinkedServiceToConnectionId",
            "key": "BlobStore1",
            "value": "<Fabric Connection ID>"
        }
        }
    }
    ],
    "export": {
    "id": "00000000-0000-0000-0000-000000000000"
    }
}

解決手順では、 Find the correct GUID and insert it into the id field of this resource. 現時点では、ID はすべてゼロ (空の GUID) です。エクスポーターでは解決できないため、ヒントでは問題を解決する方法に関するガイダンスが提供されます。

[パイプライン] セクションには、次のような手順があります。

"resolve": [
  {
    "type": "AdfResourceNameToFabricResourceId",
    "key": "Connection:BlobStore1",
    "targetPath": "properties.activities[0].typeProperties.source.datasetSettings.externalReferences.connection"
  },
  {
    "type": "AdfResourceNameToFabricResourceId",
    "key": "Connection:BlobStore1",
    "targetPath": "properties.activities[0].typeProperties.sink.datasetSettings.externalReferences.connection"
  }
],

これらの手順は何を行いますか?

これらの resolve 手順は、ADF のリンクされたサービスを、対応するファブリック接続 ID を使用してアクティビティの ソース と シンク にマップする手順です。

なぜこのようになるのですか?

これらのリソースが存在するまで、アップグレード者は接続またはパイプラインの Fabric リソース ID を認識できません。そのため、必要なリソースを作成し、解像度ファイルに入力する方法に関するヒントが提供されます。

次に、ファブリックパイプラインをエクスポートしましょう (試行 1)

アクセストークンの有効期限が切れた場合は、ここで更新します。

前のレッスンで使用したのと同じ手順を実行しますが、今回は "pipeline2" に対して実行します。

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

これは失敗します。今回は、 Import | Convert | Export コマンドは次のように返します。

{
    "state": "Failed",
    "alerts": [
      {
        "severity": "RequiresUserAction",
        "details": "Please use the hint and template to create/find a new connection and add its ID to your resolutions.",
        "connectionHint": {
          "linkedServiceName": "BlobStore1",
          "connectionType": "AzureBlobStorage",
          "datasource": "...",
          "template": {
            "type": "LinkedServiceToConnectionId",
            "key": "BlobStore1",
            "value": "<Fabric Connection ID>"
          }
        }
      }
    ],
    "resolutions": [],
    "result": {}
  }

(最後の手順の最後を読んだ場合は、 connectionHintが認識される場合があります)。

エラーには 、"接続の ID を解決に追加する" 必要があります。

問題が発生しましたか?

Fabric Upgrader は、単独では Fabric 接続を作成できません。ファブリック接続を手動で作成し、アップグレード者に使用するタイミングを指示することで、サポートが必要です。

解像度ファイルを作成する

まず、 解像度ファイルを作成します。任意の名前を付けてマシン上の任意の場所に保存できますが (PowerShell がアクセスできる限り)、このチュートリアルでは D:\Resolutions.jsonを使用します。
次の方法でファイルを初期化します。
```
[
]
```
次に、アップグレード者から提供されたヒントから不足している解像度を追加します。エラーメッセージの [ connectionHint ] セクションの [テンプレート] の下に表示されます。
```
[
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
]
```
次に、その <Fabric Connection ID>を見つける必要があります。これを行うには、Fabric UX で Fabric ワークスペースに移動し、右上隅にある歯車アイコンを選択してから、[ 接続とゲートウェイの管理] を選択します。
接続がまだ Fabric に存在しない場合は、ADF パイプラインが使用するのと同じ Azure Blob Storage アカウントへの新しい接続を作成します。任意の名前を付けることができますが、このチュートリアルでは "myblob" を使用します。
接続を作成したら、接続名の横にある省略記号ボタンをポイントしてメニューを表示します。
メニューから [設定] を選択し、 接続 ID を コピーし、 <Fabric Connection ID>の代わりに解像度ファイルに貼り付けます。

解像度ファイルは次のようになります ( value は異なります)。

[
    {
        "type": "LinkedServiceToConnectionId",
        "key": "BlobStore1",
        "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
    }
]

ついでに、次のようなコメントを解決策に追加できます。

[
   {
      "comment": "Resolve the ADF 'BlobStore1' LinkedService to the Fabric 'myblob' Connection",
      "type": "LinkedServiceToConnectionId",
      "key": "BlobStore1",
      "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
   }
]

Import-FabricResolutions コマンドレット

この解像度ファイルをインポートして、実行内容を確認できます。

PowerShell で、次のコマンドを実行します。

Import-FabricResolutions -rf "D:\Resolutions.json"

次の内容が表示されます。

{
  "state": "Succeeded",
  "alerts": [],
  "result": {},
  "resolutions": [
    {
      "type": "LinkedServiceToConnectionId",
      "key": "BlobStore1",
      "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
    }
  ]
}

これは別のアップグレードの進行状況オブジェクトですが、 resolutions フィールドが設定されるようになりました。

Import-FabricResolutionsは、コマンド チェーン内の任意の時点でExport-FabricResourcesの前に実行できます。決議は、後の手順に持ち越されます。

ファブリックパイプラインをエクスポートする (試行 2)

これで解決ファイルが作成されたので、 Import-FabricResolutions の手順を追加した後にエクスポートを再試行できます。

Import-FabricResolutionsとConvertの間にExportを追加して、コマンドを更新します。

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Import-FabricResolutions -ResolutionsFilename "<path to your resolutions file>" | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

PowerShell でコマンドを実行します。

今回は、それは動作します! ここでも、exportedFabricResources セクションには、新しいパイプラインとその ID が表示されます。

次に、Fabric UX で Fabric ワークスペースを開きます。ページを更新すると、一覧に pipeline1 が表示されます。それを開くと、あなたが期待するものが正確に見つかります!

次のステップ

2 つのパイプラインが正常にアップグレードされたので、学習した内容を使用して、さらに多くのパイプラインをアップグレードできます。

サポートされているアクティビティとデータセットの種類の詳細については、サポートされている機能を参照してください。
さまざまな種類のパイプラインの解像度ファイルを作成する方法の詳細については、解像度ファイルに接続を追加する方法を参照してください。
PowerShell を使用してこの移行を実行する一般的な手順については、「PowerShell を使用して Azure Data Factory から Fabric にパイプラインを移行する」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-09-22