Démarrage rapide : Créer une fabrique de données et un pipeline avec le kit .NET SDK

S’APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Ce guide de démarrage rapide explique comment utiliser le SDK .NET pour créer une fabrique de données Azure. Le pipeline que vous créez dans cette fabrique de données copie les données d’un dossier vers un autre dossier dans un stockage Blob Azure. Pour suivre un tutoriel sur la transformation des données à l’aide d’Azure Data Factory, consultez Tutoriel : Transformer des données à l’aide de Spark.

Notes

Cet article ne fournit pas de présentation détaillée du service Data Factory. Pour une présentation du service Azure Data Factory, consultez Présentation d’Azure Data Factory.

Prérequis

Abonnement Azure

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Rôles Azure

Pour créer des instances Data Factory, le compte d’utilisateur que vous utilisez pour vous connecter à Azure doit être membre des rôles Contributeur ou Propriétaire, ou administrateur de l’abonnement Azure. Pour voir les autorisations dont vous disposez dans l’abonnement, accédez au portail Azure, sélectionnez votre nom d’utilisateur en haut à droite, sélectionnez l’icône « ... » pour plus d’options, puis sélectionnez Mes autorisations. Si vous avez accès à plusieurs abonnements, sélectionnez l’abonnement approprié.

Les exigences applicables à la création et à la gestion des ressources enfants pour Data Factory (jeux de données, services liés, pipelines, déclencheurs et runtimes d’intégration) sont les suivantes :

  • Pour créer et gérer des ressources enfants dans le Portail Azure, vous devez appartenir au rôle Contributeurs de Data Factory au niveau du groupe de ressources ou à un niveau supérieur.
  • Pour créer et gérer des ressources enfants à l’aide de PowerShell ou du Kit de développement logiciel (SDK), le rôle Contributeur au niveau du groupe de ressources ou à un niveau supérieur est suffisant.

Pour découvrir des exemples d’instructions concernant l’ajout d’un utilisateur à un rôle, consultez l’article décrivant comment ajouter des rôles.

Pour plus d’informations, consultez les articles suivants :

Compte de Stockage Azure

Dans ce guide de démarrage rapide, vous utilisez un compte de Stockage Azure (plus précisément, un compte de Stockage Blob) à usage général à la fois comme magasins de données source et de destination. Si vous ne possédez pas de compte de Stockage Azure à usage général, consultez Créer un compte de stockage pour en créer un.

Obtenir le nom du compte de stockage

Pour ce guide de démarrage rapide, vous avez besoin du nom de votre compte de Stockage Azure. La procédure suivante détaille les étapes à suivre pour obtenir le nom de votre compte de stockage :

  1. Dans un navigateur web, accédez au portail Azure et connectez-vous à l’aide de vos nom d’utilisateur et mot de passe Azure.
  2. Dans le menu Portail Azure, sélectionnez Tous les services, puis sélectionnez Stockage>Comptes de stockage. Vous pouvez également rechercher et sélectionner Comptes de stockage à partir de n’importe quelle page.
  3. Dans la page Comptes de stockage, appliquez un filtre pour votre compte de stockage (si nécessaire), puis sélectionnez votre compte de stockage.

Vous pouvez également rechercher et sélectionner Comptes de stockage à partir de n’importe quelle page.

Création d’un conteneur d’objets blob

Dans cette section, vous allez créer un conteneur d’objets blob nommé adftutorial dans un stockage Blob Azure.

  1. Dans la page du compte de stockage, sélectionnez Présentation>Conteneurs.

  2. Dans la barre d’outils de la page <Nom du compte> - Conteneurs, sélectionnez Conteneur.

  3. Dans la boîte de dialogue Nouveau conteneur, saisissez le nom adftutorial, puis sélectionnez OK. La page <Nom du compte> - Conteneurs est mise à jour pour inclure adftutorial dans la liste des conteneurs.

    Liste des conteneurs

Ajouter un dossier et un fichier d’entrée pour le conteneur d’objets blob

Dans cette section, vous créez un dossier nommé input (entrée) dans le conteneur que vous avez créé, puis chargez un exemple de fichier dans ce dossier. Avant de commencer, ouvrez un éditeur de texte tel que Bloc-notes, puis créez un fichier nommé emp.txt avec le contenu suivant :

John, Doe
Jane, Doe

