Guia de início rápido: criar um Azure Data Factory usando o PowerShell

Artigo
12/09/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!

Este guia de início rápido descreve como usar o PowerShell para criar um Azure Data Factory. O pipeline que criar nesta fábrica de dados copia dados de uma pasta para outra pasta num armazenamento de blobs do Azure. Para ter acesso a um tutorial sobre como transformar dados com o Azure Data Factory, veja Tutorial: Transformar dados com o Spark.

Nota

Este artigo não disponibiliza uma introdução detalhada do serviço Data Factory. Para obter uma introdução ao serviço Azure Data Factory, veja Introdução ao Azure Data Factory.

Pré-requisitos

Subscrição do Azure

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Funções do Azure

Para criar instâncias do Data Factory, a conta de utilizador que utiliza para iniciar sessão no Azure tem de ser membro das funções contribuidor ou proprietário ou administrador da subscrição do Azure. Para ver as permissões que tem na subscrição, aceda ao portal do Azure, selecione o seu nome de utilizador no canto superior direito, selecione o ícone "..." para obter mais opções e, em seguida, selecione As minhas permissões. Se tiver acesso a várias subscrições, selecione a subscrição apropriada.

Para criar e gerir recursos subordinados do Data Factory - incluindo conjuntos de dados, serviços ligados, pipelines, acionadores e runtimes de integração - os requisitos seguintes são aplicáveis:

Para criar e gerir recursos subordinados no portal do Azure, tem de pertencer à função Contribuidor do Data Factory ao nível do grupo de recursos ou superior.
Para criar e gerir recursos subordinados com o PowerShell ou o SDK, a função contribuidor ao nível do grupo de recursos ou superior é suficiente.

Para obter instruções de exemplo sobre como adicionar um utilizador a uma função, veja o artigo Adicionar funções.

Para obter mais informações, veja os artigos seguintes:

Conta de armazenamento do Azure

Você usa uma conta de Armazenamento do Azure de uso geral (especificamente armazenamento de Blob) como armazenamentos de dados de origem e destino neste início rápido. Se você não tiver uma conta de Armazenamento do Azure de uso geral, consulte Criar uma conta de armazenamento para criar uma.

Obter o nome da conta de armazenamento

Você precisa do nome da sua conta de Armazenamento do Azure para este início rápido. O procedimento a seguir fornece etapas para obter o nome da sua conta de armazenamento:

Em um navegador da Web, vá para o portal do Azure e entre usando seu nome de usuário e senha do Azure.
No menu do portal do Azure, selecione Todos os serviços e, em seguida, selecione >Contas de armazenamento de armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento em qualquer página.
Na página Contas de armazenamento, filtre sua conta de armazenamento (se necessário) e selecione sua conta de armazenamento.

Você também pode pesquisar e selecionar Contas de armazenamento em qualquer página.

Criar um contentor de blobs

Nesta secção, vai criar um contentor de blobs com o nome adftutorial no armazenamento de Blobs do Azure.

Na página da conta de armazenamento, selecione Visão geral>de contêineres.
Na barra de ferramentas da página Nome da <conta - >Contêineres, selecione Contêiner.
Na caixa de diálogo Novo contentor, introduza adftutorial para o nome e selecione OK. A página Nome da conta - >Contêineres é atualizada para incluir adftutorial na lista de contêineres.<

Adicionar uma pasta de entrada e um arquivo para o contêiner de blob

Nesta seção, você cria uma pasta chamada input no contêiner criado e, em seguida, carrega um arquivo de exemplo para a pasta de entrada. Antes de começar, abra um editor de texto, como o Bloco de Notas, e crie um arquivo chamado emp.txt com o seguinte conteúdo:

John, Doe
Jane, Doe

Salve o arquivo na pasta C:\ADFv2QuickStartPSH . (Se a pasta ainda não existir, crie-a.) Em seguida, retorne ao portal do Azure e siga estas etapas:

Na página Nome da <conta> - Contêineres de onde você parou, selecione adftutorial na lista atualizada de contêineres.
1. Se você fechou a janela ou foi para outra página, entre no portal do Azure novamente.
2. No menu do portal do Azure, selecione Todos os serviços e, em seguida, selecione >Contas de armazenamento de armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento em qualquer página.
3. Selecione sua conta de armazenamento e, em seguida, selecione Containers>adftutorial.
Na barra de ferramentas da página do contêiner adftutorial , selecione Carregar.
Na página Carregar blob, selecione a caixa Arquivos e, em seguida, procure e selecione o arquivo emp.txt.
Expanda o título Avançado . A página agora é exibida como mostrado:
Na caixa Carregar para pasta, insira a entrada.
Selecione o botão Carregar. Deverá ver o ficheiro emp.txt e o estado do carregamento na lista.
Selecione o ícone Fechar (um X) para fechar a página Carregar blob .

