Importer des données en bloc dans un compte Azure Cosmos DB for NoSQL à l’aide du kit SDK .NET

  • Article

S’APPLIQUE À : NoSQL

Ce tutoriel vous montre comment créer une application console .NET qui optimise le débit approvisionné (RU/s) requis pour importer des données dans Azure Cosmos DB.

Dans cet article, vous allez lire des données à partir d’un exemple de source de données et les importer dans un conteneur Azure Cosmos DB. Ce tutoriel utilise la Version 3.0+ du kit de développement logiciel (SDK) .NET Azure Cosmos DB, qui peut être ciblé sur le .NET Framework ou .NET Core.

Ce didacticiel contient les sections suivantes :

  • Création d’un compte Azure Cosmos DB
  • Configuration de votre projet
  • Connexion à un compte Azure Cosmos DB avec prise en charge de l’exécution en bloc activée
  • Effectuer une importation de données via des opérations de création simultanées

Prérequis

Avant de suivre les instructions de cet article, vérifiez que vous disposez bien des ressources suivantes :

Étape 1 : Création d’un compte Azure Cosmos DB

Créez un compte Azure Cosmos DB for NoSQL à partir du portail Azure ou à l’aide de l’émulateur Azure Cosmos DB.

Étape 2 : Configurer votre projet .NET

Ouvrez l’invite de commandes Windows ou une fenêtre de terminal à partir de votre ordinateur local. Vous allez exécuter toutes les commandes des sections suivantes à partir de l’invite de commandes ou du terminal. Exécutez la commande dotnet new suivante pour créer une application nommée bulk-import-demo.

dotnet new console -n bulk-import-demo

Déplacez vos répertoires vers le dossier d’application nouvellement créé. Vous pouvez générer l’application avec :

cd bulk-import-demo
dotnet build

La sortie attendue de la build doit ressembler à ceci :

Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo\bulk-import-demo.csproj.
  bulk -> C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo \bin\Debug\netcoreapp2.2\bulk-import-demo.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Étape 3 : Ajouter le package Azure Cosmos DB

Tout en restant dans le répertoire de l’application, installez la bibliothèque de client Azure Cosmos DB pour .NET Core à l’aide de la commande dotnet add Package.

dotnet add package Microsoft.Azure.Cosmos

Étape 4 : Obtenir les informations d’identification de votre compte Azure Cosmos DB

L’exemple d’application doit s’authentifier auprès de votre compte Azure Cosmos DB. Pour vous authentifier, vous devez transmettre les informations d’identification du compte Azure Cosmos DB à l’application. Pour obtenir les informations d’identification de votre compte Azure Cosmos DB, procédez comme suit :

  1. Connectez-vous au portail Azure.
  2. Accédez à votre compte Azure Cosmos DB.
  3. Ouvrez le volet Clés et copiez l’URI et la CLÉ PRIMAIRE de votre compte.

Si vous utilisez l’émulateur Azure Cosmos DB, obtenez les informations d’identification à partir de cet article.

Étape 5 : Initialiser l’objet CosmosClient avec prise en charge de l’exécution en bloc

Ouvrez le fichier Program.cs généré dans un éditeur de code. Vous allez créer une nouvelle instance CosmosClient avec l’exécution en bloc activée et l’utiliser pour effectuer des opérations sur Azure Cosmos DB.

Commencez par remplacer la méthode Main par défaut et définir les variables globales. Ces variables globales incluront le point de terminaison, les clés d’autorisation, le nom de la base de données, le conteneur que vous créez ainsi que le nombre d’éléments que vous allez insérer en bloc. Veillez à remplacer les valeurs correspondant à endpointURL et aux clés d’autorisation en fonction de votre environnement.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

public class Program
{
     private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
     private const string AuthorizationKey = "<your-account-key>";
     private const string DatabaseName = "bulk-tutorial";
     private const string ContainerName = "items";
     private const int AmountToInsert = 300000;

     static async Task Main(string[] args)
     {

     }
}

Dans la méthode Main, ajoutez le code suivant pour initialiser l’objet CosmosClient :

CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey, new CosmosClientOptions() { AllowBulkExecution = true });

Notes

Une fois l’exécution en bloc spécifiée dans CosmosClientOptions, elles sont effectivement immuables pour la durée de vie du CosmosClient. La modification des valeurs n’aura aucun effet.

Une fois l’exécution en bloc activée, CosmosClient regroupe en interne les opérations simultanées en appels de service unique. Ainsi, il optimise l’utilisation du débit en distribuant les appels de service entre les partitions, puis en attribuant les résultats individuels aux appelants d’origine.

