Partager via

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

  • 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 les données à partir d’un échantillon de source de données pour ensuite les importer dans un conteneur Azure Cosmos DB.

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

Prerequisites

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

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.

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

Créez un compte Azure Cosmos DB for NoSQLà partir du Portail Azure ou créez le compte à l’aide de l’émulateurAzure 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, procurez-vous les informations d’identification de l’émulateur.

Étape 5 : Initialiser l’objet CosmosClient avec prise en charge du traitement en bloc

Ouvrez le fichier Program.cs généré dans un éditeur de code. Créez une nouvelle instance de CosmosClient avec l’exécution en bloc activée et utilisez-la 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 incluent les clés d’autorisation et de point de terminaison, le nom de la base de données, le conteneur que vous allez créer et 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 });

Note

Une fois que l’exécution en bloc est spécifiée dans les CosmosClientOptions, elles sont effectivement immuables pendant toute la durée de vie du CosmosClient. La modification des valeurs n’a 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. Pour optimiser le débit d’écriture, définissez /pk comme clé de partition, 50 000 RU/s comme débit provisionné et une stratégie d’indexation personnalisée qui exclut tous les champs. 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. Commençons par utiliser des données Fictives pour générer une liste d’éléments à partir de notre 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 récupère le nombre d’éléments que vous avez défini d’insérer 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 des documents pour créer des tâches simultanées et remplir 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 ponctuelles simultanées sont exécutées ensemble (c’est-à-dire 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, accédez au répertoire du référentiel et utilisez dotnet :

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

Étapes suivantes

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

  • Last updated on