Udostępnij za pośrednictwem

Zbiorcze importowanie danych do konta usługi Azure Cosmos DB for NoSQL przy użyciu zestawu SDK platformy .NET

  • Artykuł

DOTYCZY: NoSQL

W tym samouczku pokazano, jak utworzyć aplikację konsolową platformy .NET, która optymalizuje aprowizowaną przepływność (RU/s) wymaganą do zaimportowania danych do usługi Azure Cosmos DB.

W tym artykule odczytasz dane z przykładowego źródła danych i zaimportujesz je do kontenera usługi Azure Cosmos DB. W tym samouczku użyto wersji 3.0 lub nowszej zestawu .NET SDK usługi Azure Cosmos DB, który może być przeznaczony dla platformy .NET Framework lub .NET Core.

W tym samouczku opisano następujące czynności:

  • Tworzenie konta usługi Azure Cosmos DB
  • Konfigurowanie projektu
  • Nawiązywanie połączenia z kontem usługi Azure Cosmos DB z włączoną obsługą zbiorczą
  • Wykonywanie importowania danych za pomocą operacji tworzenia współbieżnego

Wymagania wstępne

Przed wykonaniem instrukcji opisanych w tym artykule upewnij się, że masz następujące zasoby:

  • Aktywne konto platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

    Możesz bezpłatnie wypróbować usługę Azure Cosmos DB bez subskrypcji platformy Azure i bez zobowiązania. Alternatywnie możesz utworzyć konto warstwy bezpłatnej usługi Azure Cosmos DB z pierwszymi 1000 RU/s i 25 GB miejsca do magazynowania bezpłatnie. Możesz również użyć emulatora usługi Azure Cosmos DB z identyfikatorem URI .https://localhost:8081 Aby uzyskać klucz do użycia z emulatorem, zobacz Uwierzytelnianie żądań.

  • ZESTAW SDK platformy NET Core 3. Możesz sprawdzić, która wersja jest dostępna w danym środowisku, uruchamiając polecenie dotnet --version.

Krok 1. Tworzenie konta usługi Azure Cosmos DB

Utwórz konto usługi Azure Cosmos DB for NoSQL w witrynie Azure Portal lub możesz utworzyć konto przy użyciu emulatora usługi Azure Cosmos DB.

Krok 2. Konfigurowanie projektu .NET

Otwórz wiersz polecenia systemu Windows lub okno terminalu z komputera lokalnego. Wszystkie polecenia zostaną uruchomione w następnych sekcjach z wiersza polecenia lub terminalu. Uruchom następujące polecenie dotnet new, aby utworzyć nową aplikację o nazwie bulk-import-demo.

dotnet new console -n bulk-import-demo

Zmień katalog na nowo utworzony folder aplikacji. Aplikację można skompilować za pomocą następujących funkcji:

cd bulk-import-demo
dotnet build

Oczekiwane dane wyjściowe z kompilacji powinny wyglądać mniej więcej tak:

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. Dodawanie pakietu usługi Azure Cosmos DB

Nadal w katalogu aplikacji zainstaluj bibliotekę klienta usługi Azure Cosmos DB dla platformy .NET Core przy użyciu polecenia dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Krok 4. Uzyskiwanie poświadczeń konta usługi Azure Cosmos DB

Przykładowa aplikacja musi uwierzytelniać się na koncie usługi Azure Cosmos DB. Aby przeprowadzić uwierzytelnianie, należy przekazać poświadczenia konta usługi Azure Cosmos DB do aplikacji. Uzyskaj poświadczenia konta usługi Azure Cosmos DB, wykonując następujące kroki:

  1. Zaloguj się w witrynie Azure Portal.
  2. Przejdź do konta usługi Azure Cosmos DB.
  3. Otwórz okienko Klucze i skopiuj identyfikator URI i KLUCZ PODSTAWOWY konta.

Jeśli używasz emulatora usługi Azure Cosmos DB, uzyskaj poświadczenia emulatora z tego artykułu.

Krok 5. Inicjowanie obiektu CosmosClient przy użyciu obsługi wykonywania zbiorczego

Otwórz wygenerowany Program.cs plik w edytorze kodu. Utworzysz nowe wystąpienie usługi CosmosClient z włączonym wykonywaniem zbiorczym i użyjesz go do wykonywania operacji względem usługi Azure Cosmos DB.

