Guida introduttiva: Creare una data factory e una pipeline con .NET SDK

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questa guida di avvio rapido descrive come usare .NET SDK per creare un'istanza di Azure Data Factory. La pipeline creata in questa data factory copia dati da una cartella a un'altra in un archivio BLOB di Azure. Per un'esercitazione su come trasformare dati usando Azure Data Factory, vedere Esercitazione: Trasformare i dati con Spark.

Nota

Questo articolo non offre una presentazione dettagliata del servizio Data Factory. Per un'introduzione al servizio Azure Data Factory, vedere Introduzione ad Azure Data Factory.

Prerequisiti

Sottoscrizione di Azure

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Ruoli di Azure

Per creare istanze di Data Factory, l'account utente usato per accedere ad Azure deve essere un membro del ruolo collaboratore o proprietario oppure un amministratore della sottoscrizione di Azure. Per visualizzare le autorizzazioni disponibili nella sottoscrizione, passare al portale di Azure, selezionare il nome utente nell'angolo in alto a destra, selezionare l'icona ... per visualizzare altre opzioni e quindi selezionare Autorizzazioni personali. Se si accede a più sottoscrizioni, selezionare quella appropriata.

Per creare e gestire le risorse figlio per Data Factory, inclusi i set di dati, i servizi collegati, le pipeline, i trigger e i runtime di integrazione, sono applicabili i requisiti seguenti:

  • Per creare e gestire le risorse figlio nel portale di Azure, è necessario appartenere al ruolo Collaboratore Data Factory a livello di gruppo di risorse o superiore.
  • Per creare e gestire le risorse figlio con PowerShell o l'SDK, è sufficiente il ruolo di collaboratore a livello di risorsa o superiore.

Per istruzioni di esempio su come aggiungere un utente a un ruolo, vedere l'articolo Aggiungere i ruoli.

Per altre informazioni, vedere gli articoli seguenti:

Account di archiviazione di Azure

In questa guida di avvio rapido si usa un account di archiviazione di Azure per utilizzo generico (nello specifico, un account di archiviazione BLOB) come archivio dati sia di origine che di destinazione. Se non si ha un account di archiviazione di Azure per utilizzo generico, vedere Creare un account di archiviazione per informazioni su come crearne uno.

Ottenere il nome dell'account di archiviazione

Il nome dell'account di archiviazione di Azure è necessario per questa guida di avvio rapido. La procedura seguente illustra i passaggi per recuperare il nome dell'account di archiviazione:

  1. In un Web browser passare al portale di Azure e accedere usando il nome utente e la password di Azure.
  2. Dal menu del portale di Azure scegliere Tutti i servizi, quindi selezionare Archiviazione > Account di archiviazione. È anche possibile cercare e selezionare Account di archiviazione in qualsiasi pagina.
  3. Nella pagina Account di archiviazione filtrare gli account di archiviazione, se necessario, quindi selezionare il proprio account di archiviazione.

È anche possibile cercare e selezionare Account di archiviazione in qualsiasi pagina.

Creare un contenitore BLOB

In questa sezione viene creato un contenitore BLOB denominato adftutorial nell'archivio BLOB di Azure.

  1. Dalla pagina dell'account di archiviazione, selezionare Panoramica > Contenitori.

  2. Sulla barra degli strumenti della pagina <Account name> - Contenitori selezionare Contenitore.

  3. Nella finestra di dialogo Nuovo contenitore immettere adftutorial come nome e quindi fare clic su OK. La pagina <Account name> - Contenitori viene aggiornata per includere adftutorial nell'elenco.

    Elenco dei contenitori

Aggiungere una cartella di input e un file per il contenitore BLOB

In questa sezione viene creata una cartella denominata input nel contenitore creato, in cui verrà caricato un file di esempio. Prima di iniziare, aprire un editor di testo come il Blocco note e creare un file denominato emp.txt con il contenuto seguente:

John, Doe
Jane, Doe

