.NET SDK'sını kullanarak Verileri NoSQL için Azure Cosmos DB hesabına toplu içeri aktarma

Makale
06/01/2023

UYGULANANLAR: NoSQL

Bu öğreticide, Azure Cosmos DB'ye veri aktarmak için gereken sağlanan aktarım hızını (RU/sn) en iyi duruma getiren bir .NET konsol uygulamasının nasıl derlendiği gösterilmektedir.

Bu makalede, örnek bir veri kaynağındaki verileri okuyacak ve bir Azure Cosmos DB kapsayıcısına aktaracaksınız. Bu öğreticide , .NET Framework veya .NET Core'a hedeflenebilen Azure Cosmos DB .NET SDK'sının 3.0+ sürümü kullanılmaktadır.

Bu öğreticinin içindekiler:

Azure Cosmos DB hesabı oluşturma
Projenizi yapılandırma
Toplu destek etkin bir Azure Cosmos DB hesabına bağlanma
Eşzamanlı oluşturma işlemleri aracılığıyla veri içeri aktarma gerçekleştirme

Önkoşullar

Bu makaledeki yönergeleri takip etmeden önce aşağıdaki kaynaklara sahip olduğunuzdan emin olun:

Etkin bir Azure hesabı. Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Azure Cosmos DB'yi ücretsiz olarak, Azure aboneliği olmadan ve hiçbir taahhüt gerektirmeden deneyebilirsiniz. Alternatif olarak, ilk 1000 RU/sn ve 25 GB depolama alanı ücretsiz olarak bir Azure Cosmos DB ücretsiz katmanı hesabı oluşturabilirsiniz. Azure Cosmos DB öykünücüsünün URI'sini https://localhost:8081de kullanabilirsiniz. Öykünücü ile kullanılacak anahtar için bkz . İsteklerin kimliğini doğrulama.
NET Core 3 SDK. komutunu çalıştırarak dotnet --versionortamınızda hangi sürümün kullanılabilir olduğunu doğrulayabilirsiniz.

1. Adım: Azure Cosmos DB hesabı oluşturma

Azure portalından NoSQL için Azure Cosmos DB hesabı oluşturun veya Azure Cosmos DB Öykünücüsü'ni kullanarak hesabı oluşturabilirsiniz.

2. Adım: .NET projenizi ayarlama

Yerel bilgisayarınızdan Windows komut istemini veya Terminal penceresini açın. Komut isteminden veya terminalden sonraki bölümlerde tüm komutları çalıştıracaksınız. Bulk-import-demo adlı yeni bir uygulama oluşturmak için aşağıdaki dotnet new komutunu çalıştırın.

dotnet new console -n bulk-import-demo

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirin. Uygulamayı şu şekilde oluşturabilirsiniz:

cd bulk-import-demo
dotnet build

Derlemeden beklenen çıkış şöyle görünmelidir:

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

3. Adım: Azure Cosmos DB paketini ekleme

Uygulama dizinindeyken dotnet add package komutunu kullanarak .NET Core için Azure Cosmos DB istemci kitaplığını yükleyin.

dotnet add package Microsoft.Azure.Cosmos

4. Adım: Azure Cosmos DB hesabı kimlik bilgilerinizi alma

Örnek uygulamanın Azure Cosmos DB hesabınızda kimlik doğrulaması yapması gerekir. Kimlik doğrulaması yapmak için Azure Cosmos DB hesabı kimlik bilgilerini uygulamaya geçirmeniz gerekir. Aşağıdaki adımları izleyerek Azure Cosmos DB hesabı kimlik bilgilerinizi alın:

Azure Portal’ında oturum açın.
Azure Cosmos DB hesabınıza gidin.
Anahtarlar bölmesini açın ve hesabınızın URI'sinive BİRİnCİl ANAHTAR'ını kopyalayın.

Azure Cosmos DB Öykünücüsü kullanıyorsanız öykünücü kimlik bilgilerini bu makaleden alın.

5. Adım: CosmosClient nesnesini toplu yürütme desteğiyle başlatma

Oluşturulan Program.cs dosyayı bir kod düzenleyicisinde açın. Toplu yürütme etkinleştirilmiş yeni bir CosmosClient örneği oluşturacak ve Azure Cosmos DB'ye yönelik işlemler yapmak için kullanacaksınız.

