Esercitazione: Aggiornare le pipeline di Azure Data Factory alle pipeline di Fabric usando PowerShell

Suggerimento

Per la maggior parte degli upgrade, usa l'esperienza di upgrade integrata. Fornisce un percorso di aggiornamento guidato e no-code direttamente nell'Azure Data Factory UX. Usare l'approccio PowerShell in questa esercitazione per scenari basati su script, operazioni in blocco e/o guidati da CI/CD.

Puoi aggiornare le pipeline di Azure Data Factory (ADF) a Microsoft Fabric usando il modulo PowerShell di Microsoft. FabricPipelineUpgrade PowerShell. Questo tutorial fornisce un esempio di tutti i passaggi per eseguire l'aggiornamento con istruzioni specifiche, screenshot e passaggi di risoluzione dei problemi. Per una guida più generale e concisa, vedere la panoramica.

Come preparare un aggiornamento
Come aggiornare una pipeline di Azure Data Factory a una pipeline di Fabric
Leggere e gestire gli avvisi

Prerequisiti

Tenant: L'area di lavoro di Azure Data Factory e Fabric deve trovarsi nello stesso tenant Microsoft Entra ID.
Fabric: un account tenant con una sottoscrizione di Fabric attiva - Creare gratuitamente un account.
Raccomandazioni per l'area di lavoro di Fabric (Facoltativo): Usare una nuova area di lavoro di Fabric nella stessa area geografica di ADF per gli aggiornamenti, per prestazioni ottimali.
Permessi: Accesso di lettura allo spazio di lavoro ADF e agli elementi che vuoi aggiornare e diritti di Contributore o superiori nello spazio di lavoro Fabric su cui vuoi scrivere.
Rete e autenticazione: assicurarsi di poter accedere sia ad Azure che a Fabric dal computer (entità servizio o interattiva).

Preparare l'aggiornamento

Prima di iniziare l'aggiornamento delle pipeline, verificare che l'ambiente disponga degli strumenti e dei moduli necessari:

PowerShell 7.4.2 (x64) o versione successiva
Modulo FabricPipelineUpgrade

Installare PowerShell 7.4.2 (x64) o versione successiva

Nel computer è necessario PowerShell 7.4.2 o versione successiva.

Scaricare PowerShell

Installare e importare il modulo FabricPipelineUpgrade

Aprire PowerShell 7 (x64).
Selezionare il menu Start, cercare PowerShell 7, aprire il menu di scelta rapida dell'app e selezionare Esegui come amministratore.
Nella finestra di PowerShell con privilegi elevati installare il modulo da PowerShell Gallery:
```
Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck
```

Importare il modulo nella sessione:

Import-Module Microsoft.FabricPipelineUpgrade

Se viene visualizzato un errore di firma o di criteri di esecuzione, eseguire questo comando e quindi importare di nuovo il modulo:
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

Verifica dell'installazione

Eseguire questo comando per confermare il caricamento corretto del modulo:

Get-Command -Module Microsoft.FabricPipelineUpgrade

Screenshot dell'output del comando del modulo.

Mantenere aperta la finestra di PowerShell; verrà usato per l'aggiornamento.

Il primo aggiornamento

Verrà creata una pipeline di esempio e aggiornata a Fabric per fornire una guida dettagliata al processo.

Creare facilmente una semplice pipeline di Azure Data Factory

In Azure Data Factory Studio creare una pipeline e aggiungere un'attività di attesa . È possibile denominarlo qualsiasi elemento, ma questa esercitazione usa pipeline1.

Preparare l'ambiente PowerShell

Nella finestra di PowerShell sostituire i valori per <your subscription ID> ed eseguire questi comandi in PowerShell per accedere e impostare la sottoscrizione:
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```

Eseguire questo comando per archiviare il token ADF sicuro per la sessione:

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

Nella finestra di PowerShell sostituire i valori per <your subscription ID>, <your Resource Group Name>e <your Factory Name>ed eseguire:
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName "pipeline1" -AdfToken $adfSecureToken
```
Suggerimento

Per data factory con più pipeline, è possibile importare tutte le pipeline contemporaneamente lasciando il -PipelineName parametro .

Questo comando carica la pipeline e gli artefatti associati dal tuo Azure Data Factory e crea il codice JSON per il primo "Avanzamento dell'aggiornamento".

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

Cosa significano questi campi

