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

  • Článek

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. V tomto kurzu se používá sada .NET SDK služby Azure Cosmos DB verze 3.0 nebo novější, která může být zacílena na .NET Framework nebo .NET Core.

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í vytvoření

Požadavky

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

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

Vytvořte účet Azure Cosmos DB for NoSQL z 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 systému 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í:

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. Pokud chcete provést ověření, měli byste aplikaci předat přihlašovací údaje účtu služby Azure Cosmos DB. Pomocí následujících kroků získejte přihlašovací údaje k účtu služby Azure Cosmos DB:

  1. Přihlaste se k webu Azure Portal.
  2. Přejděte na svůj účet Služby Azure Cosmos DB.
  3. Otevřete podokno Klíče a zkopírujte identifikátor URI a PRIMÁRNÍ KLÍČ svého úč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 spouš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ý bod 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 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

Jakmile je hromadné spuštění zadáno v CosmosClientOptions, jsou prakticky neměnné po celou dobu životnosti CosmosClient. Změna hodnot nebude mít žádný vliv.

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 napříč 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á 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 na základě zdroje dat a operací, které chcete provést, a použijte Task.WhenAll je k jejich souběžnému provádění. Začněme tím, že použijeme "Bogus" data k vygenerování seznamu položek z našeho datového modelu. V reálné aplikaci by položky pocházely z požadovaného zdroje dat.

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

dotnet add package Bogus

Definujte definici položek, které chcete uložit. Musíte definovat třídu v Item 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 vygeneruje náhodná 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);
}

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

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

Dále použijte seznam dokumentů k vytvoření souběžných úkolů a naplnění seznamu úkolů, aby se položky vložily 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 bodů se budou spouštět společně (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 příkazem dotnet :

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 klonování projektu nezapomeňte aktualizovat požadované přihlašovací údaje v souboru 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:

  • 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í vytvoření

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

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

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