Başlangıç olarak varsayılan Main yöntemin üzerine yazalım ve genel değişkenleri tanımlayalım. Bu genel değişkenler uç nokta ve yetkilendirme anahtarlarını, veritabanının adını, oluşturacağınız kapsayıcıyı ve toplu olarak ekleyebileceğiniz öğe sayısını içerir. endpointURL ve yetkilendirme anahtarı değerlerini ortamınıza göre değiştirdiğinden emin olun.

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

     }
}

yönteminin Main içine CosmosClient nesnesini başlatmak için aşağıdaki kodu ekleyin:

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

Not

CosmosClientOptions içinde toplu yürütme belirtildikten sonra, CosmosClient'ın ömrü boyunca etkili bir şekilde sabittir. Değerleri değiştirmenin hiçbir etkisi olmaz.

Toplu yürütme etkinleştirildikten sonra CosmosClient eşzamanlı işlemleri dahili olarak tek hizmet çağrıları halinde gruplandırıyor. Bu şekilde hizmet çağrılarını bölümlere dağıtarak ve son olarak özgün arayanlara tek tek sonuçlar atayarak aktarım hızı kullanımını iyileştirir.

Ardından tüm öğelerimizi depolamak için bir kapsayıcı oluşturabilirsiniz. Bölüm anahtarı, sağlanan aktarım hızı olarak 50000 RU/sn ve yazma aktarım hızını iyileştirmek için tüm alanları dışlayacak özel bir dizin oluşturma ilkesi olarak tanımlayın /pk . CosmosClient başlatma deyiminden sonra aşağıdaki kodu ekleyin:

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

6. Adım: Eşzamanlı görevlerin listesini doldurma

Toplu yürütme desteğinden yararlanmak için, veri kaynağına ve gerçekleştirmek istediğiniz işlemlere göre zaman uyumsuz görevlerin listesini oluşturun ve bunları eşzamanlı olarak yürütmek için kullanın Task.WhenAll . Veri modelimizden bir öğe listesi oluşturmak için "Sahte" verileri kullanarak başlayalım. Gerçek dünyadaki bir uygulamada, öğeler istediğiniz veri kaynağından gelir.

İlk olarak, dotnet add package komutunu kullanarak Bogus paketini çözüme ekleyin.

dotnet add package Bogus

Kaydetmek istediğiniz öğelerin tanımını tanımlayın. dosyasının Item içinde Program.cs sınıfını tanımlamanız gerekir:

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

    public string username{get;set;}
}

Ardından sınıfının içinde Program bir yardımcı işlev oluşturun. Bu yardımcı işlevi, eklemek için tanımladığınız öğe sayısını alır ve rastgele veri oluşturur:

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

Birlikte çalışacak belgelerin listesini başlatmak için yardımcı işlevini kullanın:

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

Ardından, eşzamanlı görevler oluşturmak ve öğeleri kapsayıcıya eklemek için görev listesini doldurmak için belge listesini kullanın. Bu işlemi gerçekleştirmek için sınıfına Program aşağıdaki kodu ekleyin:

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

Tüm bu eşzamanlı nokta işlemleri, giriş bölümünde açıklandığı gibi birlikte (toplu olarak) yürütülür.

7. Adım: Örneği çalıştırma

Örneği çalıştırmak için komutunu kullanarak dotnet bunu yapabilirsiniz:

dotnet run

Tam örneği alma

Bu öğreticideki adımları tamamlama fırsatınız olmadıysa veya yalnızca kod örneklerini indirmek isterseniz GitHub'dan ulaşabilirsiniz.

Projeyi kopyaladıktan sonra, Program.cs içinde istenen kimlik bilgilerini güncelleştirdiğinden emin olun.

Örnek, depo dizinine değiştirilerek ve kullanılarak dotnetçalıştırılabilir:

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

Sonraki adımlar

Bu öğreticide aşağıdaki adımları gerçekleştirdiniz:

Azure Cosmos DB hesabı oluşturma
Projenizi yapılandırma
Toplu destek etkin bir Azure Cosmos DB hesabına bağlanma
Eşzamanlı oluşturma işlemleri aracılığıyla veri içeri aktarma gerçekleştirme

Artık sonraki öğreticiye geçebilirsiniz:

NoSQL için API'yi kullanarak Azure Cosmos DB'yi sorgulama

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.

Tek bildiğiniz mevcut veritabanı kümenizdeki sanal çekirdek ve sunucu sayısıysa, sanal çekirdekleri veya vCPU'ları kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin etme hakkında bilgi edinin

Aracılığıyla paylaş