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

Şunlara uygulanır: ✅ 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 eğitimde neler var:

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 aktarımı 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ı. Eğer bir Azure aboneliğiniz yoksa, başlamadan önce ücretsiz bir hesap oluşturun.

İlk 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ü URI'si ile de kullanabilirsiniz. Öykünücü ile kullanılacak anahtar için İstekleri Kimlik Doğrulama bölümüne bakın.
NET Core 3 SDK. komutunu çalıştırarak dotnet --versionortamınızda hangi sürümün kullanılabilir olduğunu doğrulayabilirsiniz.

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.

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

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

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

Dizinizi yeni oluşturulan uygulama klasörüne 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ınaoturum 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 alın.

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

Oluşturulan Program.cs dosyasını bir kod düzenleyicisinde açın. Toplu yürütme etkin olarak yeni bir örneği CosmosClient oluşturun ve Azure Cosmos DB'ye yönelik işlemler yapmak için kullanın.

Varsayılan Main yöntemin üzerine yazarak ve genel değişkenleri tanımlayarak başlayın. 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 });

Uyarı

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

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ışlayan özel 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 öğelerin listesini oluşturmak için Bogus verilerini 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. Item Program.cs dosyasında 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 veriler 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 dotnet komutunu basit bir şekilde kullanabilirsiniz.

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 geçiş yaparak ve dotnet kullanılarak çalıştırılabilir.

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

Sonraki Adımlar

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-19