Ausführen eines Massenimports von Daten in ein Azure Cosmos DB für NoSQL-Konto mithilfe des .NET SDK

  • Artikel

GILT FÜR: NoSQL

Dieses Tutorial enthält eine Beschreibung der Erstellung einer .NET-Konsolenanwendung, mit der der bereitgestellte Durchsatz (RU/s), der zum Importieren von Daten in Azure Cosmos DB benötigt wird, optimiert wird.

In diesem Artikel lesen Sie Daten aus einer Beispieldatenquelle und importieren diese in einen Azure Cosmos DB-Container. In diesem Tutorial wird mindestens Version 3.0 des Azure Cosmos DB .NET SDK verwendet, das auf .NET Framework oder .NET Core ausgerichtet werden kann.

In diesem Lernprogramm wird Folgendes behandelt:

  • Erstellen eines Azure Cosmos DB-Kontos
  • Konfigurieren des Projekts
  • Herstellen einer Verbindung mit einem Azure Cosmos DB-Konto mit aktivierter Unterstützung für Massenvorgänge
  • Durchführen eines Datenimports mit gleichzeitigen Erstellungsvorgängen

Voraussetzungen

Vergewissern Sie sich zunächst, dass Sie über die folgenden Ressourcen verfügen:

Schritt 1: Erstellen eines Azure Cosmos DB-Kontos

Erstellen Sie ein Azure Cosmos DB for NoSQL-Konto über das Azure-Portal, oder verwenden Sie hierfür den Azure Cosmos DB-Emulator.

Schritt 2: Einrichten des .NET-Projekts

Öffnen Sie auf Ihrem lokalen Computer die Windows-Eingabeaufforderung oder ein Terminalfenster. Sie führen alle Befehle in den nächsten Abschnitten über die Eingabeaufforderung oder das Terminal aus. Führen Sie den folgenden „dotnet new“-Befehl aus, um eine neue App mit dem Namen bulk-import-demo zu erstellen.

dotnet new console -n bulk-import-demo

Wechseln Sie zum Ordner der neu erstellten App. Sie können die Anwendung mit folgendem Befehl erstellen:

cd bulk-import-demo
dotnet build

Die erwartete Ausgabe aus dem Build sollte etwa wie folgt aussehen:

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

Schritt 3: Hinzufügen des Azure Cosmos DB-Pakets

Installieren Sie im Anwendungsverzeichnis mit dem Befehl „dotnet add package“ die Azure Cosmos DB-Clientbibliothek für .NET Core.

dotnet add package Microsoft.Azure.Cosmos

Schritt 4: Abrufen der Anmeldeinformationen für Ihr Azure Cosmos DB-Konto

Die Beispielanwendung muss sich bei Ihrem Azure Cosmos DB-Konto authentifizieren. Für die Authentifizierung müssen Sie die Anmeldeinformationen für das Azure Cosmos DB-Konto an die Anwendung übergeben. Führen Sie zum Abrufen der Anmeldeinformationen für Ihr Azure Cosmos DB-Konto die folgenden Schritte aus:

  1. Melden Sie sich beim Azure-Portal an.
  2. Navigieren Sie zu Ihrem Azure Cosmos DB-Konto.
  3. Öffnen Sie den Bereich Schlüssel, und kopieren Sie den URI und den PRIMÄRSCHLÜSSEL Ihres Kontos.

Wenn Sie den Azure Cosmos DB-Emulator nutzen, können Sie die Anmeldeinformationen für den Emulator in diesem Artikel verwenden.

Schritt 5: Initialisieren des CosmosClient-Objekts mit Unterstützung für Massenvorgänge

Öffnen Sie die generierte Datei Program.cs in einem Code-Editor. Sie erstellen eine neue Instanz von CosmosClient mit aktivierter Massenausführung und verwenden sie, um Vorgänge für Azure Cosmos DB durchzuführen.

Zunächst überschreiben Sie die Main-Standardmethode und definieren die globalen Variablen. Diese globalen Variablen enthalten den Endpunkt und die Autorisierungsschlüssel, den Namen der Datenbank, den von Ihnen erstellten Container und die Anzahl von Elementen, die Sie per Massenvorgang einfügen. Ersetzen Sie die Werte für endpointURL und den Autorisierungsschlüssel gemäß Ihrer Umgebung.

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

     }
}

Fügen Sie in der Main-Methode den folgenden Code hinzu, um das CosmosClient-Objekt zu initialisieren:

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

