Quickstart: Criar uma Azure Data Factory usando PowerShell

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este quickstart descreve como usar o PowerShell para criar uma Azure Data Factory. O pipeline que você cria nesta fábrica de dados copia dados de uma pasta para outra num armazenamento de blobs do Azure. Para um tutorial sobre como transformar dados usando Azure Data Factory, veja Tutorial: Transformar dados usando Spark.

Pré-requisitos

subscrição do Azure

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

Azure roles

Para criar as instâncias do Data Factory, a conta de utilizador que usa para iniciar sessão no Azure deve ser membro da função contribuidor ou proprietário, ou administrador da subscrição do Azure. Para ver as permissões que tem na subscrição, vá ao portal Azure, selecione o seu nome de utilizador no canto superior direito, selecione "... Ícone " para mais opções, e depois seleciona 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 filhos no portal Azure, deve pertencer ao papel Data Factory Contributor ao nível do grupo de recursos ou superior.
• Para criar e gerir recursos filhos com o PowerShell ou o SDK, a função contribuidor ao nível de recurso 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, consulte os seguintes artigos:

• Função de Contribuidor do Data Factory
• Papéis e permissões para Azure Data Factory

conta de armazenamento do Azure

Você utiliza uma conta Armazenamento do Azure de uso geral (especificamente armazenamento Blob) como armazenamento de dados de origem e destino neste guia introdutório. Se 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

Precisas do nome da tua conta do Armazenamento do Azure para esta introdução rápida. O procedimento a seguir fornece etapas para obter o nome da sua conta de armazenamento:

1. Num navegador web, vai ao portal Azure e inicia sessão usando o teu nome de utilizador e palavra-passe Azure.
2. No menu do portal Azure, selecione Todos os serviços, depois selecione Storage>Contas de Armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento em qualquer página.
3. Na página Contas de armazenamento, filtre a sua conta de armazenamento (se necessário) e selecione a 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, crias um contentor de blob chamado adftutorial no armazenamento de Azure Blob.

1. Na página da conta de armazenamento, selecione Visão geral>de contêineres.

2. Na barra de ferramentas da página <Nome da conta> - Contentores, selecione Contentor.

3. Na caixa de diálogo Novo contentor, introduza adftutorial para o nome e selecione OK. A página <Nome da conta> - Contentores é atualizada para incluir adftutorial na lista de contentores.

   

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.) Depois regresse ao portal do Azure e siga estes passos:

1. Na página <Nome da conta> - Containeres onde estava, selecione adftutorial na lista atualizada de containeres.

   1. Se fechaste a janela ou fores a outra página, inicia sessão no portal Azure novamente.
   2. No menu do portal Azure, selecione Todos os serviços, depois selecione Storage>Contas 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.

2. Na barra de ferramentas da página do contêiner adftutorial , selecione Carregar.

3. Na página Carregar blob, selecione a caixa Arquivos e, em seguida, procure e selecione o arquivo emp.txt.

4. Expanda o título Avançado . A página agora é exibida como mostrado:

   

5. Na caixa Carregar para a pasta, insira input.

6. Selecione o botão Carregar. Deverá ver o ficheiro emp.txt e o estado do carregamento na lista.

7. Selecione o ícone Fechar (um X) para fechar a página do Carregamento de blobs.

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

Azure PowerShell

Instale os módulos Azure PowerShell mais recentes seguindo as instruções em Como instalar e configurar Azure PowerShell.

Iniciar sessão no PowerShell

1. Inicie o PowerShell em sua máquina. Mantenha o PowerShell aberto até o final deste início rápido. Se você fechar e reabrir, precisará executar esses comandos novamente.

2. Execute o seguinte comando e introduza o mesmo nome de utilizador e palavra-passe do Azure que usa para iniciar sessão no portal Azure:

   Connect-AzAccount
   

3. Execute o comando seguinte para ver todas as subscrições desta conta:

   Get-AzSubscription
   

4. Se vir várias subscrições associadas à sua conta, execute o seguinte comando para selecionar a subscrição com a qual pretende trabalhar. Substitua SubscriptionId pelo ID da sua subscrição Azure:

   Select-AzSubscription -SubscriptionId "<SubscriptionId>"
   

Criar uma fábrica de dados

1. 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 Azure entre aspas duplas e depois execute o comando. Por exemplo: "ADFQuickStartRG".

   $resourceGroupName = "ADFQuickStartRG";
   

   Se o grupo de recursos já existir, é possível que não queira substituí-lo. Atribua um valor diferente à $ResourceGroupName variável e execute o comando novamente

2. Para criar o grupo de recursos do Azure, execute o seguinte comando:

   $ResGrp = New-AzResourceGroup $resourceGroupName -location 'East US'
   

   Se o grupo de recursos já existir, é possível que não queira substituí-lo. Atribua $ResourceGroupName um valor diferente à variável e execute o comando novamente.

