Creazione, monitoraggio e gestione delle istanze di Azure Data Factory mediante Azure Data Factory .NET SDK

Panoramica

È possibile creare, monitorare e gestire le istanze di Data factory di Azure a livello di codice mediante Data Factory .NET SDK. Questo articolo contiene una procedura dettagliata per la creazione di un'applicazione console .NET di esempio che crea e monitora un'istanza di Data factory.

Nota

Questo articolo non descrive tutte le API .NET di Data Factory. Per la documentazione completa sull'API .NET per Data Factory, vedere Informazioni di riferimento sull'API NET di Data Factory.

Prerequisiti

  • Visual Studio 2012 o 2013 o 2015
  • Scaricare e installare Azure .NET SDK.
  • Azure PowerShell. Seguire le istruzioni disponibili nell'articolo Come installare e configurare Azure PowerShell per installare la versione più recente di Azure PowerShell nel computer. Azure PowerShell verrà usato per creare un'applicazione Azure Active Directory.

Creare un'applicazione in Azure Active Directory

Creare l'applicazione Azure Active Directory, creare un'entità servizio per l'applicazione e assegnarla al ruolo Collaboratore Data Factory .

  1. Avviare PowerShell.
  2. Eseguire il comando seguente e immettere il nome utente e la password usati per accedere al portale di Azure.

    Login-AzureRmAccount
    
  3. Eseguire il comando seguente per visualizzare tutte le sottoscrizioni per l'account.

    Get-AzureRmSubscription
    
  4. Eseguire il comando seguente per selezionare la sottoscrizione da usare. Sostituire <NameOfAzureSubscription> con il nome della sottoscrizione di Azure.

    Get-AzureRmSubscription -SubscriptionName <NameOfAzureSubscription> | Set-AzureRmContext
    
    Importante

    Dall'output del comando prendere nota dei valori di SubscriptionId e TenantId.

  5. Creare un gruppo di risorse di Azure denominato ADFTutorialResourceGroup eseguendo il comando seguente in PowerShell.

    New-AzureRmResourceGroup -Name ADFTutorialResourceGroup  -Location "West US"
    

    Se il gruppo di risorse esiste già, specificare se deve essere aggiornato (Y) o mantenuto invariato (N).

    Se si usa un gruppo di risorse diverso, è necessario usare il nome del gruppo di risorse invece di ADFTutorialResourceGroup in questa esercitazione.

  6. Creare un'applicazione Azure Active Directory.

    $azureAdApplication = New-AzureRmADApplication -DisplayName "ADFDotNetWalkthroughApp" -HomePage "https://www.contoso.org" -IdentifierUris "https://www.adfdotnetwalkthroughapp.org/example" -Password "Pass@word1"
    

    Se viene visualizzato l'errore seguente, specificare un URL diverso ed eseguire di nuovo il comando.

    Another object with the same value for property identifierUris already exists.
    
  7. Creare l'entità servizio di AD.

    New-AzureRmADServicePrincipal -ApplicationId $azureAdApplication.ApplicationId
    
  8. Aggiungere l'entità servizio al ruolo Collaboratore Data Factory .

    New-AzureRmRoleAssignment -RoleDefinitionName "Data Factory Contributor" -ServicePrincipalName $azureAdApplication.ApplicationId.Guid
    
  9. Ottenere l'ID applicazione.

    $azureAdApplication 
    

    Annotare l'ID applicazione (applicationID) dall'output.

Da questi passaggi si avranno i quattro valori seguenti:

  • ID tenant
  • ID sottoscrizione
  • ID applicazione
  • Password (specificata nel primo comando)

Procedura dettagliata

Nella procedura dettagliata, si crea una data factory con una pipeline contenente un'attività di copia. L'attività di copia copia i dati da una cartella nell'archivio BLOB di Azure in un'altra cartella dello stesso archivio BLOB.