state: mostra lo stato. Se dice "superato", va bene così.
avvisi: elenca eventuali problemi o informazioni aggiuntive.
result: mostra il risultato. In questo caso, importedResources elenca gli artefatti di Azure Data Factory.
risoluzioni: usate per la mappatura dei servizi collegati di Azure Data Factory alle connessioni Fabric (sezione successiva).

Convertire la pipeline di Azure Data Factory in una Fabric Pipeline

Nella finestra di PowerShell eseguire il comando Import-AdfFactory appena eseguito e aggiungere | e quindi il comando ConvertTo-FabricResources alla fine della riga.

Il comando completo dovrebbe essere simile al seguente:

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

Eseguire il comando . Verrà visualizzata una risposta simile alla seguente:

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

Verrà comunque visualizzato lo stato di avanzamento dell'aggiornamento standard, ma ora il campo dei risultati include exportableFabricResources. Questo è previsto; stai preparando le risorse Fabric per l'esportazione.

Avrai modo di conoscere il campo risoluzioni più avanti. Per il momento, il campo di esportazione mostra una pipeline Fabric con un'attività Wait.

Se ti fermi qui, questo comando funge da ipotetico: mostra cosa creerebbe l'aggiornamento ed è un buon modo per verificare l'aggiornamento prima di apportare modifiche.

Raccogliere informazioni dall'area di lavoro Fabric

Prima di esportare la pipeline di Fabric, avrai bisogno di alcuni dettagli dall'area di lavoro di Fabric. Aprire un file di testo vuoto per copiare i valori necessari in un secondo momento.

Aprire l'esperienza utente di Microsoft Fabric e passare all'area di lavoro di Data Factory.
Trovare l'ID dell'area di lavoro e copiarlo nel file di testo.
Eseguire questo comando di PowerShell per ottenere il token di accesso Fabric e archiviarlo per la sessione:
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
Suggerimento

I token di accesso scadono dopo circa un'ora. In questo caso, eseguire di nuovo il comando. Il token è scaduto se Export-FabricResources restituisce un errore di scadenza del token.

Esportare la Pipeline di Fabric

Combinare tutti i dettagli raccolti in questo comando:

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

Copiare ora il comando dal documento di testo nella finestra di PowerShell ed eseguire il comando .

Verrà visualizzata una risposta simile alla seguente:

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

Questo significa che ha funzionato! La sezione exportedFabricResources mostra la nuova pipeline e il relativo ID. Apri ora l'area di lavoro Fabric nell'esperienza utente di Fabric. Aggiornare la pagina e verrà visualizzata pipeline1 nell'elenco. Aprilo e troverai esattamente quello che ti aspetti!

Il secondo aggiornamento: copiare alcuni dati

Questo secondo aggiornamento è molto simile al primo, ma introduce un paio di nuovi concetti:

Set di dati e Servizi Collegati
Soluzioni

Il Fabric Pipeline Upgrader supporta attualmente un set limitato di set di dati , quindi useremo connessioni Archiviazione BLOB di Azure e set di dati JSON. Cominciamo.

In ADF Studio creare una pipeline che copia un file JSON da una cartella nello Archiviazione BLOB di Azure a un'altra. Questa pipeline verrà chiamata "pipeline2" e la connessione Archiviazione BLOB di Azure "BlobStore1", ma anche in questo caso è possibile usare tutti i nomi desiderati.

Esegui lo stesso comando What-If di prima per importare la pipeline e verifica quale sarà l'esito dell'aggiornamento. Assicuratevi di aggiornare il nome della pipeline.

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

Nell'output la pipeline è simile a prima, ma ora sono disponibili altri dettagli, tra cui due exportableFabricResources:

Uno per una connessione
Uno per una pipeline

Di seguito è riportato un esempio della sezione Connessione dell'output:

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

Il passaggio di risoluzione indica: Find the correct GUID and insert it into the id field of this resource. per il momento, l'ID è tutti zeri (un GUID vuoto). Poiché l'utilità di esportazione non è in grado di risolverla, il suggerimento fornisce indicazioni su come risolvere il problema.

La sezione Pipeline prevede passaggi simili:

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

Cosa fanno questi passaggi?

Questi passaggi resolve consentono di eseguire il mapping dei servizi collegati di Azure Data Factory alle attività "source" e "sink" con l'ID connessione Fabric corrispondente.

