Share via

Zbiorcze importowanie danych do konta NoSQL w usłudze Azure Cosmos DB 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 jest używana wersja 3.0 lub nowsza zestawu .NET SDK usługi Azure Cosmos DB, która może być przeznaczona do .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ą współbieżnych operacji tworzenia

Wymagania wstępne

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

Krok 1. Tworzenie konta usługi Azure Cosmos DB

Utwórz konto usługi Azure Cosmos DB for NoSQL na podstawie 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 utworzyć 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 twojego 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 obiektu 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 parametru endpointURL i klucza 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 wykonywania zbiorczego w obiekcie CosmosClientOptions są one skutecznie niezmienne przez okres istnienia obiektu CosmosClient. Zmiana wartości nie będzie miała 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 usługi 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 współbież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 generuje losowe dane:

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ń w celu wstawienia elementów do kontenera. Aby wykonać tę operację Program , dodaj następujący kod do 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 operacje punktów współbieżnych 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 dotnet pomocą 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ń w pliku Program.cs.

Przykład można uruchomić, zmieniając katalog na 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ą współbieżnych operacji tworzenia

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? Do planowania pojemności można użyć informacji o istniejącym klastrze bazy danych.