3. Defina uma variável para o nome da fábrica de dados.

   Importante

   Atualize o nome da fábrica de dados para ser globalmente exclusivo. Por exemplo, ADFTutorialFactorySP1127.

   $dataFactoryName = "ADFQuickStartFactory";
   

4. 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
   

Observe os seguintes pontos:

• O nome da Azure Data Factory deve ser globalmente único. 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 usa para iniciar sessão no Azure deve ser membro de funções contributor ou proprietário, ou um administrador da subscrição Azure.

• Para uma lista das regiões do Azure em que o Data Factory está disponível atualmente, selecione as regiões que lhe interessam na página seguinte e depois expanda Analytics para localizar Data Factory: Produtos disponíveis por região. Os armazenamentos de dados (Armazenamento do Azure, Base de Dados SQL do Azure, etc.) e os computadores (HDInsight, etc.) usados pela data factory podem estar noutras regiões.

Criar um serviço vinculado

Crie serviços vinculados em uma fábrica de dados para vincular seus armazenamentos de dados e serviços de computação ao data factory. Neste início rápido, crie um serviço ligado ao Armazenamento do Azure que é usado tanto como armazenamento de origem como de destino. O serviço vinculado tem as informações de conexão que o serviço Data Factory usa em tempo de execução para se conectar a ele.

1. Crie um arquivo JSON chamado AzureStorageLinkedService.json na pasta C:\ADFv2QuickStartPSH com o seguinte conteúdo: (Crie a pasta ADFv2QuickStartPSH se ela ainda não existir.).

   Importante

   Substitua <NomeConta> e <ChaveConta> pelo nome e chave da sua conta de armazenamento 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 usar o Bloco de Notas, selecione Todos os ficheiros para o tipo de ficheiro na caixa de diálogo Guardar como. Caso contrário, ele pode adicionar .txt extensão ao arquivo. 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 .txt extensão, uma vez que a opção Ocultar extensões para tipos de ficheiros conhecidos está definida por predefinição. Remova a .txt extensão antes de prosseguir para a próxima etapa.

2. No PowerShell, mude para a pasta ADFv2QuickStartPSH.

   Set-Location 'C:\ADFv2QuickStartPSH'
   

3. 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"
   

   Aqui está o exemplo de resultados:

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

Criar conjuntos de dados

Neste procedimento, você cria dois conjuntos de dados: InputDataset e OutputDataset. Esses conjuntos de dados são do tipo binário. Referem-se ao serviço vinculado do Armazenamento do Azure que criou na seção anterior. O conjunto de dados de entrada representa os dados de origem na pasta de inserção. Na definição do conjunto de dados de entrada, especifique o contêiner de blob (adftutorial), a pasta (entrada) e o arquivo (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, especifique o contêiner de blob (adftutorial), a pasta (saída) e o arquivo para o qual os dados são copiados.

1. 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"
               }
           }
       }
   }
   

2. 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"
   

   Aqui está a saída de exemplo:

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

3. 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"
               }
           }
       }
   }
   

4. Execute o cmdlet Set-AzDataFactoryV2Dataset para criar o OutDataset.

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

   Aqui está a saída de exemplo:

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

Criar uma canalização

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 arquivo especificado nas configurações do conjunto de dados de entrada para o arquivo especificado nas configurações do conjunto de dados de saída.

1. Crie um arquivo JSON chamado 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": []
       }
   }
   

2. 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, execute uma execução de pipeline.

Execute o cmdlet Invoke-AzDataFactoryV2Pipeline para criar uma execução de pipeline. O cmdlet retorna o identificador 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.

1. Execute o seguinte script do PowerShell para verificar continuamente o status de execução do pipeline até que ele termine de copiar os dados. Copie/cole o seguinte script na janela do PowerShell e pressione 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
   }
   

   Aqui está a saída de exemplo da execução do 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           : 
   

2. 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"
   

3. Confirme se você vê a saída semelhante à seguinte saída de exemplo do resultado da execução da 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"
   

Analisar os recursos implementados

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

1. No portal Azure, na página do contentor adftutorial, selecione Refresh para ver a pasta de saída.

   

2. Selecione saída na lista de pastas.

3. Confirme se o ficheiro emp.txt foi copiado para a pasta de saída.

   

Limpeza de recursos

Pode limpar os recursos que criou no Guia de Introdução de duas formas. Podes eliminar o grupo de recursos Azure, que inclui todos os recursos do 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

Se você quiser excluir apenas o data factory, não todo o grupo de recursos, execute o seguinte comando:

Remove-AzDataFactoryV2 -Name $dataFactoryName -ResourceGroupName $resourceGroupName

Conteúdo relacionado

O pipeline neste exemplo copia dados de um local para outro num armazenamento de blob do Azure. Leia os tutoriais para saber como utilizar o Data Factory em mais cenários.