Hinweis

Sobald die Massenausführung in den CosmosClientOptions spezifiziert ist, sind sie für die Lebensdauer des CosmosClient praktisch unveränderlich. Das Ändern der Werte hat keine Auswirkung.

Nach der Aktivierung von Massenausführungen werden gleichzeitige Vorgänge von CosmosClient intern zu gemeinsamen Dienstaufrufen gruppiert. Auf diese Weise wird die Durchsatznutzung optimiert, indem Dienstaufrufe auf Partitionen verteilt werden, und einzelne Ergebnisse werden dann den ursprünglichen Aufrufern zugewiesen.

Anschließend können Sie einen Container erstellen, in dem alle Elemente gespeichert werden. Definieren Sie /pk als Partitionsschlüssel, 50.000 RU/s als bereitgestellten Durchsatz und eine benutzerdefinierte Indizierungsrichtlinie, mit der alle Felder ausgeschlossen werden, um den Schreibdurchsatz zu optimieren. Fügen Sie nach der CosmosClient-Initialisierungsanweisung den folgenden Code hinzu:

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

Schritt 6: Auffüllen einer Liste mit gleichzeitigen Aufgaben

Erstellen Sie zum Nutzen der Unterstützung für Massenausführungen eine Liste mit asynchronen Aufgaben, die auf der Quelle der Daten und den durchzuführenden Vorgängen basiert, und verwenden Sie Task.WhenAll für die gleichzeitige Ausführung. Zunächst verwenden wir „falsche“ Daten, um aus unserem Datenmodell eine Liste mit Elementen zu generieren. In einer realen Anwendung stammen die Elemente aus Ihrer jeweiligen Datenquelle.

Fügen Sie zuerst der Lösung das falsche Paket hinzu, indem Sie den Befehl „dotnet add package“ verwenden.

dotnet add package Bogus

Legen Sie die Definition der Elemente fest, die Sie speichern möchten. Sie müssen die Item-Klasse in der Datei Program.cs definieren:

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

    public string username{get;set;}
}

Erstellen Sie als Nächstes in der Program-Klasse eine Hilfsfunktion. Mit dieser Hilfsfunktion wird die von Ihnen definierte Anzahl von Elementen abgerufen, um zufällige Daten einzufügen und zu generieren:

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

Verwenden Sie die Hilfsfunktion, um eine Liste der zu verwendenden Dokumenten zu initialisieren:

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

Verwenden Sie als Nächstes die Liste der Dokumente, um gleichzeitige Aufgaben zu erstellen und die Aufgabenliste aufzufüllen, damit die Elemente in den Container eingefügt werden. Fügen Sie der Program-Klasse den folgenden Code hinzu, um diesen Vorgang durchzuführen:

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

All diese gleichzeitigen Vorgänge werden zusammen (als Massenvorgang) ausgeführt, wie dies im Einführungsabschnitt beschrieben ist.

Schritt 7: Ausführen des Beispiels

Zum Ausführen des Beispiels können Sie einfach den Befehl dotnet verwenden:

dotnet run

Abrufen des vollständigen Beispiels

Falls Sie die Schritte in diesem Tutorial aus Zeitmangel nicht durchführen konnten oder nur die Codebeispiele herunterladen möchten, können Sie sie über GitHub beziehen.

Stellen Sie nach dem Klonen des Projekts sicher, dass Sie in der Datei Program.cs die gewünschten Anmeldeinformationen aktualisieren.

Sie können das Beispiel ausführen, indem Sie in das Repositoryverzeichnis wechseln und dotnet verwenden:

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

Nächste Schritte

In diesem Tutorial haben Sie folgende Schritte ausgeführt:

  • Erstellen eines Azure Cosmos DB-Kontos
  • Konfigurieren des Projekts
  • Herstellen einer Verbindung mit einem Azure Cosmos DB-Konto mit aktivierter Unterstützung für Massenvorgänge
  • Durchführen eines Datenimports mit gleichzeitigen Erstellungsvorgängen

Sie können jetzt mit dem nächsten Tutorial fortfahren:

Abfragen von Azure Cosmos BD mithilfe der API für NoSQL

Versuchen Sie, die Kapazitätsplanung für eine Migration zu Azure Cosmos DB durchzuführen? Sie können Informationen zu Ihrem vorhandenen Datenbankcluster für die Kapazitätsplanung verwenden.