Zacznijmy od zastąpienia domyślnej Main metody i zdefiniowania zmiennych globalnych. Te zmienne globalne będą zawierać klucze punktu końcowego i autoryzacji, nazwę bazy danych, kontener, który utworzysz, oraz liczbę elementów, które zostaną wstawione zbiorczo. Pamiętaj, aby zastąpić wartości endpointURL i klucz autoryzacji zgodnie ze środowiskiem.

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 Wewnątrz metody dodaj następujący kod, aby zainicjować obiekt CosmosClient:

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

Uwaga

Po określeniu zbiorczego wykonywania w obiekcie CosmosClientOptions są one skutecznie niezmienne przez okres istnienia obiektu CosmosClient. Zmiana wartości nie będzie miała żadnego wpływu.

Po włączeniu wykonywania zbiorczego klient CosmosClient wewnętrznie grupuje operacje współbieżne w pojedyncze wywołania usługi. W ten sposób optymalizuje wykorzystanie przepływności, dystrybuując wywołania usług między partycjami, a na koniec przypisując poszczególne wyniki do oryginalnych obiektów wywołujących.

Następnie możesz utworzyć kontener do przechowywania wszystkich naszych elementów. Zdefiniuj /pk jako klucz partycji 50000 RU/s jako aprowizowaną przepływność oraz niestandardowe zasady indeksowania, które będą wykluczać wszystkie pola w celu zoptymalizowania przepływności zapisu. Dodaj następujący kod po instrukcji inicjowania elementu CosmosClient:

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. Wypełnianie listy zadań współbieżnych

Aby skorzystać z obsługi wykonywania zbiorczego, utwórz listę zadań asynchronicznych opartych na źródle danych i operacjach, które chcesz wykonać, i użyj Task.WhenAll polecenia , aby wykonywać je jednocześnie. Zacznijmy od użycia danych "Bogus", aby wygenerować listę elementów z naszego modelu danych. W rzeczywistej aplikacji elementy pochodzą z żądanego źródła danych.

Najpierw dodaj pakiet Bogus do rozwiązania przy użyciu polecenia dotnet add package.

dotnet add package Bogus

Zdefiniuj definicję elementów, które chcesz zapisać. Należy zdefiniować klasę Item w Program.cs pliku:

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

    public string username{get;set;}
}

Następnie utwórz funkcję pomocnika wewnątrz Program klasy . Ta funkcja pomocnika pobierze liczbę elementów zdefiniowanych do wstawienia i wygenerowania losowych danych:

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

Użyj funkcji pomocnika, aby zainicjować listę dokumentów do pracy z:

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

Następnie użyj listy dokumentów, aby utworzyć współbieżne zadania i wypełnić listę zadań, aby wstawić elementy do kontenera. Aby wykonać tę operację, dodaj następujący kod do Program klasy:

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

Wszystkie te współbieżne operacje punktów zostaną wykonane razem (zbiorczo), zgodnie z opisem w sekcji wprowadzenia.

Krok 7. Uruchamianie przykładu

Aby uruchomić przykład, możesz to zrobić po prostu za pomocą dotnet polecenia :

dotnet run

Pobieranie kompletnego przykładu

Jeśli nie masz czasu na ukończenie tego samouczka lub po prostu chcesz pobrać przykłady kodu, możesz uzyskać je w serwisie GitHub.

Po sklonowaniu projektu pamiętaj o zaktualizowaniu żądanych poświadczeń wewnątrz Program.cs.

Przykład można uruchomić, zmieniając katalog repozytorium i używając polecenia dotnet:

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

Następne kroki

W tym samouczku wykonano następujące czynności:

  • Tworzenie konta usługi Azure Cosmos DB
  • Konfigurowanie projektu
  • Nawiązywanie połączenia z kontem usługi Azure Cosmos DB z włączoną obsługą zbiorczą
  • Wykonywanie importowania danych za pomocą operacji tworzenia współbieżnego

Teraz możesz przejść do następnego samouczka:

Wykonywanie zapytań względem usługi Azure Cosmos DB przy użyciu interfejsu API dla noSQL

Próbujesz zaplanować pojemność migracji do usługi Azure Cosmos DB? Informacje o istniejącym klastrze bazy danych można użyć do planowania pojemności.