Dela via

Massimportera data till Azure Cosmos DB för NoSQL-konto med hjälp av .NET SDK

  • Artikel

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:

Steg 1: Skapa ett Azure Cosmos DB-konto

Skapa ett Azure Cosmos DB för NoSQL-konto från Azure-portalen 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:

  1. Logga in på Azure-portalen.
  2. Gå till ditt Azure Cosmos DB-konto.
  3. Ö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:

Fråga Azure Cosmos DB med hjälp av API:et för NoSQL

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.