Mantenha a página do contêiner adftutorial aberta. Vai utilizá-la para verificar a saída no final deste início rápido.

Azure PowerShell

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Instale os módulos do Azure PowerShell mais recentes ao seguir as instruções em How to install and configure Azure PowerShell (Como instalar e configurar o Azure PowerShell).

Aviso

Se você não usar as versões mais recentes do PowerShell e do módulo Data Factory, poderá encontrar erros de desserialização ao executar os comandos.

Iniciar sessão no PowerShell

Inicie o PowerShell no seu computador. Mantenha o PowerShell aberto até ao fim deste início rápido. Se o fechar e reabrir, terá de executar os comandos novamente.
Execute o comando seguinte e introduza o mesmo nome de utilizador e a mesma palavra-passe do Azure que utiliza para iniciar sessão no portal do Azure:
```
Connect-AzAccount
```
Execute o comando seguinte para ver todas as subscrições desta conta:
```
Get-AzSubscription
```
Se vir várias subscrições associadas à sua conta, execute o comando seguinte selecionar aquela com que pretende trabalhar. Substitua SubscriptionId pelo ID da sua subscrição do Azure:
```
Select-AzSubscription -SubscriptionId "<SubscriptionId>"
```

Criar uma fábrica de dados

Defina uma variável para o nome do grupo de recursos que vai utilizar nos comandos do PowerShell mais tarde. Copie o texto do comando seguinte para o PowerShell, especifique um nome para o Grupo de recursos do Azure com aspas duplas e execute o comando. Por exemplo: "ADFQuickStartRG".
```
$resourceGroupName = "ADFQuickStartRG";
```
Se o grupo de recursos já existir, pode não substituí-lo. Atribua outro valor à variável $ResourceGroupName e execute novamente o comando
Para criar o grupo de recursos do Azure, execute o comando abaixo:
```
$ResGrp = New-AzResourceGroup $resourceGroupName -location 'East US'
```
Se o grupo de recursos já existir, pode não substituí-lo. Atribua outro valor à variável $ResourceGroupName e execute novamente o comando.
Defina uma variável para o nome da fábrica de dados.

Importante

Atualize o nome da fábrica de dados para que seja globalmente exclusivo. Por exemplo, ADFTutorialFactorySP1127.
```
$dataFactoryName = "ADFQuickStartFactory";
```
Para criar o data factory, execute o seguinte cmdlet Set-AzDataFactoryV2 , usando a propriedade Location e ResourceGroupName da variável $ResGrp:
```
$DataFactory = Set-AzDataFactoryV2 -ResourceGroupName $ResGrp.ResourceGroupName `
    -Location $ResGrp.Location -Name $dataFactoryName
