Lernprogramm: Upgrade Ihrer Azure Data Factory-Pipelines auf Fabric-Pipelines mithilfe von PowerShell

Sie können Ihre Azure Data Factory(ADF)-Pipelines mithilfe des PowerShell-Moduls "Microsoft.FabricPipelineUpgrade" zu Microsoft Fabric migrieren. Dieses Lernprogramm enthält ein Beispiel für alle Schritte zum Ausführen der Migration mit bestimmten Anweisungen, Screenshots und Problembehandlungsschritten. Eine allgemeinere, prägnante Anleitung finden Sie in der Übersicht.

Vorbereiten auf ein Upgrade
So aktualisieren Sie eine ADF-Pipeline auf eine Fabric-Pipeline
Lesen und Behandeln von Warnungen

Voraussetzungen

Um zu beginnen, stellen Sie sicher, dass Sie über die folgenden Voraussetzungen verfügen:

Mandant: Ihr ADF- und Fabric-Arbeitsbereich muss sich im gleichen Microsoft Entra ID-Mandanten befinden.
Fabric: Ein Mandantenkonto mit einem aktiven Fabric-Abonnement – Kostenlos ein Konto erstellen.
Empfehlungen für Fabric-Arbeitsbereiche (optional): Es wird empfohlen, einen neuen Fabric-Arbeitsbereich in derselben Region wie Ihre ADF für Upgrades zu verwenden, um eine optimale Leistung zu erzielen.
Berechtigungen: Lesezugriff auf den ADF-Arbeitsbereich und Elemente, die Sie migrieren, und Mitwirkender oder höhere Rechte im Fabric-Arbeitsbereich, zu dem Sie schreiben.
Netzwerk und Authentifizierung: Stellen Sie sicher, dass Sie sich von Ihrem Computer (interaktiv oder Dienstprinzipal) bei Azure und Fabric anmelden können.

Vorbereiten des Upgrades

Bevor Sie mit dem Upgrade von Pipelines beginnen, überprüfen Sie, ob Ihre Umgebung über die erforderlichen Tools und Module verfügt:

PowerShell 7.4.2 (x64) oder höher
FabricPipelineUpgrade-Modul

Installieren von PowerShell 7.4.2 (x64) oder höher

Sie benötigen PowerShell 7.4.2 oder höher auf Ihrem Computer.

PowerShell herunterladen

Installieren und Importieren des FabricPipelineUpgrade-Moduls

Öffnen Sie PowerShell 7 (x64).
Wählen Sie das Startmenü aus, suchen Sie nach PowerShell 7, öffnen Sie das Kontextmenü der App, und wählen Sie "Als Administrator ausführen" aus.
Installieren Sie im PowerShell-Fenster mit erhöhten Rechten das Modul aus dem PowerShell-Katalog:
```
Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck
```

Importieren Sie das Modul in Ihre Sitzung:

Import-Module Microsoft.FabricPipelineUpgrade

Wenn ein Fehler bei der Signatur- oder Ausführungsrichtlinie angezeigt wird, führen Sie diesen Befehl aus, und importieren Sie das Modul erneut:
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

Überprüfen Sie Ihre Installation

Führen Sie diesen Befehl aus, um zu bestätigen, dass das Modul ordnungsgemäß geladen wurde:

Get-Command -Module Microsoft.FabricPipelineUpgrade

Screenshot der Modulbefehlsausgabe.

Lassen Sie Ihr PowerShell-Fenster geöffnet; Sie verwenden es für das Upgrade.

Ihr erstes Upgrade

Wir erstellen eine Beispielpipeline und aktualisieren sie auf Fabric, um den Prozess exemplarisch vorzuführen.

Erstellen einer einfachen ADF-Pipeline

Erstellen Sie im Azure Data Factory Studio eine Pipeline , und fügen Sie eine Wait-Aktivität hinzu. Sie können alles benennen, aber in diesem Lernprogramm wird Pipeline1 verwendet.

Vorbereiten der PowerShell-Umgebung

