Quickstart: Create a data factory and pipeline using .NET SDK (Guia de Início Rápido: Criar uma fábrica de dados e um pipeline com o SDK .NET)
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 SDK do .NET 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.
- 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 e, em seguida, selecione >Contas de armazenamento de armazenamento. Você também pode pesquisar e selecionar Contas de armazenamento em qualquer página.
- 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.
Visual Studio
O passo a passo neste artigo usa o Visual Studio 2019. Os procedimentos para Visual Studio 2013, 2015 ou 2017 diferem ligeiramente.
Criar um aplicativo no Microsoft Entra ID
Nas seções em Como: Usar o portal para criar um aplicativo Microsoft Entra e entidade de serviço que pode acessar recursos, siga as instruções para executar estas tarefas:
- Em Criar um aplicativo Microsoft Entra, crie um aplicativo que represente o aplicativo .NET que você está criando neste tutorial. Para o URL de início de sessão, pode fornecer um URL fictício conforme 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ê usa 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 de Colaborador no nível da assinatura para que o aplicativo possa criar fábricas de dados na assinatura.
Criar um projeto do Visual Studio
Em seguida, crie um aplicativo de console C# .NET no Visual Studio:
- Inicie o Visual Studio.
- Na janela Iniciar, selecione Criar um novo aplicativo de console do projeto>(.NET Framework). É necessária a versão 4.5.2 ou superior do .NET.
- Em Nome do projeto, insira ADFv2QuickStart.
- Selecione Create (Criar) para criar o projeto.
Instalar pacotes NuGet
Selecione Ferramentas NuGet Package Manager Package Manager Console (Ferramentas>NuGet Package Manager>PackageManager Console).
No painel Console do Gerenciador de Pacotes, execute os seguintes comandos para instalar 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 fábrica de dados
Abra Program.cs e inclua as seguintes instruções para adicionar referências aos espaços de nomes.
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 seguinte ao método Principal que define as variáveis. Substitua os marcadores de posição pelos seus próprios valores. 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 armazenamentos de dados (Armazenamento do Azure, Banco de Dados SQL do Azure e muito mais) e os cálculos (HDInsight e 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 seguinte ao método Main que cria uma fábrica de dados.
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 ligado
Adicione o código seguinte ao método Main, que cria um serviço ligado do Armazenamento do Microsoft Azure.
Os serviços ligados são criados 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 Guia de início rápido, você só precisa criar um serviço vinculado do Armazenamento de Blobs do Azure para a fonte de cópia e o repositório de coletores; ele é chamado "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 seguinte código ao método Main que cria um conjunto de dados de texto delimitado.
Defina um conjunto de dados que represente os dados a copiar de uma origem para um sink. Neste exemplo, este conjunto de dados de texto delimitado faz referência ao serviço vinculado de Armazenamento de Blobs do Azure que você criou 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 "container" e o "folderPath" apontando para onde os dados residem/estã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 seguinte ao método Main que cria um pipeline com uma atividade de cópia.
Neste exemplo, esse 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 destes parâmetros são definidos quando o pipeline é acionado/executado. A atividade de cópia refere-se ao mesmo conjunto de dados de blobs criado no passo anterior como entrada e saída. Quando o conjunto de dados é usado como um conjunto de dados de entrada, o contêiner e o caminho de entrada são especificados. E, quando o conjunto de dados é usado como um conjunto de dados de saída, o contêiner e o caminho de saída 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 seguinte ao método Main que aciona uma execução de pipeline.
Esse código também define valores dos parâmetros inputContainer, inputPath, outputContainer e outputPath especificados no pipeline com os valores reais dos caminhos de blob de origem e 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);
Monitorizar uma execução de pipeline
Adicione o código seguinte ao método Main para verificar continuamente o estado até terminar 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 que recupera detalhes da execução da atividade de cópia, como o tamanho dos dados 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
Crie e inicie a aplicação e, em seguida, verifique a execução de pipeline.
A consola imprime o progresso da criação da fábrica de dados, o serviço ligado, os conjuntos de dados, o pipeline e a execução de pipeline. Em seguida, verifica o estado de execução do 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 o(s) blob(s) é(são) copiado(s) para "outputBlobPath" de "inputBlobPath", conforme especificado 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 de contêiner adftutorial em que você parou na seção Adicionar uma pasta de entrada e um arquivo para o contêiner de blob acima, selecione Atualizar para ver a pasta de saída.
- Na lista de pastas, selecione saída.
- Confirme se o ficheiro emp.txt foi copiado para a pasta de saída.
Clean up resources (Limpar recursos)
Para excluir programaticamente o data factory, adicione as seguintes linhas de código ao programa:
Console.WriteLine("Deleting the data factory");
dataFactoryResource.Delete(WaitUntil.Completed);
Próximos passos
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.