Salvare il file nella cartella C:\ADFv2QuickStartPSH. Se la cartella non esiste, crearla. Tornare al portale di Azure e seguire questa procedura:

  1. Nella pagina <Account name> - Contenitori selezionare adftutorial nell'elenco aggiornato.

    1. Se la finestra è stata chiusa o è passata a un'altra pagina, accedere nuovamente al portale di Azure.
    2. Dal menu del portale di Azure scegliere Tutti i servizi, quindi selezionare Archiviazione > Account di archiviazione. È anche possibile cercare e selezionare Account di archiviazione in qualsiasi pagina.
    3. Selezionare l'account di archiviazione, quindi Contenitori > adftutorial.
  2. Nella barra degli strumenti della pagina del contenitore adftutorial selezionare Carica.

  3. Nella pagina Carica BLOB selezionare la casella File, quindi individuare e selezionare il file emp.txt.

  4. Espandere l'intestazione Avanzate. La pagina viene ora visualizzata come illustrato di seguito:

    Selezionare il collegamento Avanzate

  5. Nella casella Carica nella cartella immettere input.

  6. Selezionare il pulsante Carica. Verranno visualizzati il file emp.txt e lo stato del caricamento nell'elenco.

  7. Selezionare l'icona Chiudi (una X) per chiudere la pagina Carica BLOB.

Lasciare aperta la pagina del contenitore adftutorial. perché verrà usata per verificare l'output alla fine di questa guida introduttiva.

Visual Studio

Nella procedura guidata illustrata in questo articolo viene usato Visual Studio 2019. Le procedure per Visual Studio 2013, 2015 o 2017 sono leggermente diverse.

Creare un'applicazione in Azure Active Directory