```

Tenha em atenção os seguintes pontos:

O nome do Azure Data Factory deve ser globalmente exclusivo. Se receber o erro seguinte, altere o nome e tente novamente.

The specified Data Factory name 'ADFv2QuickStartDataFactory' is already in use. Data Factory names must be globally unique.

Para criar instâncias do Data Factory, a conta de utilizador que utiliza para iniciar sessão no Azure tem de ser um membro das funções contribuidor ou proprietário, ou um administrador da subscrição do Azure.
Para obter uma lista de regiões do Azure em que o Data Factory está atualmente disponível, selecione as regiões que lhe interessam na página seguinte e, em seguida, expanda Analytics para localizar Data Factory: Produtos disponíveis por região. Os arquivos de dados (Armazenamento do Azure, Base de Dados SQL do Azure, etc.) e as computações (HDInsight, etc.) utilizados pela fábrica de dados podem estar noutras regiões.

Criar um serviço ligado

Crie os serviços ligados numa fábrica de dados para ligar os seus arquivos de dados e serviços de computação a essa fábrica de dados. Neste início rápido, vai criar um serviço ligado do Armazenamento do Azure que será utilizado não só como arquivo de origem como arquivo sink. O serviço ligado tem as informações de ligação utilizadas pelo serviço Data Factory em runtime para se ligar ao mesmo.

Gorjeta

Neste início rápido, você usa a chave de conta como o tipo de autenticação para seu armazenamento de dados, mas pode escolher outros métodos de autenticação suportados: URI SAS, Entidade de Serviço e Identidade Gerenciada, se necessário. Consulte as seções correspondentes neste artigo para obter detalhes. Para armazenar segredos para armazenamentos de dados com segurança, também é recomendável usar um Cofre de Chaves do Azure. Consulte este artigo para obter ilustrações detalhadas.

Crie um ficheiro JSON com o nome AzureStorageLinkedService.json na pasta C:\ADFv2QuickStartPSH com o seguinte conteúdo: (crie a pasta ADFv2QuickStartPSH, caso ainda não exista.).

Importante

Substitua <accountName> e <accountKey> pelo nome e chave da sua conta de armazenamento do Azure antes de guardar o ficheiro.
```
{
    "name": "AzureStorageLinkedService",
    "properties": {
        "annotations": [],
        "type": "AzureBlobStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net"
        }
    }
}
```
Se estiver a utilizar o Bloco de Notas, selecione Todos os Ficheiros no campo Guardar com o tipo, na caixa de diálogo Guardar como. Caso contrário, pode adicionar a extensão .txt ao ficheiro. Por exemplo, AzureStorageLinkedService.json.txt. Se criar o ficheiro no Explorador de Ficheiros antes de o abrir no Bloco de Notas, poderá não ver a extensão .txt, uma vez que a opção Ocultar extensões para tipos de ficheiros conhecidos está definida por predefinição. Antes de avançar para o próximo passo, remova a extensão .txt.
No PowerShell, mude para a pasta ADFv2QuickStartPSH.
```
Set-Location 'C:\ADFv2QuickStartPSH'
```

Execute o cmdlet Set-AzDataFactoryV2LinkedService para criar o serviço vinculado: AzureStorageLinkedService.

Set-AzDataFactoryV2LinkedService -DataFactoryName $DataFactory.DataFactoryName `
    -ResourceGroupName $ResGrp.ResourceGroupName -Name "AzureStorageLinkedService" `
    -DefinitionFile ".\AzureStorageLinkedService.json"

Segue-se o resultado do exemplo:

LinkedServiceName : AzureStorageLinkedService
ResourceGroupName : <resourceGroupName>
DataFactoryName   : <dataFactoryName>
Properties        : Microsoft.Azure.Management.DataFactory.Models.AzureBlobStorageLinkedService

Criar conjuntos de dados

Neste procedimento, vai criar dois conjuntos de dados, InputDataset e OutputDataset. Esses conjuntos de dados são do tipo binário. Dizem respeito ao serviço ligado do Armazenamento do Azure que criou na secção anterior. O conjunto de dados de entrada representa a origem de dados na pasta de entrada. Na definição do conjunto de dados de entrada, vai especificar o contentor de blobs (adftutorial), a pasta (input) e o ficheiro (emp.txt) que contêm os dados de origem. O conjunto de dados de saída representa os dados que são copiados para o destino. Na definição do conjunto de dados de saída, vai especificar o contentor de blobs (adftutorial), a pasta (output) e o ficheiro para o qual os dados vão ser copiados.

Crie um arquivo JSON chamado InputDataset.json na pasta C:\ADFv2QuickStartPSH , com o seguinte conteúdo:

{
    "name": "InputDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "annotations": [],
        "type": "Binary",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "fileName": "emp.txt",
                "folderPath": "input",
                "container": "adftutorial"
            }
        }
    }
}

Para criar o conjunto de dados: InputDataset, execute o cmdlet Set-AzDataFactoryV2Dataset.

Set-AzDataFactoryV2Dataset -DataFactoryName $DataFactory.DataFactoryName `
    -ResourceGroupName $ResGrp.ResourceGroupName -Name "InputDataset" `
    -DefinitionFile ".\InputDataset.json"

Segue-se o resultado do exemplo:

DatasetName       : InputDataset
ResourceGroupName : <resourceGroupname>
DataFactoryName   : <dataFactoryName>
Structure         :
Properties        : Microsoft.Azure.Management.DataFactory.Models.BinaryDataset

Repita os passos para criar o conjunto de dados de saída. Crie um arquivo JSON chamado OutputDataset.json na pasta C:\ADFv2QuickStartPSH , com o seguinte conteúdo:

{
    "name": "OutputDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "annotations": [],
        "type": "Binary",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "folderPath": "output",
                "container": "adftutorial"
            }
        }
    }
}

Execute o cmdlet Set-AzDataFactoryV2Dataset para criar o OutDataset.

Set-AzDataFactoryV2Dataset -DataFactoryName $DataFactory.DataFactoryName `
    -ResourceGroupName $ResGrp.ResourceGroupName -Name "OutputDataset" `
    -DefinitionFile ".\OutputDataset.json"

Segue-se o resultado do exemplo:

DatasetName       : OutputDataset
ResourceGroupName : <resourceGroupname>
DataFactoryName   : <dataFactoryName>
Structure         :
Properties        : Microsoft.Azure.Management.DataFactory.Models.BinaryDataset

Criar um pipeline

Neste procedimento, você cria um pipeline com uma atividade de cópia que usa os conjuntos de dados de entrada e saída. A atividade de cópia copia dados do ficheiro especificado nas definições do conjunto de dados de entrada para o ficheiro especificado nas definições do conjunto de dados de saída.

Crie um ficheiro JSON com o nome Adfv2QuickStartPipeline.json na pasta C:\ADFv2QuickStartPSH com o seguinte conteúdo:

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "dependsOn": [],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [],
                "typeProperties": {
                    "source": {
                        "type": "BinarySource",
                        "storeSettings": {
                            "type": "AzureBlobStorageReadSettings",
                            "recursive": true
                        }
                    },
                    "sink": {
                        "type": "BinarySink",
                        "storeSettings": {
                            "type": "AzureBlobStorageWriteSettings"
                        }
                    },
                    "enableStaging": false
                },
                "inputs": [
                    {
                        "referenceName": "InputDataset",
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "OutputDataset",
                        "type": "DatasetReference"
                    }
                ]
            }
        ],
        "annotations": []
    }
}

Para criar o pipeline: Adfv2QuickStartPipeline, execute o cmdlet Set-AzDataFactoryV2Pipeline.

$DFPipeLine = Set-AzDataFactoryV2Pipeline `
    -DataFactoryName $DataFactory.DataFactoryName `
    -ResourceGroupName $ResGrp.ResourceGroupName `
    -Name "Adfv2QuickStartPipeline" `
    -DefinitionFile ".\Adfv2QuickStartPipeline.json"

Criar uma execução de pipeline

Nesta etapa, você cria uma execução de pipeline.

Execute o cmdlet Invoke-AzDataFactoryV2Pipeline para criar uma execução de pipeline. O cmdlet devolve o ID de execução do pipeline para monitorização futura.

$RunId = Invoke-AzDataFactoryV2Pipeline `
  -DataFactoryName $DataFactory.DataFactoryName `
  -ResourceGroupName $ResGrp.ResourceGroupName `
  -PipelineName $DFPipeLine.Name

