教程：使用 PowerShell 将 Azure 数据工厂管道升级到 Fabric 管道

可以使用 Microsoft.FabricPipelineUpgrade PowerShell 模块将 Azure 数据工厂（ADF）管道迁移到 Microsoft Fabric。本教程提供了使用特定说明、屏幕截图和故障排除步骤执行迁移的所有步骤的示例。有关更常规、简洁的指南，请参阅概述。

如何准备升级
如何将 ADF 管道升级到 Fabric 管道
读取和处理警报

先决条件

若要开始，请确保满足以下先决条件：

租户：ADF 和 Fabric 工作区必须位于同一 Microsoft Entra ID 租户中。
Fabric：具有活动 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 Gallery 库安装模块：

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 数据工厂工作室中，创建管道并添加等待活动。你可以将其命名为任何内容，但本教程使用 pipeline1。

准备 PowerShell 环境

在 PowerShell 窗口中，替换 <your subscription ID> 的值，然后运行这些命令以登录并设置您的订阅。
```
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 数据工厂加载管道和关联的项目，并为第一个“升级进度”创建 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": []
}

这些字段的含义

状态：显示状态。如果显示成功，那就没问题了。
警报：列出任何问题或额外信息。
result：显示结果。此处，importedResources 列出了 ADF 工件。
解决方法：用于将 ADF 链接服务映射到构造连接（稍后部分）。

将 ADF 管道转换为 Fabric 管道

在 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 资源。

稍后你将了解“分辨率”字段。目前，导出字段显示包含 Wait 活动的 Fabric 管道。

如果在此处停止，此命令将类似于 What-If：它显示升级将创建的内容，并且是验证升级之前进行任何更改的好方法。

从 Fabric 工作区收集信息

在导出你的 Fabric 管道之前，你需要收集一些来自 Fabric 工作区的详细信息。打开空白文本文件以复制稍后需要的值。

打开Microsoft Fabric UX 并导航到数据工厂工作区。
找到工作区 ID 并将其复制到文本文件中。
运行此 PowerShell 命令以获取 Fabric 访问令牌并将其存储在会话中：
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
小窍门

访问令牌在大约一小时后过期。发生这种情况时，请再次运行该命令。如果 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。打开它，你将找到你期望的确切内容！

第二项升级：复制部分数据

第二次升级与第一个升级非常类似，但引入了几个新概念：

数据集和 LinkedServices
解决方案

Fabric 管道升级程序目前支持一组有限的数据集，因此我们将使用 Azure Blob 存储连接和 JSON 数据集。让我们进一步探讨一下。

在 ADF Studio 中，创建一个管道，用于将 JSON 文件从 Azure Blob 存储中的一个文件夹复制到另一个文件夹。我们会将此管道命名为“pipeline2”，将 Azure Blob 存储连接命名为“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

在输出中，管道与以前的版本类似，但现在包含更多详细信息，包括两个可导出的Fabric资源：

一个用于连接
一个用于管道

下面是输出的 “连接” 部分的示例：

{
    "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 链接服务映射到具有相应 Fabric 连接 ID 的活动源和 接收器 的说明。

为何发生这种情况？

在存在这些资源之前，升级程序无法知道连接或管道的 Fabric 资源 ID。因此，它提供了有关如何创建必要资源并填写解析文件的提示。

现在，我们来导出 Fabric Pipeline （尝试 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 升级程序无法自行创建 Fabric 连接。你需要通过手动创建 Fabric 连接来提供帮助，然后告诉升级程序何时使用它。

创建分辨率文件

首先，创建 Resolutions 文件。可以将它命名为任何名称并保存在 PowerShell 可以访问的位置，但本教程使用 D:\Resolutions.json。
使用以下命令初始化文件：
```
[
]
```
接下来，从升级工具提供的提示中添加缺少的分辨率。可以在错误消息部分的 connectionHint “模板”下找到它。
```
[
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
]
```
接下来，我们需要找到<Fabric Connection ID>。为此，请转到 Fabric UX 中的 Fabric 工作区，选择右上角的齿轮图标，然后选择“ 管理连接”和“网关”。
如果 Fabric 中尚不存在该连接，请创建与 ADF 管道使用的同一 Azure Blob 存储帐户的新连接。你可以将其命名为任意名称，但本教程使用“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 cmdlet

可以导入此分辨率文件来检查它的作用。

在 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。打开它，你将找到你期望的确切内容！

后续步骤

现已成功升级两个管道，接下来可以使用所学内容来升级更多管道。

有关支持的活动和数据集类型的详细信息，请参阅支持的功能。
有关如何为不同类型的管道创建解析文件的详细信息，请参阅如何向解析文件添加连接。
有关使用 PowerShell 执行此迁移的常规步骤，请参阅：使用 PowerShell 将管道从 Azure 数据工厂迁移到 Fabric。

反馈

此页面是否有帮助？

Last updated on 2025-09-22