L'attività di copia esegue lo spostamento dei dati in Azure Data Factory e si basa su un servizio disponibile a livello globale che può copiare dati tra diversi archivi dati in modo sicuro, affidabile e scalabile. Per informazioni dettagliate sull'attività di copia, vedere Attività di spostamento dei dati .

  1. Creare un'applicazione console .NET in C# con Visual Studio 2012, 2013 o 2015.
    1. Avviare Visual Studio 2012, 2013 o 2015.
    2. Fare clic su File, scegliere Nuovo e quindi fare clic su Progetto.
    3. Espandere Modelli e quindi selezionare Visual C#. In questa procedura dettagliata viene usato C#, ma è possibile usare qualsiasi linguaggio .NET.
    4. Selezionare Applicazione console dall'elenco dei tipi di progetto a destra.
    5. Immettere DataFactoryAPITestApp per Nome.
    6. Selezionare C:\ADFGetStarted come percorso.
    7. Fare clic su OK per creare il progetto.
  2. Fare clic su Strumenti, scegliere Gestione pacchetti NuGet e quindi fare clic su Console di Gestione pacchetti.
  3. Nella finestra Console di Gestione pacchetti seguire questa procedura:
    1. Eseguire questo comando per installare il pacchetto di Data factory: Install-Package Microsoft.Azure.Management.DataFactories
    2. Eseguire questo comando per installare il pacchetto di Azure Active Directory. Nel codice viene usata l'API di Active Directory: Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -Version 2.19.208020213
  4. Sostituire il contenuto del file App.config nel progetto con il contenuto seguente:

    <?xml version="1.0" encoding="utf-8" ?>
    <configuration>
        <appSettings>
            <add key="ActiveDirectoryEndpoint" value="https://login.microsoftonline.com/" />
            <add key="ResourceManagerEndpoint" value="https://management.azure.com/" />
            <add key="WindowsManagementUri" value="https://management.core.windows.net/" />
    
            <add key="ApplicationId" value="your application ID" />
            <add key="Password" value="Password you used while creating the AAD application" />
            <add key="SubscriptionId" value= "Subscription ID" />
            <add key="ActiveDirectoryTenantId" value="Tenant ID" />
        </appSettings>
    </configuration>
    
  5. Nel file App.Config, aggiornare i valori di <Application ID>, <Password>, <Subscription ID> e <tenant ID> con i propri valori.
  6. Aggiungere le seguenti istruzioni using al file Program.cs nel progetto.

    using System.Configuration;
    using System.Collections.ObjectModel;
    using System.Threading;
    using System.Threading.Tasks;
    
    using Microsoft.Azure;
    using Microsoft.Azure.Management.DataFactories;
    using Microsoft.Azure.Management.DataFactories.Models;
    using Microsoft.Azure.Management.DataFactories.Common.Models;
    
    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  7. Aggiungere al metodo Main il codice seguente che crea un'istanza della classe DataPipelineManagementClient. Si userà questo oggetto per creare una data factory, un servizio collegato, i set di dati di input e output e una pipeline. Questo oggetto viene usato anche per monitorare le sezioni di un set di dati in fase di esecuzione.

    // create data factory management client
    
    //IMPORTANT: specify the name of Azure resource group here
    string resourceGroupName = "ADFTutorialResourceGroup";
    
    //IMPORTANT: the name of the data factory must be globally unique.
    // Therefore, update this value. For example:APITutorialFactory05122017
    string dataFactoryName = "APITutorialFactory";
    
    TokenCloudCredentials aadTokenCredentials = new TokenCloudCredentials(
            ConfigurationManager.AppSettings["SubscriptionId"],
            GetAuthorizationHeader().Result);
    
    Uri resourceManagerUri = new Uri(ConfigurationManager.AppSettings["ResourceManagerEndpoint"]);
    
    DataFactoryManagementClient client = new DataFactoryManagementClient(aadTokenCredentials, resourceManagerUri);
    
    Importante

    Sostituire il valore di resourceGroupName con il nome del gruppo di risorse di Azure. Per creare un gruppo di risorse, usare il cmdlet New-AzureResourceGroup .

    Aggiornare il nome della data factory (dataFactoryName) in modo che sia univoco. Il nome della data factory deve essere globalmente univoco. Per informazioni sulle regole di denominazione per gli elementi di Data factory, vedere l'argomento relativo alle regole di denominazione di Data factory .

  8. Aggiungere al metodo Main il codice seguente che crea una data factory.

    // create a data factory
    Console.WriteLine("Creating a data factory");
    client.DataFactories.CreateOrUpdate(resourceGroupName,
        new DataFactoryCreateOrUpdateParameters()
        {
            DataFactory = new DataFactory()
            {
                Name = dataFactoryName,
                Location = "westus",
                Properties = new DataFactoryProperties()
            }
        }
    );
    
  9. Aggiungere al metodo Main il codice seguente che crea un servizio collegato di Archiviazione di Azure.

    Importante

    Sostituire storageaccountname e accountkey con il nome e la chiave dell'account di archiviazione di Azure.

    // create a linked service for input data store: Azure Storage
    Console.WriteLine("Creating Azure Storage linked service");
    client.LinkedServices.CreateOrUpdate(resourceGroupName, dataFactoryName,
        new LinkedServiceCreateOrUpdateParameters()
        {
            LinkedService = new LinkedService()
            {
                Name = "AzureStorageLinkedService",
                Properties = new LinkedServiceProperties
                (
                    new AzureStorageLinkedService("DefaultEndpointsProtocol=https;AccountName=<storageaccountname>;AccountKey=<accountkey>")
                )
            }
        }
    );
    
  10. Aggiungere al metodo Main il codice seguente che crea set di dati di input e output.

    FolderPath per il BLOB di input è impostato su adftutorial/, dove adftutorial è il nome del contenitore nell'archivio BLOB. Se questo contenitore non esiste nell'archivio BLOB di Azure, creare un contenitore con il nome adftutorial e caricare un file di testo nel contenitore.

    FolderPath per il BLOB di output è impostato su adftutorial/apifactoryoutput/{Slice}, dove il valore Slice è calcolato in modo dinamico in base al valore SliceStart (data-ora di inizio di ogni sezione).

    // create input and output datasets
    Console.WriteLine("Creating input and output datasets");
    string Dataset_Source = "DatasetBlobSource";
    string Dataset_Destination = "DatasetBlobDestination";
    
    client.Datasets.CreateOrUpdate(resourceGroupName, dataFactoryName,
    new DatasetCreateOrUpdateParameters()
    {
        Dataset = new Dataset()
        {
            Name = Dataset_Source,
            Properties = new DatasetProperties()
            {
                LinkedServiceName = "AzureStorageLinkedService",
                TypeProperties = new AzureBlobDataset()
                {
                    FolderPath = "adftutorial/",
                    FileName = "emp.txt"
                },
                External = true,
                Availability = new Availability()
                {
                    Frequency = SchedulePeriod.Hour,
                    Interval = 1,
                },
    
                Policy = new Policy()
                {
                    Validation = new ValidationPolicy()
                    {
                        MinimumRows = 1
                    }
                }
            }
        }
    });
    
    client.Datasets.CreateOrUpdate(resourceGroupName, dataFactoryName,
    new DatasetCreateOrUpdateParameters()
    {
        Dataset = new Dataset()
        {
            Name = Dataset_Destination,
            Properties = new DatasetProperties()
            {
    
                LinkedServiceName = "AzureStorageLinkedService",
                TypeProperties = new AzureBlobDataset()
                {
                    FolderPath = "adftutorial/apifactoryoutput/{Slice}",
                    PartitionedBy = new Collection<Partition>()
                    {
                        new Partition()
                        {
                            Name = "Slice",
                            Value = new DateTimePartitionValue()
                            {
                                Date = "SliceStart",
                                Format = "yyyyMMdd-HH"
                            }
                        }
                    }
                },
    
                Availability = new Availability()
                {
                    Frequency = SchedulePeriod.Hour,
                    Interval = 1,
                },
            }
        }
    });
    
  11. Aggiungere al metodo Main il codice seguente che crea e attiva una pipeline. Questa pipeline contiene una proprietà CopyActivity che accetta BlobSource come origine e BlobSink come sink.

    L'attività di copia esegue lo spostamento dei dati in Azure Data Factory e si basa su un servizio disponibile a livello globale che può copiare dati tra diversi archivi dati in modo sicuro, affidabile e scalabile. Per informazioni dettagliate sull'attività di copia, vedere Attività di spostamento dei dati .

    // create a pipeline
    Console.WriteLine("Creating a pipeline");
    DateTime PipelineActivePeriodStartTime = new DateTime(2014, 8, 9, 0, 0, 0, 0, DateTimeKind.Utc);
    DateTime PipelineActivePeriodEndTime = PipelineActivePeriodStartTime.AddMinutes(60);
    string PipelineName = "PipelineBlobSample";
    
    client.Pipelines.CreateOrUpdate(resourceGroupName, dataFactoryName,
    new PipelineCreateOrUpdateParameters()
    {
        Pipeline = new Pipeline()
        {
            Name = PipelineName,
            Properties = new PipelineProperties()
            {
                Description = "Demo Pipeline for data transfer between blobs",
    
                // Initial value for pipeline's active period. With this, you won't need to set slice status
                Start = PipelineActivePeriodStartTime,
                End = PipelineActivePeriodEndTime,
    
                Activities = new List<Activity>()
                {
                    new Activity()
                    {
                        Name = "BlobToBlob",
                        Inputs = new List<ActivityInput>()
                        {
                            new ActivityInput()
                {
                                Name = Dataset_Source
                            }
                        },
                        Outputs = new List<ActivityOutput>()
                        {
                            new ActivityOutput()
                            {
                                Name = Dataset_Destination
                            }
                        },
                        TypeProperties = new CopyActivity()
                        {
                            Source = new BlobSource(),
                            Sink = new BlobSink()
                            {
                                WriteBatchSize = 10000,
                                WriteBatchTimeout = TimeSpan.FromMinutes(10)
                            }
                        }
                    }
    
                },
            }
        }
    });
    
  12. Aggiungere al metodo Main il codice seguente per ottenere lo stato di una sezione di dati del set di dati di output. In questo esempio è prevista solo una sezione.

    // Pulling status within a timeout threshold
    DateTime start = DateTime.Now;
    bool done = false;
    
    while (DateTime.Now - start < TimeSpan.FromMinutes(5) && !done)
    {
        Console.WriteLine("Pulling the slice status");
        // wait before the next status check
        Thread.Sleep(1000 * 12);
    
        var datalistResponse = client.DataSlices.List(resourceGroupName, dataFactoryName, Dataset_Destination,
            new DataSliceListParameters()
            {
                DataSliceRangeStartTime = PipelineActivePeriodStartTime.ConvertToISO8601DateTimeString(),
                DataSliceRangeEndTime = PipelineActivePeriodEndTime.ConvertToISO8601DateTimeString()
            });
    
        foreach (DataSlice slice in datalistResponse.DataSlices)
        {
            if (slice.State == DataSliceState.Failed || slice.State == DataSliceState.Ready)
            {
                Console.WriteLine("Slice execution is done with status: {0}", slice.State);
                done = true;
                break;
            }
            else
            {
                Console.WriteLine("Slice status is: {0}", slice.State);
            }
        }
    }
    
  13. (facoltativo) Aggiungere al metodo Main il codice seguente per ottenere i dettagli dell'esecuzione di una sezione di dati.

    Console.WriteLine("Getting run details of a data slice");
    
    // give it a few minutes for the output slice to be ready
    Console.WriteLine("\nGive it a few minutes for the output slice to be ready and press any key.");
    Console.ReadKey();
    
    var datasliceRunListResponse = client.DataSliceRuns.List(
        resourceGroupName,
        dataFactoryName,
        Dataset_Destination,
        new DataSliceRunListParameters()
        {
            DataSliceStartTime = PipelineActivePeriodStartTime.ConvertToISO8601DateTimeString()
        });
    
    foreach (DataSliceRun run in datasliceRunListResponse.DataSliceRuns)
    {
        Console.WriteLine("Status: \t\t{0}", run.Status);
        Console.WriteLine("DataSliceStart: \t{0}", run.DataSliceStart);
        Console.WriteLine("DataSliceEnd: \t\t{0}", run.DataSliceEnd);
        Console.WriteLine("ActivityId: \t\t{0}", run.ActivityName);
        Console.WriteLine("ProcessingStartTime: \t{0}", run.ProcessingStartTime);
        Console.WriteLine("ProcessingEndTime: \t{0}", run.ProcessingEndTime);
        Console.WriteLine("ErrorMessage: \t{0}", run.ErrorMessage);
    }
    
    Console.WriteLine("\nPress any key to exit.");
    Console.ReadKey();
    
  14. Aggiungere alla classe Program il metodo helper seguente usato per il metodo Main. Questo metodo visualizza una finestra di dialogo che consente di specificare il nome utente e la password usati per accedere al portale di Azure.

    public static async Task<string> GetAuthorizationHeader()
    {
        AuthenticationContext context = new AuthenticationContext(ConfigurationManager.AppSettings["ActiveDirectoryEndpoint"] + ConfigurationManager.AppSettings["ActiveDirectoryTenantId"]);
        ClientCredential credential = new ClientCredential(
            ConfigurationManager.AppSettings["ApplicationId"],
            ConfigurationManager.AppSettings["Password"]);
        AuthenticationResult result = await context.AcquireTokenAsync(
            resource: ConfigurationManager.AppSettings["WindowsManagementUri"],
            clientCredential: credential);
    
        if (result != null)
            return result.AccessToken;
    
        throw new InvalidOperationException("Failed to acquire token");
    }
    
  15. In Esplora soluzioni espandere il progetto DataFactoryAPITestApp, fare clic con il pulsante destro del mouse su Riferimenti e scegliere Aggiungi riferimento. Selezionare la casella di controllo per l'assembly System.Configuration e fare clic su OK.

  16. Compilare l'applicazione console. Scegliere Compila dal menu e fare clic su Compila soluzione.
  17. Verificare che esista almeno un file nel contenitore adftutorial nell'archiviazione BLOB di Azure. In caso contrario, creare il file Emp.txt nel Blocco note con il contenuto seguente e caricarlo nel contenitore adftutorial.

    John, Doe
    Jane, Doe
    
  18. Eseguire l'esempio scegliendo Debug -> Avvia debug dal menu. Quando viene visualizzato un messaggio simile ad Acquisizione dettagli dell'esecuzione di una sezione di dati, attendere qualche minuto e premere INVIO.
  19. Usare il portale di Azure per verificare che la data factory APITutorialFactory venga creata con gli elementi seguenti:
    • Servizio collegato: AzureStorageLinkedService
    • Set di dati: DatasetBlobSource e DatasetBlobDestination.
    • Pipeline: PipelineBlobSample
  20. Verificare che venga creato un file di output nella cartella apifactoryoutput nel contenitore adftutorial.