Monitorizar a execução do pipeline.

Execute o seguinte script do PowerShell para verificar continuamente o estado de execução do pipeline até que este termine de copiar os dados. Copie/cole o seguinte script na janela do PowerShell e prima ENTER.

while ($True) {
    $Run = Get-AzDataFactoryV2PipelineRun `
        -ResourceGroupName $ResGrp.ResourceGroupName `
        -DataFactoryName $DataFactory.DataFactoryName `
        -PipelineRunId $RunId

    if ($Run) {
        if ( ($Run.Status -ne "InProgress") -and ($Run.Status -ne "Queued") ) {
            Write-Output ("Pipeline run finished. The status is: " +  $Run.Status)
            $Run
            break
        }
        Write-Output ("Pipeline is running...status: " + $Run.Status)
    }

    Start-Sleep -Seconds 10
}

Eis a saída de exemplo da execução de pipeline:

Pipeline is running...status: InProgress
Pipeline run finished. The status is:  Succeeded

ResourceGroupName : ADFQuickStartRG
DataFactoryName   : ADFQuickStartFactory
RunId             : 00000000-0000-0000-0000-0000000000000
PipelineName      : Adfv2QuickStartPipeline
LastUpdated       : 8/27/2019 7:23:07 AM
Parameters        : {}
RunStart          : 8/27/2019 7:22:56 AM
RunEnd            : 8/27/2019 7:23:07 AM
DurationInMs      : 11324
Status            : Succeeded
Message           :

Execute o script seguinte para obter os detalhes da execução da atividade de cópia, como, por exemplo, o tamanho dos dados lidos/escritos.

Write-Output "Activity run details:"
$Result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $DataFactory.DataFactoryName -ResourceGroupName $ResGrp.ResourceGroupName -PipelineRunId $RunId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)
$Result

Write-Output "Activity 'Output' section:"
$Result.Output -join "`r`n"

Write-Output "Activity 'Error' section:"
$Result.Error -join "`r`n"

Confirme se vê uma saída semelhante à seguinte saída de exemplo de resultado da execução de atividade:

ResourceGroupName : ADFQuickStartRG
DataFactoryName   : ADFQuickStartFactory
ActivityRunId     : 00000000-0000-0000-0000-000000000000
ActivityName      : CopyFromBlobToBlob
PipelineRunId     : 00000000-0000-0000-0000-000000000000
PipelineName      : Adfv2QuickStartPipeline
Input             : {source, sink, enableStaging}
Output            : {dataRead, dataWritten, filesRead, filesWritten...}
LinkedServiceName :
ActivityRunStart  : 8/27/2019 7:22:58 AM
ActivityRunEnd    : 8/27/2019 7:23:05 AM
DurationInMs      : 6828
Status            : Succeeded
Error             : {errorCode, message, failureType, target}

Activity 'Output' section:
"dataRead": 20
"dataWritten": 20
"filesRead": 1
"filesWritten": 1
"sourcePeakConnections": 1
"sinkPeakConnections": 1
"copyDuration": 4
"throughput": 0.01
"errors": []
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (Central US)"
"usedDataIntegrationUnits": 4
"usedParallelCopies": 1
"executionDetails": [
  {
    "source": {
      "type": "AzureBlobStorage"
    },
    "sink": {
      "type": "AzureBlobStorage"
    },
    "status": "Succeeded",
    "start": "2019-08-27T07:22:59.1045645Z",
    "duration": 4,
    "usedDataIntegrationUnits": 4,
    "usedParallelCopies": 1,
    "detailedDurations": {
      "queuingDuration": 3,
      "transferDuration": 1
    }
  }
]

Activity 'Error' section:
"errorCode": ""
"message": ""
"failureType": ""
"target": "CopyFromBlobToBlob"

Rever os recursos implementados

O pipeline cria automaticamente a pasta de saída no contentor de blobs adftutorial. Em seguida, copia o ficheiro emp.txt da pasta de entrada para a pasta de saída.

No portal do Azure, na página de contêiner adftutorial , selecione Atualizar para ver a pasta de saída.
Selecione a saída na lista de pastas.
Confirme se o ficheiro emp.txt foi copiado para a pasta de saída.

Clean up resources (Limpar recursos)

Pode limpar os recursos que criou no Guia de Introdução de duas formas. Pode eliminar o grupo de recursos do Azure, que inclui todos os recursos no grupo de recursos. Se quiser manter os outros recursos intactos, elimine apenas a fábrica de dados que criou neste tutorial.

A eliminação de um grupo de recursos dita a eliminação de todos os recursos, incluindo as fábricas de dados nele incluídas. Execute o seguinte comando para eliminar todo o grupo de recursos:

Remove-AzResourceGroup -ResourceGroupName $resourcegroupname

Nota

Abandonar um grupo de recursos pode levar algum tempo. Seja paciente durante o processo

Se quiser eliminar apenas a fábrica de dados, e não o grupo de recursos completo, execute o seguinte comando:

Remove-AzDataFactoryV2 -Name $dataFactoryName -ResourceGroupName $resourceGroupName

O pipeline neste exemplo copia dados de uma localização para outra localização num armazenamento de blobs do Azure. Leia os tutoriais para saber como utilizar o Data Factory em mais cenários.

Guia de início rápido: criar um Azure Data Factory usando o PowerShell

Pré-requisitos

Subscrição do Azure

Funções do Azure

Conta de armazenamento do Azure

Obter o nome da conta de armazenamento

Criar um contentor de blobs

Adicionar uma pasta de entrada e um arquivo para o contêiner de blob

Azure PowerShell

Iniciar sessão no PowerShell

Criar uma fábrica de dados

Criar um serviço ligado

Criar conjuntos de dados

Criar um pipeline

Criar uma execução de pipeline

Monitorizar a execução do pipeline.

Rever os recursos implementados

Clean up resources (Limpar recursos)

Conteúdos relacionados

Recursos adicionais