Dalle sezioni in Procedura: Usare il portale per creare un'entità servizio e applicazione di Azure AD che possano accedere alle risorse, seguire le istruzioni per eseguire queste attività:

  1. In Creare un'applicazione Azure Active Directory creare un'applicazione che rappresenti l'applicazione .NET che verrà creata in questa esercitazione. Come URL di accesso è possibile specificare un URL fittizio, come illustrato nell'articolo (https://contoso.org/exampleapp).
  2. In Ottenere i valori per l'accesso ottenere l'ID dell'applicazione e l'ID del tenant, quindi prendere nota di questi valori che verranno usati più avanti in questa esercitazione.
  3. In Certificati e segreti ottenere la chiave di autenticazione e prendere nota di questo valore che verrà usato più avanti in questa esercitazione.
  4. In Assegnare l'applicazione a un ruolo assegnare l'applicazione al ruolo Collaboratore a livello di sottoscrizione, in modo che l'applicazione possa creare le data factory nella sottoscrizione.

Creare un progetto di Visual Studio

Creare quindi un'applicazione console C# .NET in Visual Studio:

  1. Avviare Visual Studio.
  2. Nella finestra di avvio selezionare Crea un nuovo progetto > App console (.NET Framework) . È necessario .NET versione 4.5.2 o successiva.
  3. In Nome progetto immettere ADFv2QuickStart.
  4. Selezionare Crea per creare il progetto.

Installare i pacchetti NuGet

  1. Fare clic su Strumenti > Gestione Pacchetti NuGet > Console di Gestione pacchetti.

  2. Nel riquadro Console di Gestione pacchetti eseguire questi comandi per installare i pacchetti. Per altre informazioni, vedere il pacchetto NuGet Microsoft.Azure.Management.DataFactory.

    Install-Package Microsoft.Azure.Management.DataFactory
    Install-Package Microsoft.Azure.Management.ResourceManager -IncludePrerelease
    Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory
    

Creare un client di data factory

  1. Aprire Program.cs e includere le istruzioni seguenti per aggiungere riferimenti agli spazi dei nomi.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using Microsoft.Rest;
    using Microsoft.Rest.Serialization;
    using Microsoft.Azure.Management.ResourceManager;
    using Microsoft.Azure.Management.DataFactory;
    using Microsoft.Azure.Management.DataFactory.Models;
    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  2. Aggiungere il codice seguente al metodo Main per impostare le variabili. Sostituire i segnaposto con i valori personalizzati. Per un elenco di aree di Azure in cui Data Factory è attualmente disponibile, selezionare le aree di interesse nella pagina seguente, quindi espandere Analytics per individuare Data Factory: Prodotti disponibili in base all'area. Gli archivi dati (Archiviazione di Azure, database SQL di Azure e altri) e le risorse di calcolo (HDInsight e altre) usati dalla data factory possono trovarsi in altre aree.

    // 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 storageAccount = "<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 inputBlobPath =
        "<path to existing blob(s) to copy data from, e.g. containername/inputdir>";
    //specify the contains and output folder where the files are copied
    string outputBlobPath =
        "<the blob path to copy data to, e.g. containername/outputdir>";
    
    // name of the Azure Storage linked service, blob dataset, and the pipeline
    string storageLinkedServiceName = "AzureStorageLinkedService";
    string blobDatasetName = "BlobDataset";
    string pipelineName = "Adfv2QuickStartPipeline";
    

Nota

Per i cloud sovrani, è necessario usare gli endpoint specifici del cloud appropriati per ActiveDirectoryAuthority e ResourceManagerUrl (BaseUri). Ad esempio, negli Stati Uniti Azure Gov si usa l'autorità di anziché e si usa invece di e quindi si crea il client data factory https://login.microsoftonline.us https://login.microsoftonline.com di https://management.usgovcloudapi.net https://management.azure.com/ gestione. È possibile usare PowerShell per ottenere facilmente gli URL dell'endpoint per vari cloud eseguendo "Get-AzEnvironment | Format-List", che restituirà un elenco di endpoint per ogni ambiente cloud.

  1. Aggiungere il codice seguente al metodo Main per creare un'istanza della classe DataFactoryManagementClient. Usare questo oggetto per creare una data factory, il servizio collegato, i set di dati e la pipeline. È possibile usare questo oggetto anche per monitorare i dettagli sull'esecuzione della pipeline.

    // Authenticate and create a data factory management client
    var context = new AuthenticationContext("https://login.microsoftonline.com/" + tenantID);
    ClientCredential cc = new ClientCredential(applicationId, authenticationKey);
    AuthenticationResult result = context.AcquireTokenAsync(
        "https://management.azure.com/", cc).Result;
    ServiceClientCredentials cred = new TokenCredentials(result.AccessToken);
    var client = new DataFactoryManagementClient(cred) {
        SubscriptionId = subscriptionId };
    

Creare una data factory

Aggiungere il codice seguente al metodo Main per creare una data factory.

// Create a data factory
Console.WriteLine("Creating data factory " + dataFactoryName + "...");
Factory dataFactory = new Factory
{
    Location = region,
    Identity = new FactoryIdentity()
};
client.Factories.CreateOrUpdate(resourceGroup, dataFactoryName, dataFactory);
Console.WriteLine(
    SafeJsonConvert.SerializeObject(dataFactory, client.SerializationSettings));

while (client.Factories.Get(resourceGroup, dataFactoryName).ProvisioningState ==
       "PendingCreation")
{
    System.Threading.Thread.Sleep(1000);
}

Creare un servizio collegato

Aggiungere il codice seguente al metodo Main per creare un servizio collegato di Archiviazione di Azure.

Si creano servizi collegati in una data factory per collegare gli archivi dati e i servizi di calcolo alla data factory. In questa guida di avvio rapido è necessario creare solo un servizio collegato Archiviazione di Azure per l'origine della copia e l'archivio sink, denominato "AzureStorageLinkedService" nell'esempio.

// Create an Azure Storage linked service
Console.WriteLine("Creating linked service " + storageLinkedServiceName + "...");

LinkedServiceResource storageLinkedService = new LinkedServiceResource(
    new AzureStorageLinkedService
    {
        ConnectionString = new SecureString(
            "DefaultEndpointsProtocol=https;AccountName=" + storageAccount +
            ";AccountKey=" + storageKey)
    }
);
client.LinkedServices.CreateOrUpdate(
    resourceGroup, dataFactoryName, storageLinkedServiceName, storageLinkedService);
Console.WriteLine(SafeJsonConvert.SerializeObject(
    storageLinkedService, client.SerializationSettings));

Creare un set di dati

Aggiungere il codice seguente al metodo Main per creare un set di dati del BLOB di Azure.

È necessario definire un set di dati che rappresenta i dati da copiare da un'origine a un sink. In questo esempio il set di dati del BLOB fa riferimento al servizio collegato Archiviazione di Azure creato nel passaggio precedente. Il set di dati accetta un parametro il cui valore è impostato in un'attività che utilizza il set di dati. Il parametro viene usato per costruire la proprietà "folderPath" che punta al percorso in cui si trovano e sono archiviati i dati.

// Create an Azure Blob dataset
Console.WriteLine("Creating dataset " + blobDatasetName + "...");
DatasetResource blobDataset = new DatasetResource(
    new AzureBlobDataset
    {
        LinkedServiceName = new LinkedServiceReference
        {
            ReferenceName = storageLinkedServiceName
        },
        FolderPath = new Expression { Value = "@{dataset().path}" },
        Parameters = new Dictionary<string, ParameterSpecification>
        {
            { "path", new ParameterSpecification { Type = ParameterType.String } }
        }
    }
);
client.Datasets.CreateOrUpdate(
    resourceGroup, dataFactoryName, blobDatasetName, blobDataset);
Console.WriteLine(
    SafeJsonConvert.SerializeObject(blobDataset, client.SerializationSettings));

Creare una pipeline

Aggiungere il codice seguente al metodo Main per creare una pipeline con un'attività di copia.

In questo esempio la pipeline contiene un'attività e accetta due parametri: il percorso del BLOB di input e il percorso del BLOB di output. I valori per questi parametri vengono impostati all'esecuzione/attivazione della pipeline. L'attività di copia fa riferimento allo stesso set di dati del BLOB creato nel passaggio precedente come input e output. Quando il set di dati viene usato come set di dati di input, viene specificato il percorso di input. Quando il set di dati viene usato come set di dati di output, viene specificato il percorso di output.

// Create a pipeline with a copy activity
Console.WriteLine("Creating pipeline " + pipelineName + "...");
PipelineResource pipeline = new PipelineResource
{
    Parameters = new Dictionary<string, ParameterSpecification>
    {
        { "inputPath", new ParameterSpecification { Type = ParameterType.String } },
        { "outputPath", new ParameterSpecification { Type = ParameterType.String } }
    },
    Activities = new List<Activity>
    {
        new CopyActivity
        {
            Name = "CopyFromBlobToBlob",
            Inputs = new List<DatasetReference>
            {
                new DatasetReference()
                {
                    ReferenceName = blobDatasetName,
                    Parameters = new Dictionary<string, object>
                    {
                        { "path", "@pipeline().parameters.inputPath" }
                    }
                }
            },
            Outputs = new List<DatasetReference>
            {
                new DatasetReference
                {
                    ReferenceName = blobDatasetName,
                    Parameters = new Dictionary<string, object>
                    {
                        { "path", "@pipeline().parameters.outputPath" }
                    }
                }
            },
            Source = new BlobSource { },
            Sink = new BlobSink { }
        }
    }
};
client.Pipelines.CreateOrUpdate(resourceGroup, dataFactoryName, pipelineName, pipeline);
Console.WriteLine(SafeJsonConvert.SerializeObject(pipeline, client.SerializationSettings));

Creare un'esecuzione della pipeline

Aggiungere il codice seguente al metodo Main per attivare un'esecuzione della pipeline.

Questo codice imposta anche i valori dei parametri inputPath e outputPath specificati nella pipeline con i valori effettivi dei percorsi dei BLOB di origine e sink.

// Create a pipeline run
Console.WriteLine("Creating pipeline run...");
Dictionary<string, object> parameters = new Dictionary<string, object>
{
    { "inputPath", inputBlobPath },
    { "outputPath", outputBlobPath }
};
CreateRunResponse runResponse = client.Pipelines.CreateRunWithHttpMessagesAsync(
    resourceGroup, dataFactoryName, pipelineName, parameters: parameters
).Result.Body;
Console.WriteLine("Pipeline run ID: " + runResponse.RunId);

Monitorare un'esecuzione della pipeline

  1. Aggiungere il codice seguente al metodo Main per controllare continuamente lo stato fino al termine della copia dei dati.

    // Monitor the pipeline run
    Console.WriteLine("Checking pipeline run status...");
    PipelineRun pipelineRun;
    while (true)
    {
        pipelineRun = client.PipelineRuns.Get(
            resourceGroup, dataFactoryName, runResponse.RunId);
        Console.WriteLine("Status: " + pipelineRun.Status);
        if (pipelineRun.Status == "InProgress" || pipelineRun.Status == "Queued")
            System.Threading.Thread.Sleep(15000);
        else
            break;
    }
    
  2. Aggiungere il codice seguente al metodo Main per recuperare i dettagli dell'esecuzione dell'attività di copia, ad esempio le dimensioni dei dati letti o scritti.

    // Check the copy activity run details
    Console.WriteLine("Checking copy activity run details...");
    
    RunFilterParameters filterParams = new RunFilterParameters(
        DateTime.UtcNow.AddMinutes(-10), DateTime.UtcNow.AddMinutes(10));
    ActivityRunsQueryResponse queryResponse = client.ActivityRuns.QueryByPipelineRun(
        resourceGroup, dataFactoryName, runResponse.RunId, filterParams);
    if (pipelineRun.Status == "Succeeded")
        Console.WriteLine(queryResponse.Value.First().Output);
    else
        Console.WriteLine(queryResponse.Value.First().Error);
    Console.WriteLine("\nPress any key to exit...");
    Console.ReadKey();
    

Eseguire il codice

Compilare e avviare l'applicazione, quindi verificare l'esecuzione della pipeline.

La console stampa lo stato di creazione della data factory, del servizio collegato, dei set di dati, della pipeline e dell'esecuzione della pipeline. Controlla quindi lo stato di esecuzione della pipeline. Attendere fino a visualizzare i dettagli dell'esecuzione dell'attività di copia con le dimensioni dei dati di lettura/scrittura. Usare quindi strumenti come Azure Storage Explorer per verificare che i BLOB siano stati copiati da "inputBlobPath" a "outputBlobPath", come specificato nelle variabili.

Output di esempio

Creating data factory SPv2Factory0907...
{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "East US"
}
Creating linked service AzureStorageLinkedService...
{
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": {
        "value": "DefaultEndpointsProtocol=https;AccountName=<storageAccountName>;AccountKey=<storageAccountKey>",
        "type": "SecureString"
      }
    }
  }
}
Creating dataset BlobDataset...
{
  "properties": {
    "type": "AzureBlob",
    "typeProperties": {
      "folderPath": {
        "value": "@{dataset().path}",
        "type": "Expression"
      }
    },
    "linkedServiceName": {
      "referenceName": "AzureStorageLinkedService",
      "type": "LinkedServiceReference"
    },
    "parameters": {
      "path": {
        "type": "String"
      }
    }
  }
}
Creating pipeline Adfv2QuickStartPipeline...
{
  "properties": {
    "activities": [
      {
        "type": "Copy",
        "typeProperties": {
          "source": {
            "type": "BlobSource"
          },
          "sink": {
            "type": "BlobSink"
          }
        },
        "inputs": [
          {
            "referenceName": "BlobDataset",
            "parameters": {
              "path": "@pipeline().parameters.inputPath"
            },
            "type": "DatasetReference"
          }
        ],
        "outputs": [
          {
            "referenceName": "BlobDataset",
            "parameters": {
              "path": "@pipeline().parameters.outputPath"
            },
            "type": "DatasetReference"
          }
        ],
        "name": "CopyFromBlobToBlob"
      }
    ],
    "parameters": {
      "inputPath": {
        "type": "String"
      },
      "outputPath": {
        "type": "String"
      }
    }
  }
}
Creating pipeline run...
Pipeline run ID: 308d222d-3858-48b1-9e66-acd921feaa09
Checking pipeline run status...
Status: InProgress
Status: InProgress
Checking copy activity run details...
{
    "dataRead": 331452208,
    "dataWritten": 331452208,
    "copyDuration": 23,
    "throughput": 14073.209,
    "errors": [],
    "effectiveIntegrationRuntime": "DefaultIntegrationRuntime (West US)",
    "usedDataIntegrationUnits": 2,
    "billedDuration": 23
}

Press any key to exit...

Verificare l'output

La pipeline crea automaticamente la cartella di output nel contenitore BLOB adftutorial, quindi copia il file emp.txt dalla cartella di input a quella di output.

  1. Nel portale di Azure, nella pagina del contenitore adftutorial in cui si è rimasti dalla sezione precedente Aggiungere una cartella di input e un file per il contenitore BLOB selezionare Aggiorna per visualizzare la cartella di output.
  2. Nell'elenco delle cartelle selezionare output.
  3. Verificare che emp.txt venga copiato nella cartella di output.

Pulire le risorse

Per eliminare una data factory a livello di codice, aggiungere al programma le righe di codice seguenti:

Console.WriteLine("Deleting the data factory");
client.Factories.Delete(resourceGroup, dataFactoryName);

Passaggi successivi

La pipeline in questo esempio copia i dati da una posizione a un'altra in un archivio BLOB di Azure. Per informazioni sull'uso di Data Factory in più scenari, fare riferimento alle esercitazioni.