Share 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 etablerat 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 till .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 via samtidiga skapandeåtgärder

Förutsättningar

Kontrollera att du har följande resurser innan du följer anvisningarna i den här artikeln:

Steg 1: Skapa ett Azure Cosmos DB-konto

Skapa ett Azure Cosmos DB for NoSQL-konto från Azure Portal eller skapa kontot med hjälp av Azure Cosmos DB-emulatorn.

Steg 2: Konfigurera ditt .NET-projekt

Ö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 dotnet new-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

De 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

När du fortfarande är i programkatalogen installerar du Azure Cosmos DB-klientbiblioteket för .NET Core med hjälp av kommandot dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Steg 4: Hämta autentiseringsuppgifterna 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 kontots URI och PRIMÄRNYCKEL .

Om du använder Azure Cosmos DB-emulatorn hämtar du emulatorns autentiseringsuppgifter 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 grupp. Se till att ersätta 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 });

Anteckning

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, 5 000 RU/s som etablerat dataflöde och en anpassad indexeringsprincip som exkluderar alla fält för att optimera skrivdataflödet. Lägg till följande kod efter CosmosClient-initieringsinitieringsinitieringen:

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: Fyll 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 med objekt från vår datamodell. I ett verkligt program skulle objekten komma från din önskade datakälla.

Lägg först till det falska 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. Lägg till följande kod i Program klassen för att utföra den här åtgärden:

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 grupp) enligt beskrivningen i introduktionsavsnittet.

Steg 7: Kör exemplet

För att köra exemplet kan du göra det bara med dotnet kommandot :

dotnet run

Hämta hela 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 klonar projektet måste du uppdatera önskade autentiseringsuppgifter i Program.cs.

Du kan köra exemplet genom att ändra till katalogen för lagringsplatsen 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 via 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 göra kapacitetsplanering för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.