Azure Cosmos DB'de toplu işlemler gerçekleştirmek için toplu yürütücü .NET kitaplığını kullanma

  • Şunlara uygulanır: ✅ NoSQL

Note

Bu makalede açıklanan toplu yürütücü kütüphanesi, .NET SDK 2.x sürümünü kullanan uygulamalar için sürdürülmektedir. Yeni uygulamalar için, doğrudan .NET SDK sürüm 3.x ile kullanılabilen toplu desteği kullanabilirsiniz ve bu, herhangi bir dış kütüphane gerektirmez.

Şu anda toplu yürütücü kitaplığını kullanıyorsanız ve daha yeni SDK'da toplu desteğe geçmeyi planlıyorsanız, uygulamanızı geçirmek için Geçiş kılavuzundaki adımları kullanın.

Bu öğreticide, belgeleri bir Azure Cosmos DB kapsayıcısına içeri aktarmak ve güncelleştirmek için toplu yürütücü .NET kitaplığını kullanma yönergeleri sağlanır. Toplu yürütücü kitaplığı ve bunun büyük aktarım hızı ve depolamayı kullanmanıza nasıl yardımcı olduğu hakkında bilgi edinmek için bkz. Azure Cosmos DB toplu yürütücü kitaplığına genel bakış. Bu öğreticide, rastgele oluşturulan belgeleri bir Azure Cosmos DB kapsayıcısına toplu olarak içeri aktaran örnek bir .NET uygulaması görürsünüz. Verileri içeri aktardıktan sonra kitaplık, belirli belge alanlarında gerçekleştirilecek işlemler olarak düzeltme ekleri belirterek içeri aktarılan verileri toplu olarak nasıl güncelleştirebileceğinizi gösterir.

Şu anda toplu yürütücü kitaplığı yalnızca NoSQL için Azure Cosmos DB ve Gremlin hesapları için API tarafından desteklenmektedir. Bu makalede, NoSQL hesapları için API ile toplu yürütücü .NET kitaplığının nasıl kullanılacağı açıklanmaktadır. Gremlin hesapları için API ile toplu yürütücü .NET kitaplığını nasıl kullanacağınızı öğrenmek için bkz: Toplu yürütücü kitaplığı kullanarak Gremlin için Azure Cosmos DB'de verileri toplu olarak içe aktarma.

Prerequisites

Örnek uygulamayı kopyalama

Şimdi GitHub'dan örnek bir .NET uygulaması indirerek kodla çalışmaya geçelim. Bu uygulama, Azure Cosmos DB hesabınızda depolanan veriler üzerinde toplu işlemler gerçekleştirir. Uygulamayı kopyalamak için bir komut istemi açın, kopyalamak istediğiniz dizine gidin ve aşağıdaki komutu çalıştırın:

git clone https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started.git

Kopyalanan depo, BulkImportSample ve BulkUpdateSample adlı iki örnek içerir. Örnek uygulamalardan birini açabilir, App.config dosyasındaki bağlantı dizelerini Azure Cosmos DB hesabınızın bağlantı dizeleriyle güncelleyebilir, çözümü derleyebilir ve çalıştırabilirsiniz.

BulkImportSample uygulaması rastgele belgeler oluşturur ve bunları Azure Cosmos DB hesabınıza toplu olarak içeri aktarır. BulkUpdateSample uygulaması, belirli belge alanlarında gerçekleştirilecek işlemler olarak düzeltme ekleri belirterek içeri aktarılan belgeleri toplu olarak güncelleştirir. Sonraki bölümlerde, bu örnek uygulamaların her birinde kodu gözden geçireceksiniz.

Azure Cosmos DB hesabına verileri toplu içeri aktarma

  1. BulkImportSample klasörüne gidin ve BulkImportSample.sln dosyasını açın.

  2. Azure Cosmos DB'nin bağlantı dizesi aşağıdaki kodda gösterildiği gibi App.config dosyasından alınır:

    private static readonly string EndpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
private static readonly string AuthorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];
private static readonly string DatabaseName = ConfigurationManager.AppSettings["DatabaseName"];
private static readonly string CollectionName = ConfigurationManager.AppSettings["CollectionName"];
private static readonly int CollectionThroughput = int.Parse(ConfigurationManager.AppSettings["CollectionThroughput"]);

    Toplu içeri aktarıcı yeni bir veritabanı ve veritabanı adı, kapsayıcı adı ve App.config dosyasında belirtilen aktarım hızı değerleriyle bir kapsayıcı oluşturur.

  3. Ardından, DocumentClient nesnesi Doğrudan TCP bağlantı moduyla başlatılır:

    ConnectionPolicy connectionPolicy = new ConnectionPolicy
{
   ConnectionMode = ConnectionMode.Direct,
   ConnectionProtocol = Protocol.Tcp
};
DocumentClient client = new DocumentClient(new Uri(endpointUrl),authorizationKey,
connectionPolicy)

  4. BulkExecutor nesnesi, bekleme süresi ve kısıtlanmış istekler için yüksek bir yeniden deneme değeriyle başlatılır. Ardından, kullanım ömrü boyunca tıkanıklık denetimini BulkExecutor'a geçirmek için 0 olarak ayarlanır.

    // Set retry options high during initialization (default values).
