Tutorial: Atualizar seus pipelines do Azure Data Factory para pipelines do Fabric usando o PowerShell

Você pode migrar seus pipelines do AdF (Azure Data Factory) para o Microsoft Fabric usando o módulo Microsoft.FabricPipelineUpgrade PowerShell. Este tutorial fornece um exemplo de todas as etapas para executar a migração com instruções específicas, capturas de tela e etapas de solução de problemas. Para obter um guia mais geral e conciso, consulte a visão geral.

Como se preparar para uma atualização
Como atualizar um pipeline do ADF para um pipeline do Fabric
Ler e manipular alertas

Pré-requisitos

Para começar, verifique se você tem os seguintes pré-requisitos:

Locatário: seu workspace do ADF e do Fabric deve estar no mesmo locatário do Microsoft Entra ID.
Fabric: uma conta de locatário do Fabric com uma assinatura ativa – Crie uma conta gratuita.
Recomendações de workspace do Fabric (opcional): recomendamos usar um novo workspace do Fabric na mesma região que o ADF para atualizações para obter o melhor desempenho.
Permissões: Acesso de leitura ao workspace do ADF e aos itens que você migrará e direitos de colaborador ou superiores no workspace do Fabric onde você escreverá.
Rede e autenticação: verifique se você pode fazer login no Azure e no Fabric por meio do computador (interativo ou principal de serviço).

Prepare-se para atualizar

Antes de começar a atualizar os pipelines, verifique se o ambiente tem as ferramentas e os módulos necessários:

PowerShell 7.4.2 (x64) ou posterior
Módulo FabricPipelineUpgrade

Instalar o PowerShell 7.4.2 (x64) ou posterior

Você precisa do PowerShell 7.4.2 ou posterior em seu computador.

Baixar o PowerShell

Instalar e importar o módulo FabricPipelineUpgrade

Abra o PowerShell 7 (x64).
Selecione o menu Iniciar, pesquise o PowerShell 7, abra o menu de contexto do aplicativo e selecione Executar como administrador.

Na janela do PowerShell elevada, instale o módulo a partir da PowerShell Gallery:

Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck

Importe o módulo para sua sessão:

Import-Module Microsoft.FabricPipelineUpgrade

Se você vir um erro de política de assinatura ou execução, execute este comando e importe o módulo novamente:
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

Verificar a instalação

Execute este comando para confirmar o módulo carregado corretamente:

Get-Command -Module Microsoft.FabricPipelineUpgrade

Captura de tela da saída do comando do módulo.

Mantenha a janela do PowerShell aberta; você o usará para a atualização.

Sua primeira atualização

Criaremos um pipeline de exemplo e o atualizaremos para o Fabric como um passo a passo do processo.

Criar um pipeline do ADF simples

No Azure Data Factory Studio, crie um pipeline e adicione uma atividade de espera. Você pode nomeá-lo qualquer coisa, mas este tutorial usa pipeline1.

Preparar seu ambiente do PowerShell

Na janela do PowerShell, substitua os valores <your subscription ID> e execute estes comandos no PowerShell para entrar e definir sua assinatura:
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```

Execute este comando para armazenar o token seguro do ADF para sua sessão:

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

Na janela do PowerShell, substitua os valores por <your subscription ID>, <your Resource Group Name>e <your Factory Name>, e execute:
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName "pipeline1" -AdfToken $adfSecureToken
```
Dica

Para fábricas de dados com vários pipelines, você pode importar todos os pipelines de uma só vez, omitindo o parâmetro -PipelineName.

Esse comando carrega o pipeline e os artefatos associados do Azure Data Factory e cria o JSON para o primeiro "Progresso de Atualização".

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

O que esses campos significam

estado: mostra o status. Se diz bem-sucedido, você é bom.
alertas: lista quaisquer problemas ou informações extras.
resultado: mostra o resultado. Aqui, importedResources lista os artefatos do ADF.
resoluções: usadas para mapear os Serviços Vinculados do ADF para Conexões do Fabric (seção posterior).

