Delen via

Gegevens bulksgewijs importeren in een Azure Cosmos DB for NoSQL-account met behulp van de .NET SDK

  • Artikel

VAN TOEPASSING OP: NoSQL

Deze zelfstudie laat zien hoe u een .NET-consoletoepassing bouwt waarmee de ingerichte doorvoer (RU/s) die nodig is voor het importeren van gegevens in Azure Cosmos DB, wordt geoptimaliseerd.

In dit artikel leest u gegevens uit een voorbeeldgegevensbron en importeert u deze in een Azure Cosmos DB-container. In deze zelfstudie wordt gebruikgemaakt van versie 3.0+ van de Azure Cosmos DB .NET SDK. Deze is gericht op .NET Framework of .NET Core.

In deze zelfstudie komt het volgende aan bod:

  • Een Azure Cosmos DB-account maken
  • Uw project configureren
  • Verbinding maken met een Azure Cosmos DB-account waarvoor bulkondersteuning is ingeschakeld
  • Een gegevensimport uitvoeren met gelijktijdige maakbewerkingen

Vereisten

Voordat u de instructies in dit artikel uitvoert, moet u zorgen dat u beschikt over de volgende resources:

Stap 1: een Azure Cosmos DB-account maken

Maak een Azure Cosmos DB for NoSQL-account vanuit Azure Portal of u kunt het account maken met behulp van de Azure Cosmos DB Emulator.

Stap 2: Uw .NET-project instellen

Open de Windows-opdrachtprompt of een Terminalvenster op uw lokale computer. U voert alle opdrachten in de volgende secties uit vanaf de opdrachtprompt of terminal. Voer de volgende nieuwe DotNet-opdracht uit om een nieuwe app te maken met de naam bulk-import-demo.

dotnet new console -n bulk-import-demo

Wijzig uw map in de zojuist gemaakte app-map. U kunt de toepassing maken met:

cd bulk-import-demo
dotnet build

De verwachte uitvoer van de build moet er ongeveer als volgt uitzien:

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

Stap 3: Het Azure Cosmos DB-pakket toevoegen

Terwijl u zich nog in de toepassingsmap bevindt, installeert u de Azure Cosmos DB-clientbibliotheek voor .NET Core met behulp van de DotNet-opdracht pakket toevoegen.

dotnet add package Microsoft.Azure.Cosmos

Stap 4: De referenties van uw Azure Cosmos DB-account ophalen

De voorbeeldtoepassing moet worden geverifieerd bij uw Azure Cosmos DB-account. Als u zich wilt verifiëren, moet u de referenties van het Azure Cosmos DB-account doorgeven aan de toepassing. Haal de referenties van uw Azure Cosmos DB-account op door de volgende stappen uit te voeren:

  1. Meld u aan bij het Azure-portaal.
  2. Navigeer naar uw Azure Cosmos DB-account.
  3. Open het deelvenster Sleutels en kopieer de URI en PRIMAIRE SLEUTEL van uw account.

Als u de Azure Cosmos DB Emulator gebruikt, haalt u de referenties van de emulator op uit dit artikel.

Stap 5: Het CosmosClient-object initialiseren met ondersteuning voor bulkuitvoering

Open het gegenereerde Program.cs-bestand in een code-editor. U maakt een nieuw exemplaar van CosmosClient waarvoor bulkuitvoering is ingeschakeld en gebruikt om bewerkingen uit te voeren op Azure Cosmos DB.

Laten we beginnen met het overschrijven van de standaardmethode Main en het definiëren van de globale variabelen. Deze globale variabelen bevatten het eindpunt en de autorisatiesleutels, de naam van de database, de container die u maakt en het aantal items dat u bulksgewijs invoegt. Zorg ervoor dat u de waarden voor de eindpunt-URL en de autorisatiesleutel vervangt naar aanleiding van uw omgeving.

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)
     {

     }
}

Voeg in de methode Main de volgende code toe om het CosmosClient-object te initialiseren:

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

Notitie

Zodra bulkuitvoering is opgegeven in De CosmosClientOptions, zijn ze effectief onveranderbaar voor de levensduur van de CosmosClient. Het wijzigen van de waarden heeft geen effect.

Nadat de bulkuitvoering is ingeschakeld, worden in de CosmosClient intern gelijktijdige bewerkingen gegroepeerd in afzonderlijke serviceaanroepen. Op deze manier wordt het gebruik van de doorvoer geoptimaliseerd door serviceaanroepen over partities te verdelen en uiteindelijk afzonderlijke resultaten toe te wijzen aan de oorspronkelijke oproepende functies.

U kunt vervolgens een container maken om alle items op te slaan. Definieer /pk als de partitiesleutel, 50.000 RU/s als ingerichte doorvoer en een aangepast indexeringsbeleid waarmee alle velden worden uitgesloten om de schrijfdoorvoer te optimaliseren. Voeg de volgende code toe na de CosmosClient-initialisatie-instructie:

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

Stap 6: Een lijst met gelijktijdige taken vullen

Als u de ondersteuning voor bulkuitvoering wilt benutten, maakt u een lijst met asynchrone taken op basis van de gegevensbron en de bewerkingen die u wilt uitvoeren, en gebruikt u Task.WhenAll om deze gelijktijdig uit te voeren. Laten we beginnen met het gebruik van 'Bogus'-gegevens voor het genereren van een lijst met items uit ons gegevensmodel. In een echte toepassing zijn de items afkomstig uit de gewenste gegevensbron.

Voeg eerst het pseudopakket aan de oplossing toe met behulp van de DotNet-opdracht pakket toevoegen.

dotnet add package Bogus

Definieer de definitie van de items die u wilt opslaan. U moet de klasse Item in het bestand Program.cs definiëren:

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

    public string username{get;set;}
}

Maak vervolgens een Help-functie binnen de klasse Program. Met deze Help-functie wordt het gedefinieerde aantal in te voegen items opgehaald en worden willekeurige gegevens gegenereerd:

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

Gebruik de helperfunctie om een lijst met documenten te initialiseren waarmee u kunt werken:

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

Gebruik vervolgens de lijst met documenten om gelijktijdige taken te maken en de takenlijst te vullen om de items in de container in te voegen. Als u deze bewerking wilt uitvoeren, voegt u de volgende code toe aan de klasse 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);

Al deze gelijktijdige puntbewerkingen worden samen uitgevoerd (in bulk), zoals beschreven in de inleidende sectie.

Stap 7: Het voorbeeld uitvoeren

Als u de voorbeeldtoepassing wilt uitvoeren, kunt u dit gewoon doen met de dotnet-opdracht:

dotnet run

De volledige voorbeeldtoepassing ophalen

Als u geen tijd hebt gehad om de stappen in deze zelfstudie uit te voeren of als u alleen de codevoorbeelden wilt downloaden, kunt u deze ophalen van GitHub.

Nadat het project is gekloond, moet u de gewenste referenties in Program.cs bijwerken.

De voorbeeldtoepassing kan worden uitgevoerd door naar de map van de opslagplaats te gaan en met behulp van dotnet:

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

Volgende stappen

In deze zelfstudie hebt u de volgende stappen uitgevoerd:

  • Een Azure Cosmos DB-account maken
  • Uw project configureren
  • Verbinding maken met een Azure Cosmos DB-account waarvoor bulkondersteuning is ingeschakeld
  • Een gegevensimport uitvoeren met gelijktijdige maakbewerkingen

U kunt nu verdergaan met de volgende zelfstudie:

Query's uitvoeren op Azure Cosmos DB met behulp van de API voor NoSQL

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.