Ersetzen Sie im PowerShell-Fenster die Werte für <your subscription ID> und führen Sie diese Befehle in PowerShell aus, um sich anzumelden und Ihr Abonnement festzulegen.
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```

Führen Sie diesen Befehl aus, um das sichere ADF-Token für Ihre Sitzung zu speichern:

$adfSecureToken = (Get-AzAccessToken -ResourceUrl "https://management.azure.com/").Token

Ersetzen Sie im PowerShell-Fenster die Werte für <your subscription ID>, <your Resource Group Name>und <your Factory Name>führen Sie folgendes aus:
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName "pipeline1" -AdfToken $adfSecureToken
```
Tipp

Für Datenfabriken mit mehreren Pipelines können Sie alle Pipelines gleichzeitig importieren, indem Sie den -PipelineName Parameter verlassen.

Dieser Befehl lädt die Pipeline und die zugehörigen Artefakte aus Ihrer Azure Data Factory und erstellt das JSON für den ersten "Upgrade Progress".

{
  "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": []
}

Was diese Felder bedeuten

status: Zeigt den Status an. Wenn die Meldung "Erfolgreich" lautet, ist alles in Ordnung.
Warnungen: Listet alle Probleme oder zusätzlichen Informationen auf.
Ergebnis: Zeigt das Ergebnis an. Hier listet importedResources die ADF-Artefakte auf.
Auflösungen: Wird zum Zuordnen von ADF Linked Services zu Fabric Connections (späterer Abschnitt) verwendet.

Konvertieren Sie Ihre ADF-Pipeline in eine Fabric-Pipeline

Nehmen Sie in Ihrem PowerShell-Fenster den Import-AdfFactory Befehl, den Sie gerade ausgeführt haben, und fügen Sie | dann den Befehl ConvertTo-FabricResources am Ende der Zeile hinzu.

