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 budete číst data z ukázkového zdroje dat a importovat je do kontejneru Azure Cosmos DB. 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.

Tento kurz zahrnuje:

Požadavky

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

• Aktivní účet Azure Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

  Službu Azure Cosmos DB můžete vyzkoušet zdarma bez předplatného Azure a bez nutnosti závazku. Alternativně můžete vytvořit účet úrovně Free služby Azure Cosmos DB s prvních 1 000 RU/s a 25 GB úložiště zdarma. Emulátor služby Azure Cosmos DB můžete také použít s identifikátorem URI https://localhost:8081služby . Klíč, který se má použít s emulátorem, najdete v tématu Ověřování požadavků.

• NET Core 3 SDK. Spuštěním příkazu dotnet --version můžete ověřit, která verze je ve vašem prostředí k dispozici.

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

Vytvořte účet Azure Cosmos DB for NoSQL z webu Azure Portal nebo ho můžete vytvořit 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 z tohoto článku.

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

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

Začněme přepsáním výchozí Main metody a definováním globálních proměnných. Tyto globální proměnné budou zahrnovat koncové a autorizační klíče, název databáze, kontejner, který vytvoříte, a počet položek, které budete vkládat hromadně. Nezapomeňte nahradit hodnoty koncového bodu ARL 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 });

Po povolení hromadného spuštění CosmosClient interně seskupí souběžné operace do volání jedné 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ásady indexování, které vyloučí 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();

Pak pomocí seznamu dokumentů vytvoříte souběžné úkoly a naplníte seznam úkolů, abyste do kontejneru vložili položky. 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 spustí 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

V tomto kurzu jste provedli následující kroky:

Teď můžete pokračovat k dalšímu kurzu:

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.

• Pokud víte, že je počet virtuálních jader a serverů ve vašem existujícím databázovém clusteru, přečtěte si informace o odhadu jednotek žádostí pomocí virtuálních jader nebo virtuálních procesorů.
• Pokud znáte typické sazby požadavků pro vaši aktuální úlohu databáze, přečtěte si informace o odhadu jednotek žádostí pomocí plánovače kapacity služby Azure Cosmos DB.