Ausführen eines Massenimports von Daten in ein Azure Cosmos DB für NoSQL-Konto mithilfe des .NET SDK
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:
Ein aktives Azure-Konto. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Sie können Azure Cosmos DB kostenlos testen – ohne Azure-Abonnement und unverbindlich. Alternativ können Sie ein Azure Cosmos DB-Konto im Free-Tarif erstellen, bei dem die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos sind. Sie können auch den Azure Cosmos DB-Emulator mit dem URI
https://localhost:8081
verwenden. Informationen zur Verwendung des Schlüssels mit dem Emulator finden Sie unter Verwenden des Azure Cosmos-Emulators für lokale Entwicklungs- und Testvorgänge..NET Core 3 SDK. Führen Sie
dotnet --version
aus, um zu überprüfen, welche Version in Ihrer Umgebung verfügbar ist.
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:
- Melden Sie sich beim Azure-Portal an.
- Navigieren Sie zu Ihrem Azure Cosmos DB-Konto.
- Ö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:
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.
- Wenn Sie lediglich die Anzahl der virtuellen Kerne und Server in Ihrem vorhandenen Datenbankcluster kennen, lesen Sie die Informationen zum Schätzen von Anforderungseinheiten mithilfe von virtuellen Kernen oder virtuellen CPUs.
- Wenn Sie die typischen Anforderungsraten für Ihre aktuelle Datenbankworkload kennen, lesen Sie die Informationen zum Schätzen von Anforderungseinheiten mit dem Azure Cosmos DB-Kapazitätsplaner