Der vollständige Befehl sollte wie folgt aussehen:
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName  "pipeline1" -AdfToken $adfSecureToken | ConvertTo-FabricResources
```

Führen Sie den Befehl aus. Sie sollten eine Antwort sehen, die ungefähr so aussieht:

{
  "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": []
}

Der standardmäßige Upgradestatus wird weiterhin angezeigt, aber jetzt enthält das Ergebnisfeld exportableFabricResources. Das wird erwartet; Sie richten die Fabric-Ressourcen zum Export bereit.

Sie erfahren später mehr über das Auflösungsfeld. Derzeit zeigt das Exportfeld eine Fabric-Pipeline mit einer Wait-Aktivität an.

Wenn Sie hier anhalten, verhält sich dieser Befehl wie eine Simulation: Er zeigt, was durch das Upgrade erstellt wird, und ist eine gute Möglichkeit, das Upgrade zu überprüfen, bevor Änderungen vorgenommen werden.

Sammeln von Informationen aus Ihrem Fabric-Arbeitsbereich

Bevor Sie Ihre Fabric-Pipeline exportieren, benötigen Sie einige Details aus Ihrem Fabric-Arbeitsbereich. Öffnen Sie eine leere Textdatei, um die Werte zu kopieren, die Sie später benötigen.

Öffnen Sie microsoft Fabric UX, und navigieren Sie zu Ihrem Data Factory-Arbeitsbereich.
Suchen Sie Ihre Arbeitsbereichs-ID , und kopieren Sie sie in Ihre Textdatei.
Führen Sie diesen PowerShell-Befehl aus, um Ihr Fabric-Zugriffstoken abzurufen und für Ihre Sitzung zu speichern:
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
Tipp

Zugriffstoken laufen nach etwa einer Stunde ab. Führen Sie in diesem Fall den Befehl erneut aus. Sie wissen, dass das Token abgelaufen ist, wenn Export-FabricResources einen Tokenablauffehler zurückgibt.

Fabric-Pipeline exportieren

Kombinieren Sie alle Details, die Sie in diesem Befehl gesammelt haben:

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

Kopieren Sie nun Ihren Befehl aus dem Textdokument in Ihr PowerShell-Fenster, und führen Sie den Befehl aus.

Sie sollten eine Antwort sehen, die ungefähr so aussieht:

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

Das bedeutet, dass es funktioniert hat! Im Abschnitt "exportedFabricResources" werden Ihre neue Pipeline und deren ID angezeigt. Öffnen Sie nun Ihren Fabric-Arbeitsbereich in Fabric UX. Aktualisieren Sie die Seite, und in der Liste wird Pipeline1 angezeigt. Öffnen Sie es, und Sie werden genau das finden, was Sie erwarten!

Ihr zweites Upgrade: Kopieren einiger Daten

Dieses zweite Upgrade ähnelt dem ersten, führt aber ein paar neue Konzepte ein:

Datensätze und Verknüpfte Dienste
Lösungen

Der Fabric Pipeline Upgrader unterstützt derzeit eine begrenzte Gruppe von Datasets, daher verwenden wir Azure Blob Storage-Verbindungen und JSON-Datasets. Tauchen wir ein.

Erstellen Sie in ADF Studio eine Pipeline, die eine JSON-Datei aus einem Ordner in Ihrem Azure Blob Storage in einen anderen kopiert . Wir nennen diese Pipeline "pipeline2" und die Azure Blob Storage-Verbindung "BlobStore1", aber auch hier können Sie beliebige Namen verwenden.We'll call this pipeline "pipeline2" and the Azure Blob Storage connection "BlobStore1", but again, you can use any names you like.

Führen Sie den gleichen What-If Befehl wie zuvor aus, um Ihre Pipeline zu importieren, und überprüfen Sie, was das Migrationsergebnis wäre. Stellen Sie sicher, dass Sie den Namen der Pipeline aktualisieren.

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

In der Ausgabe sieht die Pipeline ähnlich wie zuvor aus, aber jetzt gibt es mehr Details, einschließlich zweier exportierbarer Fabric-Ressourcen:

Eine für eine Verbindung
Eine für eine Pipeline

Hier ist ein Beispiel für den Verbindungsabschnitt der Ausgabe:

{
    "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"
    }
}

Der Lösungsschritt besagt: Find the correct GUID and insert it into the id field of this resource. Die ID besteht vorerst aus lauter Nullen (eine leere GUID). Da der Exporter es nicht beheben kann, enthält der Hinweis Anleitungen zum Beheben des Problems.

Der Abschnitt "Pipeline" weist ähnliche Schritte auf:

"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"
  }
],

Was tun diese Schritte?

Diese resolve Schritte sind Anweisungen, mit denen Sie Ihre ADF-verknüpften Dienste der Aktivitäten zu der entsprechenden Quelle und Senke mit der passenden Fabric-Verbindungs-ID zuordnen.

Was ist dafür die Ursache?

Der Upgrader kann die Fabric-Ressourcen-ID für eine Verbindung oder Pipeline erst kennen, wenn diese Ressourcen vorhanden sind. Daher bietet es einen Tipp, wie Sie die erforderlichen Ressourcen erstellen und Ihre Auflösungsdatei ausfüllen.

Exportieren wir nun die Fabric-Pipeline (Versuch 1)

Wenn Ihre Zugriffstoken abgelaufen sind, aktualisieren Sie sie jetzt.

Führen Sie die gleichen Schritte aus, die Sie in der vorherigen Lektion verwendet haben, aber für "pipeline2" dieses Mal.

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

Dies schlägt fehl. Dieses Mal gibt der Import | Convert | Export Befehl etwas wie folgt zurück:

{
    "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": {}
  }

(Wenn Sie das Ende des letzten Schritts gelesen haben, können Sie connectionHint möglicherweise erkennen.)

Der Fehler besagt, dass wir die ID einer Verbindung zu Ihren Auflösungen hinzufügen müssen.

Was ist schief gegangen?

Der Fabric-Upgrader kann Fabric-Verbindungen nicht selbst erstellen. Sie müssen dabei helfen, indem Sie eine Fabric-Verbindung manuell erstellen und dann dem Upgrader mitteilen, wann sie verwendet werden soll.

Erstellen einer Lösungsdatei

Erstellen Sie zunächst eine Lösungsdatei. Sie können es beliebig benennen und überall dort speichern, wo Sie möchten (solange PowerShell darauf zugreifen kann), aber in diesem Tutorial wird D:\Resolutions.json verwendet.
Initialisieren Sie die Datei mit:
```
[
]
```
Fügen Sie als Nächstes Ihre fehlende Auflösung aus dem Hinweis hinzu, den Sie von Ihrem Upgrader erhalten haben. Sie finden sie unter "Vorlage" im connectionHint Abschnitt der Fehlermeldung.
```
[
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
]
```
Als Nächstes müssen wir das <Fabric Connection ID> finden. Wechseln Sie dazu zu Ihrem Fabric-Arbeitsbereich in Fabric UX, wählen Sie das Zahnradsymbol in der oberen rechten Ecke aus, und wählen Sie dann "Verbindungen und Gateways verwalten" aus.
Wenn die Verbindung noch nicht in Fabric vorhanden ist, erstellen Sie eine neue Verbindung mit demselben Azure Blob Storage-Konto, das Ihre ADF-Pipeline verwendet. Sie können es alles benennen, aber in diesem Lernprogramm wird "myblob" verwendet.
Zeigen Sie nach dem Erstellen der Verbindung auf die Auslassungspunkteschaltfläche neben dem Verbindungsnamen, um das Menü anzuzeigen.
Wählen Sie im Menü "Einstellungen" aus, kopieren Sie dann die Verbindungs-ID und fügen Sie sie in Ihre Auflösungsdatei anstelle von <Fabric Connection ID> ein.

Die Auflösungsdatei sollte ungefähr wie folgt aussehen (Ihre value Auflösungen sind anders):

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

Während Sie dabei sind, können Sie Ihrer Lösung wie folgt einen Kommentar hinzufügen:

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

Das Import-FabricResolutions-Cmdlet

Sie können diese Auflösungsdatei importieren, um zu überprüfen, was sie tut.

Führen Sie in PowerShell Folgendes aus:

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

Sie sollten Folgendes sehen:

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

Dies ist ein weiteres Upgrade-Fortschrittsobjekt, aber jetzt ist das resolutions-Feld ausgefüllt.

Sie können Import-FabricResolutions an jedem beliebigen Punkt in der Befehlskette ausführen, bevor . Die Entschließungen werden zu einem späteren Zeitpunkt vorangebracht.

Export der Fabric-Pipeline (Versuch 2)

Nachdem wir nun eine Lösungsdatei haben, können wir den Export nach dem Hinzufügen des Import-FabricResolutions Schritts erneut versuchen.

Aktualisieren Sie Ihren Befehl, indem Sie Import-FabricResolutions zwischen Convert und Export einfügen.

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

Führen Sie den Befehl in PowerShell aus.

Dieses Mal funktioniert es! Auch hier zeigt der Abschnitt "exportedFabricResources" Ihre neue Pipeline und deren ID an.

Öffnen Sie nun Ihren Fabric-Arbeitsbereich in Fabric UX. Aktualisieren Sie die Seite, und in der Liste wird Pipeline1 angezeigt. Öffnen Sie es, und Sie werden genau das finden, was Sie erwarten!

Nächste Schritte

Nachdem Sie nun zwei Pipelines erfolgreich aktualisiert haben, können Sie das gelernte Verwenden, um weitere Pipelines zu aktualisieren.

Weitere Informationen zu den unterstützten Aktivitäten und Datasets finden Sie in der unterstützten Funktionalität.
Weitere Informationen zum Erstellen der Auflösungsdatei für verschiedene Arten von Pipelines finden Sie unter Hinzufügen von Verbindungen zu Ihrer Auflösungsdatei.
Allgemeine Schritte zum Ausführen dieser Migration mithilfe von PowerShell finden Sie unter: Migrieren von Pipelines aus Azure Data Factory zu Fabric mithilfe von PowerShell.

Feedback

War diese Seite hilfreich?

Last updated on 2025-09-22