Udostępnij przez

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

  • Dotyczy: ✅ NoSQL

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

W tym artykule odczytujesz dane z przykładowego źródła danych i zaimportujesz je do kontenera usługi Azure Cosmos DB.

Ten samouczek obejmuje:

  • 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ą
  • Wykonaj import 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:

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.

Krok 1. Tworzenie konta usługi Azure Cosmos DB

Utwórz konto usługi Azure Cosmos DB for NoSQL w witrynie Azure Portal lub utwórz je 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 będąc w katalogu aplikacji, zainstaluj bibliotekę klienta usługi Azure Cosmos DB dla środowiska .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ę do witryny Azure Portal.
  2. Przejdź do konta usługi Azure Cosmos DB.
  3. Otwórz kartę Klucze i skopiuj identyfikator URI oraz PODSTAWOWY KLUCZ konta.

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

Krok 5: Zainicjuj obiekt CosmosClient z obsługą wykonywania zbiorczego

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

Zacznij od zastąpienia domyślnej Main metody i zdefiniowania zmiennych globalnych. Te zmienne globalne obejmują 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 zmienić wartości endpointURL i wartości 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 / Notatka

Po określeniu zbiorczego wykonywania w obiekcie CosmosClientOptions są one skutecznie niezmienne przez okres istnienia obiektu CosmosClient. Zmiana wartości nie ma 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 wyklucza wszystkie pola w celu zoptymalizowania przepływności zapisu. Dodaj następujący kod po instrukcji inicjalizującej 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 w celu wygenerowania listy elementów z naszego modelu danych. W rzeczywistej aplikacji elementy pochodzą z żądanego źródła danych.

Najpierw dodaj do rozwiązania pakiet Bogus, używając polecenia "dotnet add package".

dotnet add package Bogus

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

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 pobiera liczbę elementów zdefiniowanych do wstawienia i generowania 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, z którymi będziesz pracować.

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 są wykonywane 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

Pobierz kompletny przykład

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

Dalsze kroki

Wykonywanie zapytań w usłudze Azure Cosmos DB używając API dla NoSQL

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

  • Last updated on