Converter o Pipeline do ADF em um Pipeline do Fabric

Na janela do PowerShell, pegue o comando Import-AdfFactory que você acabou de executar e adicione | e, em seguida, o comando ConvertTo-FabricResources ao final da linha.

Seu comando completo deve ter esta aparência:

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

Execute o comando. Você deve ver uma resposta como esta:

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

Você ainda verá o progresso de atualização padrão, mas agora o campo de resultado inclui exportableFabricResources. Isso é esperado; você está preparando os recursos do Fabric para exportar.

Você aprenderá mais tarde sobre o campo de resoluções. Por enquanto, o campo de exportação mostra um pipeline do Fabric com uma atividade Wait.

Se você parar aqui, esse comando atuará como um What-If: ele mostra o que a atualização criaria e é uma boa maneira de validar a atualização antes de fazer qualquer alteração.

Coletar informações do seu workspace do Fabric

Antes de exportar o pipeline do Fabric, você precisará de alguns detalhes do espaço de trabalho do Fabric. Abra um arquivo de texto em branco para copiar os valores necessários posteriormente.

Abra o Microsoft Fabric UX e navegue até o workspace do Data Factory.
Localize sua ID do Workspace e copie-a no arquivo de texto.
Execute este comando do PowerShell para obter o Token de Acesso do Fabric e armazená-lo para sua sessão:
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
Dica

Os tokens de acesso expiram após cerca de uma hora. Quando isso acontecer, execute o comando novamente. Você saberá que o token expirou se Export-FabricResources retornar um erro de expiração do token.

Exportar o Pipeline do Fabric

Combine todos os detalhes que você reuniu neste 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

Agora, copie o comando do documento de texto para a janela do PowerShell e execute o comando.

Você deve ver uma resposta como esta:

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

Isso significa que funcionou! A seção exportedFabricResources mostra o seu novo pipeline e seu ID. Agora, abra o workspace do Fabric no Fabric UX. Atualize a página e você verá o pipeline1 na lista. Abra-o e você encontrará exatamente o que espera!

Sua segunda atualização: copiar alguns dados

Esta segunda atualização é muito parecida com a primeira, mas apresenta alguns novos conceitos:

Conjuntos de dados e Serviços Conectados
Resoluções

Atualmente, o Fabric Pipeline Upgrader dá suporte a um conjunto limitado de conjuntos de dados, portanto, usaremos conexões do Armazenamento de Blobs do Azure e conjuntos de dados JSON. Vamos mergulhar.

No ADF Studio, crie um pipeline que copia um arquivo JSON de uma pasta no Armazenamento de Blobs do Azure para outra. Chamaremos esse pipeline de "pipeline2" e a conexão de Armazenamento de Blobs do Azure de "BlobStore1", mas, novamente, você pode usar os nomes desejados.

Execute o mesmo comando What-If de antes para importar o pipeline e verificar qual seria o resultado da migração. Certifique-se de atualizar o nome do pipeline.

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

Na saída, o pipeline é semelhante ao anterior, mas agora há mais detalhes, incluindo dois exportableFabricResources:

Um para uma conexão de rede
Um para um Pipeline

Aqui está um exemplo da seção Conexão da saída:

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

A etapa de resolução diz: Find the correct GUID and insert it into the id field of this resource. Por enquanto, o ID é formado por zeros (um GUID vazio). Como o exportador não pode resolvê-lo, a dica fornece orientação sobre como resolver o problema.

A seção Pipeline tem etapas semelhantes:

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

O que essas etapas fazem?

Estas resolve etapas são instruções para você mapear os serviços vinculados do ADF para a origem e o coletor das atividades com a ID de Conexão do Fabric correspondente.

Por que isso acontece?