Ottenere un elenco di sezioni di dati non riusciti

// Parse the resource path
var ResourceGroupName = "ADFTutorialResourceGroup";
var DataFactoryName = "DataFactoryAPITestApp";

var parameters = new ActivityWindowsByDataFactoryListParameters(ResourceGroupName, DataFactoryName);
parameters.WindowState = "Failed";
var response = dataFactoryManagementClient.ActivityWindows.List(parameters);
do
{
    foreach (var activityWindow in response.ActivityWindowListResponseValue.ActivityWindows)
    {
        var row = string.Join(
            "\t",
            activityWindow.WindowStart.ToString(),
            activityWindow.WindowEnd.ToString(),
            activityWindow.RunStart.ToString(),
            activityWindow.RunEnd.ToString(),
            activityWindow.DataFactoryName,
            activityWindow.PipelineName,
            activityWindow.ActivityName,
            string.Join(",", activityWindow.OutputDatasets));
        Console.WriteLine(row);
    }

    if (response.NextLink != null)
    {
        response = dataFactoryManagementClient.ActivityWindows.ListNext(response.NextLink, parameters);
    }
    else
    {
        response = null;
    }
}
while (response != null);

Passaggi successivi

Vedere l'esempio seguente per la creazione di una pipeline mediante .NET SDK che copia i dati da un archivio BLOB di Azure a un database SQL Azure: