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

Você pode migrar seus pipelines do Azure Data Factory (ADF) para o Microsoft Fabric usando o módulo do PowerShell Microsoft.FabricPipelineUpgrade. 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 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 lidar com alertas

Pré-requisitos

Para começar, certifique-se de ter os seguintes pré-requisitos:

Locatário : Seu espaço de trabalho ADF e Fabric deve estar no mesmo locatário do Microsoft Entra ID.
Fabric: uma conta de inquilino com uma assinatura ativa do Fabric - Crie uma conta grátis.
Recomendações para espaço de trabalho Fabric (opcional): recomendamos o uso de um novo espaço de trabalho Fabric na mesma região do seu ADF para obter o melhor desempenho em atualizações.
Permissões: Acesso de leitura ao espaço de trabalho do ADF e aos itens que irá migrar e direitos de Colaborador ou superiores no espaço de trabalho do Fabric para o qual irá escrever.
Rede e autenticação: certifique-se de que pode iniciar sessão no Azure e no Fabric a partir da sua máquina (interativa ou entidade de serviço).

Prepare-se para atualizar

Antes de começar a atualizar pipelines, verifique se seu 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 no seu computador.

Baixar PowerShell

Instalar e importar o módulo FabricPipelineUpgrade

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

Na janela elevada do PowerShell, instale o módulo da Galeria do PowerShell:

Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck

Importe o módulo para a 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ê vai usá-lo para a atualização.

A sua primeira atualização

Vamos criar um pipeline de exemplo e atualizá-lo para o Fabric como um passo a passo do processo.

Criar um pipeline 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 sua janela do PowerShell, substitua os valores por <your subscription ID> e execute estes comandos no PowerShell para iniciar sessão e definir a sua subscrição.
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```

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

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

Na janela do PowerShell, substitua os valores de <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
```
Sugestão

Para Data Factories com vários pipelines, você pode importar todos os pipelines de uma só vez, deixando de fora o -PipelineName parâmetro.

Este comando carrega o pipeline e os artefatos associados do seu Azure Data Factory e cria o JSON para o primeiro "Progresso da 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 significam estes campos

state: Mostra o status. Se disser Sucesso, você é bom.
alertas: lista quaisquer problemas ou informações extras.
resultado: Mostra o resultado. Aqui, importedResources lista os artefatos do ADF.
resoluções: Usado para mapear os Serviços Vinculados do ADF para Conexões de Malha (seção posterior).

Converta seu pipeline do ADF em um pipeline de malha

Na janela do PowerShell, pegue o comando Import-AdfFactory que você acabou de executar e adicione | e, em seguida, o comando ConvertTo-FabricResources até o 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 da Atualização padrão, mas agora o campo de resultado inclui exportableFabricResources. Isso é esperado; você está preparando os recursos do Fabric para exportação.

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

Se você parar por aqui, esse comando age 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.

Recolher informações do seu espaço de trabalho do Fabric

Antes de exportar o seu pipeline do Fabric, você precisará de alguns detalhes da sua área de trabalho do Fabric. Abra um arquivo de texto em branco para copiar os valores de que você precisará mais tarde.

Abra o Microsoft Fabric UX e navegue até o espaço de trabalho do Data Factory.
Encontre o ID do espaço de trabalho e copie-o para o arquivo de texto.
Execute este comando do PowerShell para obter o seu Fabric Access Token e armazená-lo para a sua sessão:
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
Sugestão

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 de tecido

Combine todos os detalhes reunidos 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 secção exportedFabricResources mostra o seu novo pipeline e o seu ID. Agora, abra seu espaço de trabalho do Fabric na UX do Fabric. Atualize a página e você verá pipeline1 na lista. Abra-o e encontrará exatamente o que espera!

A sua segunda melhoria: copie alguns dados

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

Conjuntos de dados e Serviços Ligados
Resolutions

Atualmente, o Atualizador de Pipeline de Fabric suporta um conjunto limitado de datasets; por isso, utilizaremos conexões de Azure Blob Storage e datasets JSON. Vamos mergulhar.

No ADF Studio, crie um pipeline que copie 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 que desejar.

Execute o mesmo comando What-If de antes para importar seu 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 parece semelhante ao anterior, mas agora há mais detalhes, incluindo dois exportableFabricResources:

Um para conexão
Um para um gasoduto

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 consiste em 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 fazem estas etapas?

Estes resolve passos são instruções para você mapear os seus serviços vinculados do ADF para a origem e o destino das atividades com o ID de conexão do Fabric correspondente.

Por que isso acontece?

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

Agora vamos exportar o pipeline de fabric (tentativa 1)

Se seus tokens de acesso expiraram, 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 o ID de uma conexão às suas resoluções".

O que correu mal?

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

Criar um ficheiro de resoluções

Primeiro, crie um arquivo de Resoluções. Você pode nomeá-lo qualquer coisa e salvá-lo onde quiser em sua máquina (desde que o PowerShell possa acessá-lo), mas este tutorial usa D:\Resolutions.json.
Inicialize o arquivo com:
```
[
]
```
Em seguida, adicione sua resolução ausente a partir da dica que seu 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 descobrir isso <Fabric Connection ID>. Para fazer isso, vá para o espaço de trabalho do Fabric no Fabric UX, selecione o ícone de engrenagem no canto superior direito e, em seguida, selecione Gerenciar conexões e gateways.
Se a ligação ainda não existir no Fabric, crie uma nova ligação à mesma conta de Armazenamento de Blob do Azure que o seu pipeline do ADF utiliza. Você pode nomeá-lo qualquer coisa, mas este tutorial usa "myblob".
Depois de criar a conexão, passe o mouse sobre o botão de reticências ao lado do nome da conexão para mostrar o menu.
Selecione Configurações no menu e, em seguida, copie a ID de conexão e cole-a no arquivo de Resoluções no lugar de <Fabric Connection ID>.

Seu arquivo de resoluções deve ter esta aparência (seu value será diferente):

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

Enquanto estiver nisso, podes adicionar um comentário à tua resolução como este:

[
   {
      "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, executar:

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

Você deve ver:

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

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

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

Exportar o Fabric Pipeline (tentativa 2)

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

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

Execute o comando no PowerShell.

Desta vez, funciona! Novamente, a seção exportedFabricResources mostra o seu novo pipeline, bem como o seu identificador (ID).

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

Próximos passos

Agora que atualizaste com êxito dois pipelines, podes usar o que aprendeste para atualizar mais pipelines.

Para obter mais informações sobre os tipos de atividades e conjuntos de dados suportados, consulte a funcionalidade suportada.
Para obter mais informações sobre como criar o arquivo de resoluções para diferentes tipos de pipelines, consulte 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.

Feedback

Esta página foi útil?

Last updated on 2025-09-22