Sdílet prostřednictvím

Hromadný import dat do účtu Azure Cosmos DB for NoSQL pomocí sady .NET SDK

PLATÍ PRO: NoSQL

V tomto kurzu se dozvíte, jak vytvořit konzolovou aplikaci .NET, která optimalizuje zřízenou propustnost (RU/s) potřebnou k importu dat do služby Azure Cosmos DB.

V tomto článku načtete data z ukázkového zdroje dat a naimportujete je do kontejneru Azure Cosmos DB.

Tento kurz zahrnuje:

  • Vytvoření účtu služby Azure Cosmos DB
  • Konfigurace projektu
  • Připojení k účtu služby Azure Cosmos DB s povolenou hromadnou podporou
  • Provedení importu dat prostřednictvím souběžných operací vytváření

Požadavky

Než budete postupovat podle pokynů v tomto článku, ujistěte se, že máte následující zdroje informací:

V tomto kurzu se používá verze 3.0 nebo novější sady .NET SDK služby Azure Cosmos DB, na kterou je možné cílit na rozhraní .NET Framework nebo .NET Core.

Krok 1: Vytvoření účtu služby Azure Cosmos DB

Vytvořte účet Azure Cosmos DB for NoSQL z webu Azure Portal nebo vytvořte účet pomocí emulátoru služby Azure Cosmos DB.

Krok 2: Nastavení projektu .NET

Otevřete příkazový řádek windows nebo okno terminálu z místního počítače. Všechny příkazy v dalších částech spustíte z příkazového řádku nebo terminálu. Spuštěním následujícího příkazu dotnet new vytvořte novou aplikaci s názvem bulk-import-demo.

dotnet new console -n bulk-import-demo

Změňte adresář na nově vytvořenou složku aplikace. Aplikaci můžete sestavit pomocí následujících:

cd bulk-import-demo
dotnet build

Očekávaný výstup sestavení by měl vypadat přibližně takto:

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

Krok 3: Přidání balíčku Azure Cosmos DB

V adresáři aplikace nainstalujte klientskou knihovnu Azure Cosmos DB pro .NET Core pomocí příkazu dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Krok 4: Získání přihlašovacích údajů účtu služby Azure Cosmos DB

Ukázková aplikace se musí ověřit ve vašem účtu služby Azure Cosmos DB. K ověření byste měli aplikaci předat přihlašovací údaje účtu služby Azure Cosmos DB. Pomocí následujícího postupu získejte přihlašovací údaje účtu služby Azure Cosmos DB:

  1. Přihlaste se k portálu Azure.
  2. Přejděte ke svému účtu služby Azure Cosmos DB.
  3. Otevřete podokno Klíče a zkopírujte identifikátor URI a PRIMÁRNÍ KLÍČ vašeho účtu.

Pokud používáte emulátor služby Azure Cosmos DB, získejte přihlašovací údaje emulátoru.

Krok 5: Inicializace objektu CosmosClient s podporou hromadného spuštění

Otevřete vygenerovaný soubor Program.cs v editoru kódu. Vytvořte novou instanci CosmosClient s povoleným hromadným spuštěním a použijte ji k provádění operací se službou Azure Cosmos DB.

Začněte přepsáním výchozí Main metody a definováním globálních proměnných. Mezi tyto globální proměnné patří koncové a autorizační klíče, název databáze, kontejner, který vytvoříte, a počet položek, které vložíte hromadně. Nezapomeňte nahradit hodnoty endpointURL a autorizačního klíče podle vašeho prostředí.

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 Do metody přidejte následující kód pro inicializaci objektu CosmosClient:

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

Poznámka:

Po zadání hromadného spuštění v CosmosClientOptions jsou efektivně neměnné po celou dobu životnosti CosmosClient. Změna hodnot nemá žádný vliv.

Po povolení hromadného provádění, CosmosClient interně seskupí souběžné operace do jednotlivého volání služby. Tímto způsobem optimalizuje využití propustnosti tím, že distribuuje volání služby mezi oddíly a nakonec přiřadí jednotlivé výsledky původním volajícím.

Pak můžete vytvořit kontejner pro uložení všech našich položek. Definujte /pk jako klíč oddílu 50000 RU/s jako zřízenou propustnost a vlastní zásadu indexování, která vylučuje všechna pole pro optimalizaci propustnosti zápisu. Za inicializační příkaz CosmosClient přidejte následující kód:

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

Krok 6: Naplnění seznamu souběžných úloh

Pokud chcete využít podporu hromadného spouštění, vytvořte seznam asynchronních úloh založených na zdroji dat a operacích, které chcete provést, a použijte Task.WhenAll je ke souběžnému spuštění. Začněme tím, že použijeme data Bogus k vygenerování seznamu položek z našeho datového modelu. V reálné aplikaci by položky pocházejí z požadovaného zdroje dat.

Nejprve do řešení přidejte balíček Bogus pomocí příkazu dotnet add package.

dotnet add package Bogus

Definujte definici položek, které chcete uložit. Potřebujete definovat Item třídu v souboru Program.cs :

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

    public string username{get;set;}
}

Dále vytvořte pomocnou funkci uvnitř Program třídy. Tato pomocná funkce získá počet položek, které jste definovali pro vložení a vygenerování náhodných dat:

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

Pomocí pomocné funkce inicializujete seznam dokumentů, se kterými chcete pracovat:

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

Potom pomocí seznamu dokumentů vytvoříte souběžné úkoly a naplníte seznam úkolů a vložíte položky do kontejneru. Chcete-li provést tuto operaci, přidejte do Program třídy následující kód:

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

Všechny tyto souběžné operace bodu se provádějí společně (to je hromadně), jak je popsáno v úvodní části.

Krok 7: Spuštění ukázky

Pokud chcete ukázku spustit, můžete to udělat jednoduše pomocí dotnet příkazu:

dotnet run

Získání kompletní ukázky

Pokud jste neměli dostatek času k dokončení kroků v tomto kurzu nebo si jen chcete stáhnout ukázky kódu, můžete je získat z GitHubu.

Po naklonování projektu nezapomeňte aktualizovat požadované přihlašovací údaje uvnitř Program.cs.

Ukázku můžete spustit tak, že změníte adresář úložiště a použijete dotnet:

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

Další kroky

Dotazování služby Azure Cosmos DB pomocí rozhraní API pro NoSQL

Pokoušíte se naplánovat kapacitu migrace do služby Azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.

  • Last updated on