Sdílet prostřednictvím

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 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:

  • 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í:

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

Poznámka:

Po zadání hromadného spuštění v CosmosClientOptions jsou efektivně 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 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:

  • 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 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.