client.ConnectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 30;
client.ConnectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 9;

IBulkExecutor bulkExecutor = new BulkExecutor(client, dataCollection);
await bulkExecutor.InitializeAsync();

// Set retries to 0 to pass complete control to bulk executor.
client.ConnectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 0;
client.ConnectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 0;

  5. Uygulama BulkImportAsync API'sini çağırır. .NET kitaplığı, toplu içeri aktarma işlemi için iki API aşırı yüklemesini sağlar: biri serileştirilmiş JSON belgeleri listesini, diğeri de seriden çıkarılmış POCO belgeleri listesini kabul eder. Bu aşırı yüklenmiş yöntemlerin tanımları hakkında daha fazla bilgi edinmek için API belgelerine bakın.

    BulkImportResponse bulkImportResponse = await bulkExecutor.BulkImportAsync(
  documents: documentsToImportInBatch,
  enableUpsert: true,
  disableAutomaticIdGeneration: true,
  maxConcurrencyPerPartitionKeyRange: null,
  maxInMemorySortingBatchSize: null,
  cancellationToken: token);

    BulkImportAsync yöntemi aşağıdaki parametreleri kabul eder:

    Parameter Tanım
    enableUpsert Belgelerde upsert işlemlerini etkinleştirmek için bir işaret. Verilen kimliğe sahip bir belge zaten varsa, belge güncelleştirilir. Varsayılan olarak false olarak ayarlanır.
    disableAutomaticIdGeneration Kimliğin otomatik olarak oluşturulmasını devre dışı bırakmak için bir bayrak. Varsayılan olarak true olarak ayarlanır.
    BölümAnahtarıAralığıBaşınaMaksEşzamanlılık Bölüm anahtarı aralığı başına en yüksek eşzamanlılık derecesi. null olarak ayarlanması kitaplığın varsayılan 20 değerini kullanmasına neden olur.
    maxInMemorySortingBatchSize Belge numaralandırıcısından çekilen ve her aşamada API çağrısına geçirilen en fazla belge sayısı. Bellek içi sıralama aşaması, toplu içeri aktarmadan önce gerçekleşir. Bu parametrenin null olarak ayarlanması kitaplığın varsayılan en düşük değeri (documents.count, 1000000) kullanmasına neden olur.
    cancellationToken Toplu içeri aktarma işleminin düzgün bir şekilde sonlandırılması için iptal belirteci.

Toplu veri aktarma yanıtı nesne tanımı
Toplu içeri aktarma API çağrısının sonucu aşağıdaki öznitelikleri içerir:

Parameter Tanım
NumberOfDocumentsImported (uzun) Toplu içeri aktarma API çağrısına sağlanan belgelerin toplamından başarıyla içeri aktarılan toplam belge sayısı.
TotalRequestUnitsConsumed (çift) Toplu içeri aktarma API çağrısı tarafından kullanılan toplam istek birimi (RU).
TotalTimeTaken (TimeSpan) Yürütmeyi tamamlamak için toplu içeri aktarma API çağrısının aldığı toplam süre.
BadInputDocuments (Liste<nesnesi>) Toplu içeri aktarma API çağrısında başarıyla içeri aktarılamamış hatalı biçimli belgelerin listesi. Döndürülen belgeleri düzeltin ve içeri aktarmayı yeniden deneyin. Hatalı biçimlendirilmiş belgeler, kimlik değeri dize olmayan belgeleri içerir (null veya başka bir veri türü geçersiz olarak kabul edilir).

Azure Cosmos DB hesabınızdaki verileri toplu güncelleştirme

BulkUpdateAsync API'sini kullanarak mevcut belgeleri güncelleştirebilirsiniz. Bu örnekte, Name alanını yeni bir değere ayarlarsınız ve Description alanını mevcut belgelerden kaldırırsınız. Desteklenen güncelleştirme işlemlerinin tamamı için API belgelerine bakın.

  1. BulkUpdateSample klasörüne gidin ve BulkUpdateSample.sln dosyasını açın.

  2. İlgili alan güncelleştirme işlemleriyle birlikte güncelleştirme öğelerini tanımlayın. Bu örnekte, alanı güncelleştirmek için SetUpdateOperationName. Ayrıca, belge alanını belirli bir değere göre artırma, belirli değerleri dizi alanına gönderme veya dizi alanından belirli bir değeri kaldırma gibi başka işlemler de gerçekleştirebilirsiniz. Toplu güncelleştirme API'sinin sağladığı farklı yöntemler hakkında bilgi edinmek için API belgelerine bakın.

    SetUpdateOperation<string> nameUpdate = new SetUpdateOperation<string>("Name", "UpdatedDoc");