O atualizador não pode saber a ID de recurso do Fabric para uma conexão ou pipeline até que esses recursos existam. Portanto, ele fornece uma dica sobre como criar os recursos necessários e preencher o arquivo de resolução.

Agora, vamos exportar o Fabric Pipeline (tentativa 1)

Se os tokens de acesso expirarem, atualize-os agora.

Execute as mesmas etapas usadas na lição anterior, mas para "pipeline2" desta vez.

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

Isso falha. Desta vez, o Import | Convert | Export comando retorna algo como:

{
    "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 você ler o final da última etapa, poderá reconhecer connectionHint.)

O erro diz que precisamos "adicionar a ID da conexão às suas resoluções".

O que deu errado?

O Fabric Upgrader não pode criar conexões de Fabric por conta própria. Você precisa ajudar criando uma conexão do Fabric manualmente e informando ao atualizador quando usá-la.

Criar um arquivo de resoluções

Primeiro, crie um arquivo de Resoluções. Você pode nomeá-lo como quiser e salvá-lo onde preferir em seu computador (contanto que o PowerShell possa acessá-lo), mas este tutorial usa D:\Resolutions.json.
Inicialize o arquivo com:
```
[
]
```
Em seguida, adicione sua resolução ausente com base na dica que o atualizador lhe deu. Você pode encontrá-lo em "modelo" na seção connectionHint da mensagem de erro.
```
[
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
]
```
Em seguida, precisamos encontrar aquele <Fabric Connection ID>. Para fazer isso, vá para o workspace do Fabric no Fabric UX, selecione o ícone de engrenagem no canto superior direito e selecione Gerenciar conexões e gateways.
Se a conexão ainda não existir no Fabric, crie uma nova conexão com a mesma conta de armazenamento de Blobs do Azure usada pelo pipeline do ADF. Você pode nomeá-lo qualquer coisa, mas este tutorial usa "myblob".
Depois de criar a conexão, passe o mouse sobre o botão com três pontos ao lado do nome da conexão para exibir o menu.
Selecione Configurações no menu, copie a ID da Conexão e cole-a no arquivo Resoluções no lugar de <Fabric Connection ID>.

O arquivo de resoluções deve ser semelhante a este (seu value será diferente):

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

Enquanto estiver nisso, você pode adicionar um comentário à sua resolução desta maneira:

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

O cmdlet Import-FabricResolutions

Você pode importar esse arquivo de resoluções para verificar o que ele faz.

No PowerShell, execute o comando:

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

Você deve ver:

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

Esse é outro objeto de progresso de atualização, mas agora o campo resolutions está preenchido.

Você pode executar Import-FabricResolutions em qualquer ponto da cadeia de comandos antesExport-FabricResources. As resoluções serão encaminhadas para etapas posteriores.

Exportar o fluxo de trabalho do Fabric (tentativa 2)

Agora que temos um arquivo de resoluções, podemos tentar a exportação novamente depois de adicionar a Import-FabricResolutions etapa.

Atualize o comando adicionando Import-FabricResolutions entreConvert: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

Execute o comando no PowerShell.

Desta vez, funciona! Novamente, a seção exportedFabricResources mostra seu novo pipeline e sua ID.

Agora abra o workspace do Fabric no Fabric UX. Atualize a página e você verá o pipeline1 na lista. Abra-o e você encontrará exatamente o que espera!

Próximas etapas

Agora que você atualizou com êxito dois pipelines, pode usar o que aprendeu para atualizar mais pipelines.

Para obter mais informações sobre os tipos de atividades e conjuntos de dados com suporte, consulte a funcionalidade com suporte.
Para obter mais informações sobre como criar o arquivo de resoluções para diferentes tipos de pipelines, confira como adicionar conexões ao arquivo de resoluções.
Para obter etapas gerais sobre como executar essa migração usando o PowerShell, consulte: Migrar pipelines do Azure Data Factory para o Fabric usando o PowerShell.

Comentários

Esta página foi útil?

Last updated on 2025-09-22