Início Rápido: Criar um data factory e um pipeline usando o SDK do .NET
APLICA-SE A: Azure Data Factory Azure Synapse Analytics
Dica
Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!
Este guia de início rápido descreve como usar o SDK do .NET para criar um Azure Data Factory. O pipeline que você criar nesse data factory copia dados de uma pasta para outra em um Armazenamento de Blobs do Azure. Para obter um tutorial sobre como transformar dados usando o Azure Data Factory, confira Tutorial: Transformar dados usando o Spark.
Observação
Este artigo não fornece uma introdução detalhada do serviço Data Factory. Para obter uma introdução do serviço do Azure Data Factory, consulte Introdução ao Azure Data Factory.
Pré-requisitos
Assinatura do Azure
Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Funções do Azure
Para criar instâncias de Data Factory, a conta de usuário usada para entrar no Azure deve ser um membro das funções colaborador ou proprietário, ou um administrador da assinatura do Azure. Para exibir as permissões que você tem na assinatura, acesse o portal do Azure, selecione seu nome de usuário no canto superior direito e selecione o ícone “ ... ” para obter mais opções; em seguida, selecione Minhas permissões. Se tiver acesso a várias assinaturas, selecione a que for adequada.
Para criar e gerenciar recursos filho para o Data Factory – incluindo conjuntos de dados, serviços vinculados, pipelines, gatilhos e runtimes de integração –, os requisitos a seguir são aplicáveis:
- Para criar e gerenciar recursos filho no portal do Azure, você precisa pertencer à função Colaborador do Data Factory no nível do grupo de recursos ou superior.
- Para criar e gerenciar recursos filho com o PowerShell ou o SDK, a função de colaborador no nível do recurso ou superior é suficiente.
Para obter instruções de exemplo sobre como adicionar um usuário a uma função, confira o artigo Adicionar funções.
Para obter mais informações, confira os seguintes artigos:
Conta de Armazenamento do Azure
Use uma conta de Armazenamento do Azure de uso geral (especificamente o Armazenamento de Blobs) 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, confira Criar uma conta de armazenamento para criar uma.
Obter o nome da conta de armazenamento
Você precisará do nome da sua conta de Armazenamento do Azure para este início rápido. O procedimento a seguir fornece as 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, em seguida, selecione Armazenamento>Contas de armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento de qualquer página.
- Na página Contas de armazenamento, filtre pela sua conta de armazenamento (se necessário) e selecione a sua conta de armazenamento.
Você também pode pesquisar e selecionar Contas de armazenamento de qualquer página.
Criar um contêiner de blob
Nesta seção, você cria um contêiner de blobs chamado adftutorial no armazenamento de Blobs do Azure.
Na página da conta de armazenamento, selecione Visão geral>Contêineres.
Na barra de ferramentas da página <Nome da conta> - Contêineres, selecione Contêiner.
Na caixa de diálogo Novo contêiner, insira adftutorial como 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 ao contêiner de blob
Nesta seção, você pode adicionar uma pasta chamada entrada ao contêiner que acabou de criar e, em seguida, carregar um arquivo de exemplo na 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.) Então volte ao portal do Azure e siga estas etapas:
Na página <Nome da conta> - Contêineres em que você parou, selecione adftutorial na lista atualizada de contêineres.
- Se você fechou a janela ou foi para outra página, entre no portal do Azure novamente.
- No menu do portal do Azure, selecione Todos os serviços, em seguida, selecione Armazenamento>Contas de armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento de qualquer página.
- Selecione a sua conta de armazenamento e, em seguida, Contêineres>adftutorial.
Na barra de ferramentas da página de contêiner do adftutorial, selecione Carregar.
Na página Carregar blob, selecione a caixa Arquivos e, em seguida, navegue até o arquivo emp.txt e selecione-o.
Expanda o título Avançado. A página agora será exibida como mostrado:
Na caixa Carregar para a pasta, insira entrada.
Selecione o botão Carregar. O arquivo emp.txt e o status do carregamento devem estar na lista.
Selecione o ícone Fechar (um X) para fechar a página Carregar blob.
Mantenha a página do contêiner adftutorial aberta. Você a usa para verificar a saída no final do guia de início rápido.
Visual Studio
As instruções passo a passo neste artigo usam o Visual Studio 2019. Os procedimentos para Visual Studio 2013, 2015 ou 2017 são levemente diferentes.
Criar um aplicativo no Microsoft Entra ID
Nas seções em Instruções: usar o portal para criar um aplicativo do Microsoft Entra e uma entidade de serviço que possa acessar recursos, siga as instruções para executar estas tarefas:
- Em Criar um aplicativo do Microsoft Entra, crie um aplicativo que represente o aplicativo .NET que você está criando neste tutorial. Para a URL de logon, você pode fornecer uma URL fictícia, como mostrado no artigo (
https://contoso.org/exampleapp
). - Em Obter valores para entrar, obtenha a ID do aplicativo e a ID do locatário e anote esses valores que você usará posteriormente neste tutorial.
- Em Certificados e segredos, obtenha a chave de autenticação e anote esse valor que você usa posteriormente neste tutorial.
- Em Atribuir o aplicativo a uma função, atribua o aplicativo à função Colaborador no nível da assinatura para que o aplicativo possa criar os data factories na assinatura.
Criar um projeto do Visual Studio
Em seguida, crie um aplicativo de console do .NET em C# no Visual Studio:
- Inicie o Visual Studio.
- Na janela Iniciar, selecione Criar um novo projeto>Aplicativo de Console (.NET Framework) . O .NET versão 4.5.2 ou superior é necessário.
- Em Nome do projeto, insira ADFv2QuickStart.
- Selecione Criar para criar o cluster.
Instalar os pacotes NuGet
Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.
No painel Console do Gerenciador de Pacotes, execute os comandos a seguir para instalar os pacotes. Para obter mais informações, consulte o Pacote NuGet Azure.ResourceManager.DataFactory.
Install-Package Azure.ResourceManager.DataFactory -IncludePrerelease Install-Package Azure.Identity
Criar uma data factory
Abra Program.cs e inclua as instruções a seguir para adicionar referências aos namespaces.
using Azure; using Azure.Core; using Azure.Core.Expressions.DataFactory; using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.DataFactory; using Azure.ResourceManager.DataFactory.Models; using Azure.ResourceManager.Resources; using System; using System.Collections.Generic;
Adicione o código a seguir, que define as variáveis, ao método Main. Substitua os espaços reservados pelos seus próprios valores. Para obter uma lista de regiões do Azure no qual o Data Factory está disponível no momento, selecione as regiões que relevantes para você na página a seguir e, em seguida, expanda Análise para localizar Data Factory: Produtos disponíveis por região. Os armazenamentos de dados (Armazenamento do Azure, Banco de Dados SQL do Azure entre outros) e serviços de computação (HDInsight entre outros) usados pelo data factory podem estar em outras regiões.
// Set variables string tenantID = "<your tenant ID>"; string applicationId = "<your application ID>"; string authenticationKey = "<your authentication key for the application>"; string subscriptionId = "<your subscription ID where the data factory resides>"; string resourceGroup = "<your resource group where the data factory resides>"; string region = "<the location of your resource group>"; string dataFactoryName = "<specify the name of data factory to create. It must be globally unique.>"; string storageAccountName = "<your storage account name to copy data>"; string storageKey = "<your storage account key>"; // specify the container and input folder from which all files // need to be copied to the output folder. string inputBlobContainer = "<blob container to copy data from, e.g. containername>"; string inputBlobPath = "<path to existing blob(s) to copy data from, e.g. inputdir/file>"; //specify the contains and output folder where the files are copied string outputBlobContainer = "<blob container to copy data from, e.g. containername>"; string outputBlobPath = "<the blob path to copy data to, e.g. outputdir/file>"; // name of the Azure Storage linked service, blob dataset, and the pipeline string storageLinkedServiceName = "AzureStorageLinkedService"; string blobDatasetName = "BlobDataset"; string pipelineName = "Adfv2QuickStartPipeline";
Adicione o código a seguir, que cria um data factory, ao método Main.
ArmClient armClient = new ArmClient( new ClientSecretCredential(tenantID, applicationId, authenticationKey, new TokenCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzurePublicCloud }), subscriptionId, new ArmClientOptions { Environment = ArmEnvironment.AzurePublicCloud } ); ResourceIdentifier resourceIdentifier = SubscriptionResource.CreateResourceIdentifier(subscriptionId); SubscriptionResource subscriptionResource = armClient.GetSubscriptionResource(resourceIdentifier); Console.WriteLine("Get an existing resource group " + resourceGroupName + "..."); var resourceGroupOperation = subscriptionResource.GetResourceGroups().Get(resourceGroupName); ResourceGroupResource resourceGroupResource = resourceGroupOperation.Value; Console.WriteLine("Create a data factory " + dataFactoryName + "..."); DataFactoryData dataFactoryData = new DataFactoryData(AzureLocation.EastUS2); var dataFactoryOperation = resourceGroupResource.GetDataFactories().CreateOrUpdate(WaitUntil.Completed, dataFactoryName, dataFactoryData); Console.WriteLine(dataFactoryOperation.WaitForCompletionResponse().Content); // Get the data factory resource DataFactoryResource dataFactoryResource = dataFactoryOperation.Value;
Criar um serviço vinculado
Adicione o código a seguir, que cria um serviço vinculado do Armazenamento do Azure, ao método Main.
Os serviços vinculados são criados em um data factory para vincular seus armazenamentos de dados e serviços de computação ao data factory. Neste Início Rápido, você só precisa criar um serviço vinculado do Armazenamento de Blobs do Azure para a origem da cópia e o repositório de coletores; ele se chama "AzureBlobStorageLinkedService" no exemplo.
// Create an Azure Storage linked service
Console.WriteLine("Create a linked service " + storageLinkedServiceName + "...");
AzureBlobStorageLinkedService azureBlobStorage = new AzureBlobStorageLinkedService()
{
ConnectionString = azureBlobStorageConnectionString
};
DataFactoryLinkedServiceData linkedServiceData = new DataFactoryLinkedServiceData(azureBlobStorage);
var linkedServiceOperation = dataFactoryResource.GetDataFactoryLinkedServices().CreateOrUpdate(WaitUntil.Completed, storageLinkedServiceName, linkedServiceData);
Console.WriteLine(linkedServiceOperation.WaitForCompletionResponse().Content);
Criar um conjunto de dados
Adicione o código a seguir ao método Principal que cria um Conjunto de dados de texto delimitado.
Você define um conjunto de dados que representa os dados a copiar de uma origem para um coletor. Neste exemplo, esse Conjunto de dados de texto delimitado faz referência ao serviço vinculado do Armazenamento de Blobs do Azure criado na etapa anterior. O conjunto de dados usa dois parâmetros cujo valor é definido em uma atividade que consome o conjunto de dados. Os parâmetros são usados para construir o "contêiner" e o "folderPath" apontando para onde os dados residem/são armazenados.
// Create an Azure Blob dataset
DataFactoryLinkedServiceReference linkedServiceReference = new DataFactoryLinkedServiceReference(DataFactoryLinkedServiceReferenceType.LinkedServiceReference, storageLinkedServiceName);
DelimitedTextDataset delimitedTextDataset = new DelimitedTextDataset(linkedServiceReference)
{
DataLocation = new AzureBlobStorageLocation
{
Container = DataFactoryElement<string>.FromExpression("@dataset().container"),
FileName = DataFactoryElement<string>.FromExpression("@dataset().path")
},
Parameters =
{
new KeyValuePair<string, EntityParameterSpecification>("container",new EntityParameterSpecification(EntityParameterType.String)),
new KeyValuePair<string, EntityParameterSpecification>("path",new EntityParameterSpecification(EntityParameterType.String))
},
FirstRowAsHeader = false,
QuoteChar = "\"",
EscapeChar = "\\",
ColumnDelimiter = ","
};
DataFactoryDatasetData datasetData = new DataFactoryDatasetData(delimitedTextDataset);
var datasetOperation = dataFactoryResource.GetDataFactoryDatasets().CreateOrUpdate(WaitUntil.Completed, blobDatasetName, datasetData);
Console.WriteLine(datasetOperation.WaitForCompletionResponse().Content);
Criar um pipeline
Adicione o código a seguir, que cria um pipeline com uma atividade de cópia, ao método Main.
Neste exemplo, este pipeline contém uma atividade e usa quatro parâmetros: o contêiner e o caminho do blob de entrada e o contêiner e o caminho do blob de saída. Os valores para esses parâmetros são definidos quando o pipeline é disparado/executado. A atividade de cópia refere-se ao mesmo conjunto de dados de blob criado na etapa anterior como entrada e saída. Quando o conjunto de dados é usado como um conjunto de dados de entrada, o contêiner de entrada e o caminho são especificados. E, quando o conjunto de dados é usado como um conjunto de dados de saída, o contêiner de saída e o caminho são especificados.
// Create a pipeline with a copy activity
Console.WriteLine("Creating pipeline " + pipelineName + "...");
DataFactoryPipelineData pipelineData = new DataFactoryPipelineData()
{
Parameters =
{
new KeyValuePair<string, EntityParameterSpecification>("inputContainer",new EntityParameterSpecification(EntityParameterType.String)),
new KeyValuePair<string, EntityParameterSpecification>("inputPath",new EntityParameterSpecification(EntityParameterType.String)),
new KeyValuePair<string, EntityParameterSpecification>("outputContainer",new EntityParameterSpecification(EntityParameterType.String)),
new KeyValuePair<string, EntityParameterSpecification>("outputPath",new EntityParameterSpecification(EntityParameterType.String))
},
Activities =
{
new CopyActivity("CopyFromBlobToBlob",new DataFactoryBlobSource(),new DataFactoryBlobSink())
{
Inputs =
{
new DatasetReference(DatasetReferenceType.DatasetReference,blobDatasetName)
{
Parameters =
{
new KeyValuePair<string, BinaryData>("container", BinaryData.FromString("\"@pipeline().parameters.inputContainer\"")),
new KeyValuePair<string, BinaryData>("path", BinaryData.FromString("\"@pipeline().parameters.inputPath\""))
}
}
},
Outputs =
{
new DatasetReference(DatasetReferenceType.DatasetReference,blobDatasetName)
{
Parameters =
{
new KeyValuePair<string, BinaryData>("container", BinaryData.FromString("\"@pipeline().parameters.outputContainer\"")),
new KeyValuePair<string, BinaryData>("path", BinaryData.FromString("\"@pipeline().parameters.outputPath\""))
}
}
}
}
}
};
var pipelineOperation = dataFactoryResource.GetDataFactoryPipelines().CreateOrUpdate(WaitUntil.Completed, pipelineName, pipelineData);
Console.WriteLine(pipelineOperation.WaitForCompletionResponse().Content);
Criar uma execução de pipeline
Adicione o código a seguir, que dispara uma execução de pipeline, ao método Main.
Esse código também define valores dos parâmetros inputContainer, inputPath, outputContainere outputPath especificados no pipeline com os valores reais dos caminhos de blob de origem e de coletor.
// Create a pipeline run
Console.WriteLine("Creating pipeline run...");
Dictionary<string, BinaryData> parameters = new Dictionary<string, BinaryData>()
{
{ "inputContainer",BinaryData.FromObjectAsJson(inputBlobContainer) },
{ "inputPath",BinaryData.FromObjectAsJson(inputBlobPath) },
{ "outputContainer",BinaryData.FromObjectAsJson(outputBlobContainer) },
{ "outputPath",BinaryData.FromObjectAsJson(outputBlobPath) }
};
var pipelineResource = dataFactoryResource.GetDataFactoryPipeline(pipelineName);
var runResponse = pipelineResource.Value.CreateRun(parameters);
Console.WriteLine("Pipeline run ID: " + runResponse.Value.RunId);
Monitorar uma execução de pipeline
Adicione o código a seguir ao método Main para verificar continuamente o status até que ele termine de copiar os dados.
// Monitor the pipeline run Console.WriteLine("Checking pipeline run status..."); DataFactoryPipelineRunInfo pipelineRun; while (true) { pipelineRun = dataFactoryResource.GetPipelineRun(runResponse.Value.RunId.ToString()); Console.WriteLine("Status: " + pipelineRun.Status); if (pipelineRun.Status == "InProgress" || pipelineRun.Status == "Queued") System.Threading.Thread.Sleep(15000); else break; }
Adicione o código a seguir ao método Main para recuperar os detalhes de execução da atividade de cópia, como o tamanho dos dados que são lidos ou gravados.
// Check the copy activity run details Console.WriteLine("Checking copy activity run details..."); var queryResponse = dataFactoryResource.GetActivityRun(pipelineRun.RunId.ToString(), new RunFilterContent(DateTime.UtcNow.AddMinutes(-10), DateTime.UtcNow.AddMinutes(10))); var enumerator = queryResponse.GetEnumerator(); enumerator.MoveNext(); if (pipelineRun.Status == "Succeeded") Console.WriteLine(enumerator.Current.Output); else Console.WriteLine(enumerator.Current.Error); Console.WriteLine("\nPress any key to exit..."); Console.ReadKey();
Executar o código
Compile e inicie o aplicativo, então verifique a execução do pipeline.
O console imprime o progresso de criação do data factory, do serviço vinculado, dos conjuntos de dados, do pipeline e da execução de pipeline. Em seguida, ele verifica o status da execução de pipeline. Aguarde até ver os detalhes da execução da atividade de cópia com o tamanho dos dados de leitura/gravação. Em seguida, use ferramentas como o Gerenciador de Armazenamento do Azure para verificar se os blobs são copiados de "inputBlobPath" para "outputBlobPath" conforme você especificou nas variáveis.
Saída de exemplo
Create a data factory quickstart-adf...
{
"name": "quickstart-adf",
"type": "Microsoft.DataFactory/factories",
"properties": {
"provisioningState": "Succeeded",
"version": "2018-06-01"
},
"location": "eastus2"
}
Create a linked service AzureBlobStorage...
{
"name": "AzureBlobStorage",
"type": "Microsoft.DataFactory/factories/linkedservices",
"properties": {
"type": "AzureBlobStorage",
"typeProperties": {
"connectionString": "DefaultEndpointsProtocol=https;AccountName=<storageAccountName>;",
"encryptedCredential": "<encryptedCredential>"
}
}
}
Creating dataset BlobDelimitedDataset...
{
"name": "BlobDelimitedDataset",
"type": "Microsoft.DataFactory/factories/datasets",
"properties": {
"type": "DelimitedText",
"linkedServiceName": {
"type": "LinkedServiceReference",
"referenceName": "AzureBlobStorage"
},
"parameters": {
"container": {
"type": "String"
},
"path": {
"type": "String"
}
},
"typeProperties": {
"location": {
"container": {
"type": "Expression",
"value": "@dataset().container"
},
"type": "AzureBlobStorageLocation",
"fileName": {
"type": "Expression",
"value": "@dataset().path"
}
},
"columnDelimiter": ",",
"quoteChar": "\"",
"escapeChar": "\\",
"firstRowAsHeader": false
}
}
}
Creating pipeline Adfv2QuickStartPipeline...
{
"properties": {
"activities": [
{
"inputs": [
{
"type": "DatasetReference",
"referenceName": "BlobDelimitedDataset",
"parameters": {
"container": "@pipeline().parameters.inputContainer",
"path": "@pipeline().parameters.inputPath"
}
}
],
"outputs": [
{
"type": "DatasetReference",
"referenceName": "BlobDelimitedDataset",
"parameters": {
"container": "@pipeline().parameters.outputContainer",
"path": "@pipeline().parameters.outputPath"
}
}
],
"name": "CopyFromBlobToBlob",
"type": "Copy",
"typeProperties": {
"source": {
"type": "BlobSource"
},
"sink": {
"type": "BlobSink"
}
}
}
],
"parameters": {
"inputContainer": {
"type": "String"
},
"inputPath": {
"type": "String"
},
"outputContainer": {
"type": "String"
},
"outputPath": {
"type": "String"
}
}
}
}
Creating pipeline run...
Pipeline run ID: 3aa26ffc-5bee-4db9-8bac-ccbc2d7b51c1
Checking pipeline run status...
Status: InProgress
Status: Succeeded
Checking copy activity run details...
{
"dataRead": 1048,
"dataWritten": 1048,
"filesRead": 1,
"filesWritten": 1,
"sourcePeakConnections": 1,
"sinkPeakConnections": 1,
"copyDuration": 8,
"throughput": 1.048,
"errors": [],
"effectiveIntegrationRuntime": "AutoResolveIntegrationRuntime (East US 2)",
"usedDataIntegrationUnits": 4,
"billingReference": {
"activityType": "DataMovement",
"billableDuration": [
{
"meterType": "AzureIR",
"duration": 0.06666666666666667,
"unit": "DIUHours"
}
],
"totalBillableDuration": [
{
"meterType": "AzureIR",
"duration": 0.06666666666666667,
"unit": "DIUHours"
}
]
},
"usedParallelCopies": 1,
"executionDetails": [
{
"source": {
"type": "AzureBlobStorage"
},
"sink": {
"type": "AzureBlobStorage"
},
"status": "Succeeded",
"start": "2023-12-15T10:25:33.9991558Z",
"duration": 8,
"usedDataIntegrationUnits": 4,
"usedParallelCopies": 1,
"profile": {
"queue": {
"status": "Completed",
"duration": 5
},
"transfer": {
"status": "Completed",
"duration": 1,
"details": {
"listingSource": {
"type": "AzureBlobStorage",
"workingDuration": 0
},
"readingFromSource": {
"type": "AzureBlobStorage",
"workingDuration": 0
},
"writingToSink": {
"type": "AzureBlobStorage",
"workingDuration": 0
}
}
}
},
"detailedDurations": {
"queuingDuration": 5,
"transferDuration": 1
}
}
],
"dataConsistencyVerification": {
"VerificationResult": "NotVerified"
}
}
Press any key to exit...
Verificar a saída
O pipeline cria automaticamente a pasta de saída no contêiner de blob adftutorial. Em seguida, ele copia o arquivo emp.txt da pasta de entrada para a pasta de saída.
- No portal do Azure, na página do contêiner adftutorial que você interrompeu na seção Adicionar uma pasta de entrada e um arquivo ao contêiner de blobs acima, selecione Atualizar para exibir a pasta de saída.
- Na lista de pastas, selecione saída.
- Confirme que emp.txt tenha sido copiado para a pasta de saída.
Limpar os recursos
Para excluir programaticamente o data factory, adicione as linhas de código a seguir ao programa:
Console.WriteLine("Deleting the data factory");
dataFactoryResource.Delete(WaitUntil.Completed);
Próximas etapas
O pipeline nessa amostra copia dados de uma localização para outra em um Armazenamento de Blobs do Azure. Percorra os tutoriais para saber mais sobre o uso do Data Factory em mais cenários.