UnsetUpdateOperation descriptionUpdate = new UnsetUpdateOperation("description");

List<UpdateOperation> updateOperations = new List<UpdateOperation>();
updateOperations.Add(nameUpdate);
updateOperations.Add(descriptionUpdate);

List<UpdateItem> updateItems = new List<UpdateItem>();
for (int i = 0; i < 10; i++)
{
 updateItems.Add(new UpdateItem(i.ToString(), i.ToString(), updateOperations));
}

  3. Uygulama BulkUpdateAsync API'sini çağırır. BulkUpdateAsync yönteminin tanımı hakkında bilgi edinmek için API belgelerine bakın.

    BulkUpdateResponse bulkUpdateResponse = await bulkExecutor.BulkUpdateAsync(
  updateItems: updateItems,
  maxConcurrencyPerPartitionKeyRange: null,
  maxInMemorySortingBatchSize: null,
  cancellationToken: token);

    BulkUpdateAsync yöntemi aşağıdaki parametreleri kabul eder:

    Parameter Tanım
    BölümAnahtarıAralığıBaşınaMaksEşzamanlılık Bölüm anahtarı aralığı başına en yüksek eşzamanlılık derecesi. Bu parametre null olarak ayarlanırsa, kitaplık varsayılan değeri (20) kullanır.
    maxInMemorySortingBatchSize Her aşamada API çağrısına geçirilen güncelleştirme öğeleri numaralandırıcısından çekilen en fazla güncelleştirme öğesi sayısı. Toplu güncellemeden önce gerçekleşen bellek içi sıralama aşaması amacıyla. Bu parametrenin null olarak ayarlanması kitaplığın varsayılan en düşük değeri (updateItems.count, 1000000) kullanmasına neden olur.
    cancellationToken Toplu güncelleştirme işleminden düzgün bir şekilde çıkmak için iptal belirteci.

Toplu güncelleme yanıt obje tanımı
Toplu güncelleştirme API çağrısının sonucu aşağıdaki öznitelikleri içerir:

Parameter Tanım
NumberOfDocumentsUpdated (uzun) Toplu güncelleştirme API'si çağrısına sağlanan toplam belge sayısının dışında başarıyla güncelleştirilen belge sayısı.
TotalRequestUnitsConsumed (çift) Toplu güncelleştirme API çağrısı tarafından kullanılan toplam istek birimi (RU) .
TotalTimeTaken (TimeSpan) Toplu güncelleştirme API çağrısının yürütmeyi tamamlama süresi.

Performans ipuçları

Toplu yürütücü kitaplığını kullanırken performansı artırmak için aşağıdaki noktaları göz önünde bulundurun:

  • En iyi performans için uygulamanızı Azure Cosmos DB hesabınızın yazma bölgesiyle aynı bölgede yer alan bir Azure sanal makinesinden çalıştırın.

  • Belirli bir Azure Cosmos DB kapsayıcısına karşılık gelen tek bir sanal makinede uygulamanın tamamı için tek bir BulkExecutor nesnesi örneği oluşturmanız önerilir.

  • Tek bir toplu işlem API'sinin yürütülmesi, birden çok görevi dahili olarak oluştururken istemci bilgisayarın CPU'sunun ve ağ GÇ'sinin büyük bir bölümünü tüketir. Toplu işlem API çağrılarını yürüten uygulama işleminizde birden çok eşzamanlı görev oluşturmaktan kaçının. Tek bir sanal makinede çalışan tek bir toplu işlem API'si çağrısı kapsayıcının aktarım hızının tamamını (kapsayıcınızın aktarım hızı > 1 milyon RU/sn ise) tüketemiyorsa, toplu işlem API çağrılarını eşzamanlı olarak yürütmek için ayrı sanal makineler oluşturmak tercih edilir.

  • Bir BulkExecutor nesnesi oluşturarak hedef Azure Cosmos DB kapsayıcısının InitializeAsync() bölüm eşlemesini elde etmek için yöntemin çağrıldığından emin olun.

  • Uygulamanızın App.Config dosyasında daha iyi performans için gcServer'ın etkinleştirildiğinden emin olun 

    <runtime>
  <gcServer enabled="true" />
</runtime>

  • Yazılım kütüphanesi, ya bir log dosyasına ya da konsola toplanabilecek izler üretir. Her ikisini de etkinleştirmek için uygulamanızın App.Config dosyasına aşağıdaki kodu ekleyin:

    <system.diagnostics>
  <trace autoflush="false" indentsize="4">
    <listeners>
      <add name="logListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="application.log" />
      <add name="consoleListener" type="System.Diagnostics.ConsoleTraceListener" />
    </listeners>
  </trace>
</system.diagnostics>

Sonraki Adımlar

  • Last updated on