Enregistrez-le dans le dossier C:\ADFv2QuickStartPSH (si le dossier n’existe pas, créez-le). Revenez ensuite au portail Azure et procédez comme suit :

  1. Dans la page <Nom du compte> - Conteneurs, là où vous vous êtes arrêté, sélectionnez adftutorial dans la liste mise à jour des conteneurs.

    1. Si vous avez fermé la fenêtre ou accédé à une autre page, connectez-vous au Portail Azure à nouveau.
    2. Dans le menu Portail Azure, sélectionnez Tous les services, puis sélectionnez Stockage>Comptes de stockage. Vous pouvez également rechercher et sélectionner Comptes de stockage à partir de n’importe quelle page.
    3. Sélectionnez votre compte de stockage, puis sélectionnez Conteneurs>adftutorial.
  2. Dans la barre d’outils de la page du conteneur adftutorial, sélectionnez Charger.

  3. Dans la page Charger l’objet blob, sélectionnez la zone Fichiers, puis recherchez et sélectionnez le fichier emp.txt.

  4. Développez le titre Avancé. La page s’affiche à présent comme indiqué :

    Sélectionner le lien Avancé

  5. Dans la zone Charger dans le dossier, entrez input.

  6. Cliquez sur le bouton Charger. Vous devriez voir le fichier emp.txt et l’état du chargement dans la liste.

  7. Sélectionnez l’icône Fermer (X) pour fermer la page Charger l’objet blob.

Laissez la page du conteneur adftutorial ouverte. Vous l’utiliserez pour vérifier la sortie à la fin de ce guide de démarrage rapide.

Visual Studio

La procédure pas à pas décrite dans cet article utilise Visual Studio 2019. Les procédures pour Visual Studio 2013, 2015 ou 2017 diffèrent légèrement.

Créer une application dans Azure Active Directory

Dans les sections de la rubrique Procédure : Utiliser le portail pour créer une application et un principal du service Azure AD pouvant accéder aux ressources, suivez les instructions pour effectuer ces tâches :

  1. Dans Créer une application Azure Active Directory, créez une application qui représente l’application .NET que vous créez dans ce didacticiel. Pour l’URL de connexion, vous pouvez fournir une URL factice, comme indiqué dans l’article (https://contoso.org/exampleapp).
  2. Dans Obtenir les valeurs pour la connexion, récupérez l’ID d’application et l’ID de locataire, puis notez ces valeurs que vous allez utiliser ultérieurement dans ce didacticiel.
  3. Dans Certificats et secrets, récupérez la clé d’authentification, puis notez cette valeur que vous allez utiliser ultérieurement dans ce didacticiel.
  4. Dans Affecter l’application à un rôle, affectez l’application au rôle Contributeur au niveau de l’abonnement de sorte que l’application puisse créer des fabriques de données dans l’abonnement.

Créer un projet Visual Studio

Créez ensuite une application console .NET en C# dans Visual Studio :

  1. Lancez Visual Studio.
  2. Dans la fenêtre Démarrer, sélectionnez Créer un projet>Application console (.NET Framework) . .NET version 4.5.2 ou ultérieure est nécessaire.
  3. Dans Nom du projet, entrez ADFv2QuickStart.
  4. Sélectionnez Créer pour créer le projet.

Installer les packages NuGet

  1. Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package.

  2. Dans le volet Console du Gestionnaire de package, exécutez les commandes suivantes pour installer les packages. Pour plus d’informations, voir Package NuGet Microsoft.Azure.Management.DataFactory.

    Install-Package Microsoft.Azure.Management.DataFactory
    Install-Package Microsoft.Azure.Management.ResourceManager -IncludePrerelease
    Install-Package Microsoft.Identity.Client
    

Créer un client de fabrique de données

  1. Ouvrez Program.cs, insérez les instructions suivantes pour ajouter des références aux espaces de noms.

    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.Identity.Client;
    
  2. Ajoutez le code suivant à la méthode Main qui définit les variables. Remplacez les espaces réservés par vos valeurs. Pour obtenir la liste des régions Azure dans lesquelles Data Factory est actuellement disponible, sélectionnez les régions qui vous intéressent dans la page suivante, puis développez Analytique pour localiser Data Factory : Disponibilité des produits par région. Les magasins de données (Stockage Azure, Azure SQL Database, etc.) et les services de calcul (HDInsight et autres) utilisés par la fabrique de données peuvent être situés dans d’autres régions.

    // 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";
    

Notes

Concernant les clouds souverains, vous devez utiliser les points de terminaison spécifiques au cloud appropriés pour ActiveDirectoryAuthority et ResourceManagerUrl (BaseUri). Par exemple, dans Azure US Gov, vous utiliseriez l'autorité de https://login.microsoftonline.us au lieu de https://login.microsoftonline.com, et vous utiliseriez https://management.usgovcloudapi.net au lieu de https://management.azure.com/, puis vous créeriez le client de gestion de fabrique de données. Vous pouvez utiliser PowerShell pour obtenir facilement les URL des points de terminaison de différents clouds en exécutant « Get-AzEnvironment | Format-List », qui renverra une liste de points de terminaison pour chaque environnement cloud.

  1. Ajoutez le code suivant à la méthode Main qui crée une instance de la classe DataFactoryManagementClient. Cet objet vous permet de créer une fabrique de données, un service lié, des jeux de données ainsi qu’un pipeline. Cet objet vous permet également de surveiller les détails de l’exécution du pipeline.

    // Authenticate and create a data factory management client
    IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(applicationId)
     .WithAuthority("https://login.microsoftonline.com/" + tenantID)
     .WithClientSecret(authenticationKey)
     .WithLegacyCacheCompatibility(false)
     .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
     .Build();
    
    AuthenticationResult result = await app.AcquireTokenForClient(
      new string[]{ "https://management.azure.com//.default"})
       .ExecuteAsync();
    ServiceClientCredentials cred = new TokenCredentials(result.AccessToken);
    var client = new DataFactoryManagementClient(cred) {
        SubscriptionId = subscriptionId };
    

Créer une fabrique de données

Ajoutez le code suivant à la méthode Main qui crée une fabrique de données.

// 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);
}