Perché si verifica questa situazione?

L'aggiornamento non è in grado di conoscere l'ID risorsa Fabric per una connessione o una pipeline fino a quando tali risorse non esistono. Fornisce quindi un suggerimento su come creare le risorse necessarie e compilare il file di risoluzione.

Adesso esportiamo la pipeline Fabric (tentativo 1)

Se i token di accesso sono scaduti, aggiornarli ora.

Eseguire gli stessi passaggi usati nella lezione precedente, ma per "pipeline2" questa volta.

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

Questo fallisce. Questa volta, il Import | Convert | Export comando restituisce un risultato simile al seguente:

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

Se si legge la fine dell'ultimo passaggio, è possibile riconoscere connectionHint.

L'errore indica che è necessario "aggiungere l'ID di una connessione alle risoluzioni".

Cosa è andato storto?

Il Fabric Upgrader non può creare connessioni Fabric autonomamente. È necessario aiutare a creare manualmente una connessione a Fabric e quindi indicare all'upgrader quando usarla.

Creare un file di risoluzioni

Creare prima di tutto un file Risoluzioni. È possibile denominarlo qualsiasi elemento e salvarlo ovunque si desideri nel computer (purché PowerShell possa accedervi), ma questa esercitazione usa D:\Resolutions.json.
Inizializzare il file con:
```
[
]
```
Aggiungere quindi la risoluzione mancante dall'hint fornito dal componente di aggiornamento. È possibile trovarlo in 'template' nella connectionHint sezione del messaggio di errore.
```
[
  {
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
  }
]
```
Successivamente, dobbiamo trovare <Fabric Connection ID>. Per fare ciò, vai all'area di lavoro Fabric nell'interfaccia utente di Fabric, seleziona l'icona a forma di ingranaggio nell'angolo in alto a destra, quindi seleziona Gestisci connessioni e gateway.
Se la connessione non esiste ancora in Fabric, creare una nuova connessione allo stesso account Archiviazione BLOB di Azure usato dalla pipeline di Azure Data Factory. È possibile denominarlo qualsiasi elemento, ma questa esercitazione usa "myblob".
Dopo aver creato la connessione, passare il puntatore del mouse sul pulsante con i puntini di sospensione accanto al nome della connessione per visualizzare il menu.
Selezionare Impostazioni dal menu, quindi copiare l'ID connessione e incollarlo nel file Risoluzioni al posto di <Fabric Connection ID>.

Il file delle risoluzioni dovrebbe essere simile al seguente (il file value sarà diverso):

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

Mentre si è in questo punto, è possibile aggiungere un commento alla risoluzione in questo modo:

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

Cmdlet Import-FabricResolutions

È possibile importare questo file di risoluzioni per verificare le operazioni che esegue.

In PowerShell eseguire:

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

Dovresti vedere:

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

Si tratta di un altro oggetto di stato dell'aggiornamento, ma ora il campo resolutions viene popolato.

È possibile eseguire Import-FabricResolutions in qualsiasi punto della catena di comandi primaExport-FabricResources. Le risoluzioni verranno portate avanti ai passaggi successivi.

Esportare la pipeline di Fabric (tentativo 2)

Ora che è disponibile un file di risoluzioni, è possibile riprovare l'esportazione dopo aver aggiunto il Import-FabricResolutions passaggio.

Aggiornare il comando aggiungendo Import-FabricResolutions tra Convert e 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

Eseguire il comando in PowerShell.

Questa volta, funziona! Anche in questo caso, la sezione exportedFabricResources mostra la nuova pipeline e il relativo ID.

Apri ora l'area di lavoro Fabric nell'esperienza utente di Fabric. Aggiornare la pagina e verrà visualizzata pipeline1 nell'elenco. Aprilo e troverai esattamente quello che ti aspetti!

Passaggi successivi

Dopo aver aggiornato correttamente due pipeline, è possibile usare ciò che si è appreso per aggiornare più pipeline.

Per altre informazioni sui tipi di attività e set di dati supportati, vedere la funzionalità supportata.
Per altre informazioni su come creare il file di risoluzioni per diversi tipi di pipeline, vedere come aggiungere connessioni al file delle risoluzioni.
Per i passaggi generali su come eseguire questo aggiornamento usando PowerShell, vedi: Aggiorna pipeline da Azure Data Factory a Fabric usando PowerShell.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-29