Delen via

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

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

Vereiste voorwaarden

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

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.

Stap 1: een Azure Cosmos DB-account maken

Maak een Azure Cosmos DB for NoSQL-account vanuit Azure Portal of maak het account 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: Ontvang de inloggegevens van uw Azure Cosmos DB-account

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 te volgen:

  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.

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

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

Begin met het overschrijven van de standaardmethode Main en het definiëren van de globale variabelen. Deze globale variabelen omvatten 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, kunnen ze in feite onveranderbaar zijn voor de levensduur van cosmosClient. Het wijzigen van de waarden heeft geen effect.

Nadat de bulkuitvoering is ingeschakeld, worden in de CosmosClient intern gelijktijdige bewerkingen gegroepeerd in enkele serviceaanroepen. Hierdoor wordt het gebruik van de doorvoercapaciteit geoptimaliseerd door serviceaanroepen over partities te verdelen en uiteindelijk individuele resultaten toe te wijzen aan de oorspronkelijke aanroepers.

U kunt vervolgens een container maken om alle items op te slaan. Definieer /pk als de partitiesleutel, 50000 RU/s als ingerichte doorvoer en een aangepast indexeringsbeleid dat alle velden uitsluit 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 om een lijst met items uit ons gegevensmodel te genereren. 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 Item klasse definiëren in het Program.cs-bestand :

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 helperfunctie wordt het aantal items opgehaald dat u hebt gedefinieerd om willekeurige gegevens in te voegen en te genereren:

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 (dat bulksgewijs is) zoals beschreven in de inleidingssectie.

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

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.