Massimportera data till Azure Cosmos DB för NoSQL-konto med hjälp av .NET SDK
GÄLLER FÖR: NoSQL
Den här självstudien visar hur du skapar ett .NET-konsolprogram som optimerar det etablerade dataflöde (RU/s) som krävs för att importera data till Azure Cosmos DB.
I den här artikeln läser du data från en exempeldatakälla och importerar dem till en Azure Cosmos DB-container. I den här självstudien används version 3.0+ av Azure Cosmos DB .NET SDK, som kan riktas mot .NET Framework eller .NET Core.
Den här självstudiekursen omfattar:
- Skapa ett Azure Cosmos DB-konto
- Konfigurera projektet
- Ansluta till ett Azure Cosmos DB-konto med massstöd aktiverat
- Utföra en dataimport genom samtidiga skapandeåtgärder
Förutsättningar
Innan du följer anvisningarna i den här artikeln kontrollerar du att du har följande resurser:
Ett aktivt Azure-konto. Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
Du kan prova Azure Cosmos DB kostnadsfritt, utan en Azure-prenumeration och utan något åtagande. Du kan också skapa ett kostnadsfritt Azure Cosmos DB-konto med de första 1 000 RU/s och 25 GB lagringsutrymme utan kostnad. Du kan också använda Azure Cosmos DB-emulatorn med en URI för
https://localhost:8081
. Den nyckel som ska användas med emulatorn finns i Autentisera begäranden.NET Core 3 SDK. Du kan kontrollera vilken version som är tillgänglig i din miljö genom att köra
dotnet --version
.
Steg 1: Skapa ett Azure Cosmos DB-konto
Skapa ett Azure Cosmos DB för NoSQL-konto från Azure Portal eller skapa kontot med hjälp av Azure Cosmos DB-emulatorn.
Steg 2: Konfigurera .NET-projektet
Öppna Windows-kommandotolken eller ett terminalfönster från den lokala datorn. Du kör alla kommandon i nästa avsnitt från kommandotolken eller terminalen. Kör följande nya dotnet-kommando för att skapa en ny app med namnet bulk-import-demo.
dotnet new console -n bulk-import-demo
Ändra katalogen till den nyligen skapade appmappen. Du kan skapa programmet med:
cd bulk-import-demo
dotnet build
Förväntade utdata från bygget bör se ut ungefär så här:
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
Steg 3: Lägg till Azure Cosmos DB-paketet
Installera Azure Cosmos DB-klientbiblioteket för .NET Core medan du fortfarande är i programkatalogen med hjälp av kommandot dotnet add package.
dotnet add package Microsoft.Azure.Cosmos
Steg 4: Hämta dina autentiseringsuppgifter för Ditt Azure Cosmos DB-konto
Exempelprogrammet måste autentiseras mot ditt Azure Cosmos DB-konto. För att autentisera bör du skicka autentiseringsuppgifterna för Azure Cosmos DB-kontot till programmet. Hämta autentiseringsuppgifterna för ditt Azure Cosmos DB-konto genom att följa dessa steg:
- Logga in på Azure-portalen.
- Gå till ditt Azure Cosmos DB-konto.
- Öppna fönstret Nycklar och kopiera URI:n och primärnyckeln för ditt konto.
Om du använder Azure Cosmos DB-emulatorn hämtar du autentiseringsuppgifterna för emulatorn från den här artikeln.
Steg 5: Initiera CosmosClient-objektet med stöd för masskörning
Öppna den genererade Program.cs
filen i en kodredigerare. Du skapar en ny instans av CosmosClient med masskörning aktiverat och använder den för att utföra åtgärder mot Azure Cosmos DB.
Vi börjar med att skriva över standardmetoden Main
och definiera de globala variablerna. Dessa globala variabler inkluderar slutpunkts- och auktoriseringsnycklarna, namnet på databasen, containern som du skapar och antalet objekt som du kommer att infoga i bulk. Ersätt värdena för endpointURL- och auktoriseringsnyckeln enligt din miljö.
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)
{
}
}
Main
I metoden lägger du till följande kod för att initiera CosmosClient-objektet:
CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey, new CosmosClientOptions() { AllowBulkExecution = true });
Kommentar
När masskörning har angetts i CosmosClientOptions är de i praktiken oföränderliga under CosmosClients livslängd. Att ändra värdena har ingen effekt.
När masskörningen har aktiverats grupperar CosmosClient internt samtidiga åtgärder i anrop med en enda tjänst. På så sätt optimeras dataflödesanvändningen genom att tjänstanrop distribueras mellan partitioner och slutligen tilldela enskilda resultat till de ursprungliga anroparna.
Du kan sedan skapa en container för att lagra alla våra objekt. Definiera /pk
som partitionsnyckel, 50000 RU/s som etablerat dataflöde och en anpassad indexeringsprincip som utesluter alla fält för att optimera skrivdataflödet. Lägg till följande kod efter CosmosClient-initieringsinitieringssatsen:
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);
Steg 6: Fylla i en lista över samtidiga uppgifter
Om du vill dra nytta av stöd för masskörning skapar du en lista över asynkrona uppgifter baserat på datakällan och de åtgärder som du vill utföra och använder Task.WhenAll
för att köra dem samtidigt.
Vi börjar med att använda "falska" data för att generera en lista över objekt från vår datamodell. I ett verkligt program skulle objekten komma från din önskade datakälla.
Lägg först till Bogus-paketet i lösningen med hjälp av kommandot dotnet add package .
dotnet add package Bogus
Definiera definitionen av de objekt som du vill spara. Du måste definiera Item
klassen i Program.cs
filen:
public class Item
{
public string id {get;set;}
public string pk {get;set;}
public string username{get;set;}
}
Skapa sedan en hjälpfunktion i Program
klassen. Den här hjälpfunktionen hämtar antalet objekt som du har definierat för att infoga och genererar slumpmässiga data:
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);
}
Använd hjälpfunktionen för att initiera en lista över dokument att arbeta med:
IReadOnlyCollection<Item> itemsToInsert = Program.GetItemsToInsert();
Använd sedan listan med dokument för att skapa samtidiga uppgifter och fylla i uppgiftslistan för att infoga objekten i containern. Om du vill utföra den här åtgärden lägger du till följande kod i Program
klassen:
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);
Alla dessa samtidiga punktåtgärder körs tillsammans (som är i bulk) enligt beskrivningen i introduktionsavsnittet.
Steg 7: Kör exemplet
För att kunna köra exemplet kan du göra det helt enkelt med kommandot dotnet
:
dotnet run
Hämta det fullständiga exemplet
Om du inte har tid att slutföra stegen i den här självstudien eller bara vill ladda ned kodexemplen kan du hämta den från GitHub.
När du har klonade projektet måste du uppdatera önskade autentiseringsuppgifter i Program.cs.
Exemplet kan köras genom att ändra till lagringsplatskatalogen och använda dotnet
:
cd cosmos-dotnet-bulk-import-throughput-optimizer
dotnet run
Nästa steg
I den här självstudien har du gjort följande:
- Skapa ett Azure Cosmos DB-konto
- Konfigurera projektet
- Ansluta till ett Azure Cosmos DB-konto med massstöd aktiverat
- Utföra en dataimport genom samtidiga skapandeåtgärder
Nu kan du gå vidare till nästa självstudie:
Försöker du planera kapacitet för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.
- Om allt du vet är antalet virtuella kärnor och servrar i ditt befintliga databaskluster läser du om att uppskatta enheter för begäranden med virtuella kärnor eller virtuella kärnor
- Om du känner till vanliga begärandefrekvenser för din aktuella databasarbetsbelastning kan du läsa om att uppskatta enheter för begäranden med azure Cosmos DB-kapacitetshanteraren