Créer un service lié

Ajoutez le code suivant à la méthode Main qui crée un service lié Stockage Azure.

Vous allez créer des services liés dans une fabrique de données pour lier vos magasins de données et vos services de calcul à la fabrique de données. Dans ce guide de démarrage rapide, vous devez uniquement créer un service lié Stockage Azure à la fois pour la source de copie et le magasin récepteur, nommé « AzureStorageLinkedService » dans l’exemple.

// 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));

Créer un jeu de données

Ajoutez le code suivant à la méthode Main qui crée un jeu de données d’objet blob Azure.

Vous définissez un jeu de données qui représente les données à copier d’une source vers un récepteur. Dans cet exemple, ce jeu de données d’objet blob fait référence au service lié Stockage Azure que vous avez créé à l’étape précédente. Le jeu de données prend un paramètre dont la valeur est définie dans une activité qui consomme le jeu de données. Le paramètre est utilisé pour construire le « FolderPath » pointant vers l’emplacement où les données sont stockées.

// 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));

Créer un pipeline

Ajoutez le code suivant à la méthode Main qui crée un pipeline avec une activité de copie.

Dans cet exemple, ce pipeline contient une activité et accepte deux paramètres : le chemin de l’objet blob d’entrée et le chemin de l’objet blob de sortie. Les valeurs de ces paramètres sont définies quand le pipeline est déclenché/exécuté. L’activité de copie fait référence au même jeu de données d’objet blob créé à l’étape précédente comme entrée et sortie. Quand le jeu de données est utilisé comme jeu de données d’entrée, le chemin d’entrée est spécifié. De même, quand le jeu de données est utilisé comme jeu de données de sortie, le chemin de sortie est spécifié.

// 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));

Créer une exécution du pipeline

Ajoutez le code suivant à la méthode Main qui déclenche une exécution du pipeline.

Ce code définit également les valeurs des paramètres inputPath et outputPath spécifiés dans le pipeline avec les valeurs réelles des chemins des objets blob source et récepteur.

// 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);

Surveiller une exécution du pipeline

  1. Ajoutez le code suivant à la méthode Main afin de vérifier continuellement l’état jusqu’à la fin de la copie des données.

    // 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. Ajoutez le code suivant à la méthode Main qui récupère les détails de l’exécution de l’activité de copie, tels que la taille des données lues ou écrites.

    // 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();
    

Exécuter le code

Créez et démarrez l’application, puis vérifiez l’exécution du pipeline.

La console affiche la progression de la création de la fabrique de données, du service lié, des jeux de données, du pipeline et de l’exécution du pipeline. Elle vérifie ensuite l’état de l’exécution du pipeline. Patientez jusqu’à voir les détails de l’exécution de l’activité de copie avec la taille des données lues/écrites. Utilisez ensuite des outils comme l’Explorateur Stockage Azure pour vérifier que les objets blob sont copiés dans « outputBlobPath » depuis « inputBlobPath » comme vous l’avez spécifié dans les variables.

Exemple de sortie

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

Vérifier la sortie

Le pipeline crée automatiquement le dossier de sortie dans le conteneur d’objets blob adftutorial. Ensuite, il copie le fichier emp.txt à partir du dossier d’entrée dans le dossier de sortie.

  1. Sur le portail Azure, dans la page de conteneur adftutorial que vous avez arrêtée dans la section Ajouter un dossier et un fichier d’entrée pour le conteneur d’objets blob ci-dessus, sélectionnez Actualiser pour voir le dossier de sortie.
  2. Dans la liste des dossiers, sélectionnez sortie.
  3. Vérifiez que le fichier emp.txt a été copié dans le dossier de sortie.

Nettoyer les ressources

Pour supprimer par programmation la fabrique de données, ajoutez les lignes de code suivantes au programme :

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

Étapes suivantes

Dans cet exemple, le pipeline copie les données d’un emplacement vers un autre dans un stockage Blob Azure. Consultez les didacticiels pour en savoir plus sur l’utilisation de Data Factory dans d’autres scénarios.