Vous pouvez ensuite créer un conteneur pour stocker tous les éléments. Définissez /pk en tant que clé de partition, 50 000 RU/s en tant que débit approvisionné, et une stratégie d’indexation personnalisée qui exclut tous les champs afin d'optimiser le débit d’écriture. Ajoutez le code suivant après l’instruction d’initialisation CosmosClient :

Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseName);

await database.DefineContainer(Program.ContainerName, "/pk")
        .WithIndexingPolicy()
            .WithIndexingMode(IndexingMode.Consistent)
            .WithIncludedPaths()
                .Attach()
            .WithExcludedPaths()
                .Path("/*")
                .Attach()
        .Attach()
    .CreateAsync(50000);

Étape 6 : Remplir une liste de tâches simultanées

Pour bénéficier de la prise en charge de l’exécution en bloc, créez une liste de tâches asynchrones en fonction de la source de données et des opérations que vous souhaitez effectuer, puis utilisez Task.WhenAll pour les exécuter simultanément. Commencez par utiliser des données « fictives » pour générer une liste d’éléments à partir du modèle de données. Dans une application réelle, les éléments proviennent de la source de données souhaitée.

Tout d’abord, ajoutez le package fictif à la solution à l’aide de la commande dotnet add package.

dotnet add package Bogus

Définissez les éléments que vous souhaitez enregistrer. Vous devez définir la classe Item dans le fichier Program.cs :

public class Item
{
    public string id {get;set;}
    public string pk {get;set;}

    public string username{get;set;}
}

Ensuite, créez une fonction d’assistance au sein la classe Program. Cette fonction d’assistance obtient le nombre d’éléments que vous avez définis à des fins d'insertion et génère des données aléatoires :

private static IReadOnlyCollection<Item> GetItemsToInsert()
{
    return new Bogus.Faker<Item>()
    .StrictMode(true)
    //Generate item
    .RuleFor(o => o.id, f => Guid.NewGuid().ToString()) //id
    .RuleFor(o => o.username, f => f.Internet.UserName())
    .RuleFor(o => o.pk, (f, o) => o.id) //partitionkey
    .Generate(AmountToInsert);
}

Utilisez la fonction d’assistance pour initialiser une liste de documents à utiliser :

IReadOnlyCollection<Item> itemsToInsert = Program.GetItemsToInsert();

Utilisez ensuite la liste de documents pour créer des tâches simultanées et remplissez la liste des tâches afin d’insérer les éléments dans le conteneur. Pour effectuer cette opération, ajoutez le code suivant à la classe Program :

Container container = database.GetContainer(ContainerName);
List<Task> tasks = new List<Task>(AmountToInsert);
foreach (Item item in itemsToInsert)
{
    tasks.Add(container.CreateItemAsync(item, new PartitionKey(item.pk))
        .ContinueWith(itemResponse =>
        {
            if (!itemResponse.IsCompletedSuccessfully)
            {
                AggregateException innerExceptions = itemResponse.Exception.Flatten();
                if (innerExceptions.InnerExceptions.FirstOrDefault(innerEx => innerEx is CosmosException) is CosmosException cosmosException)
                {
                    Console.WriteLine($"Received {cosmosException.StatusCode} ({cosmosException.Message}).");
                }
                else
                {
                    Console.WriteLine($"Exception {innerExceptions.InnerExceptions.FirstOrDefault()}.");
                }
            }
        }));
}

// Wait until all are done
await Task.WhenAll(tasks);

Toutes ces opérations de point simultanées sont exécutées ensemble (en bloc), comme décrit dans la section Introduction.

Étape 7 : Exécuter l’exemple

Pour exécuter l’exemple, vous pouvez tout simplement utiliser la commande dotnet :

dotnet run

Obtenir l'exemple complet

Si vous n’avez pas le temps de suivre les étapes de ce didacticiel, ou que vous voulez simplement télécharger les exemples de code, vous pouvez les obtenir à partir de GitHub.

Après avoir cloné le projet, assurez-vous de mettre à jour les informations d’identification souhaitées dans Program.cs.

Pour exécuter l'exemple, vous utilisez le répertoire du référentiel et dotnet :

cd cosmos-dotnet-bulk-import-throughput-optimizer
dotnet run

Étapes suivantes

Dans ce tutoriel, vous avez effectué les tâches suivantes :

  • Création d’un compte Azure Cosmos DB
  • Configuration de votre projet
  • Connexion à un compte Azure Cosmos DB avec prise en charge de l’exécution en bloc activée
  • Effectuer une importation de données via des opérations de création simultanées

Vous pouvez maintenant passer au tutoriel suivant :

Interroger Azure Cosmos DB à l’aide de l’API pour NoSQL

Vous tentez d’effectuer une planification de la capacité pour une migration vers Azure Cosmos DB ? Vous pouvez utiliser les informations sur votre cluster de bases de données existant pour la planification de la capacité.