Azure Cosmos DB'de işlem toplu işlemleri

UYGULANANLAR: NoSQL

İşlem toplu işlemi, kapsayıcıdaki aynı bölüm anahtarıyla birlikte başarılı olması veya başarısız olması gereken bir grup nokta işlemini açıklar. İşlemler tanımlanır, toplu işe eklenir ve toplu iş yürütülür. Tüm işlemler işlem toplu işlemi içinde tanımlandığı sırayla başarılı olursa, işlem işlenir. Ancak herhangi bir işlem başarısız olursa tüm işlem geri alınır.

Azure Cosmos DB'de işlem nedir?

Tipik bir veritabanındaki bir işlem, tek bir mantıksal iş birimi olarak gerçekleştirilen bir işlem dizisi olarak tanımlanabilir. Her işlem ACID (Bölünmezlik, Tutarlılık, Yalıtım, Dayanıklılık) özellik garantileri sağlar.

• Bölünmezlik , bir işlem içinde yapılan tüm işlemlerin tek bir birim olarak ele alınıp bunların tümünün işlenmediğini veya hiçbirinin işlenmediğini garanti eder.
• Tutarlılık , verilerin işlemler arasında her zaman geçerli bir durumda olmasını sağlar.
• Yalıtım , iki işlemin birbirini engellemesini garanti eder. Birçok ticari sistem, uygulama gereksinimlerine göre kullanılabilecek birden çok yalıtım düzeyi sağlar.
• Dayanıklılık , veritabanında işlenen tüm değişikliklerin her zaman mevcut olmasını sağlar. Azure Cosmos DB, aynı mantıksal bölüm anahtarı içindeki işlemler için anlık görüntü yalıtımına sahip tam ACID uyumlu işlemleri destekler.

İşlem toplu işlemleri ve saklı yordamlar

Azure Cosmos DB şu anda işlemlerde işlem kapsamını da sağlayan saklı yordamları destekler. Ancak işlem toplu işlemleri aşağıdaki avantajları sunar:

• Dil seçeneği – İşlem toplu işlemi zaten çalıştığınız SDK'da ve dilde desteklenirken saklı yordamların JavaScript'te yazılması gerekir.
• Kod sürümü oluşturma – Uygulama kodunun sürümü oluşturma ve CI/CD işlem hattınıza ekleme, saklı yordamın güncelleştirilmesini düzenlemekten ve geçişin doğru zamanda gerçekleştiğinden emin olmaktan çok daha doğaldır. Ayrıca değişiklikleri geri döndürmeyi de kolaylaştırır.
• Performans – Saklı yordam yürütmeye kıyasla eşdeğer işlemlerde gecikme süresi %30'a kadar azaltıldı.
• İçerik serileştirme – İşlem toplu işlemi içindeki her işlem yükü için özel serileştirme seçenekleri kullanabilir.

İşlem toplu işlemi oluşturma

.NET

İşlem toplu işlemi oluştururken bir kapsayıcı örneğiyle başlayın ve CreateTransactionalBatch öğesini çağırın:

PartitionKey partitionKey = new PartitionKey("road-bikes");

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Ardından toplu işe birden çok işlem ekleyin:

Product bike = new (
    id: "68719520766",
    category: "road-bikes",
    name: "Chropen Road Bike"
);

batch.CreateItem<Product>(bike);

Part part = new (
    id: "68719519885",
    category: "road-bikes",
    name: "Tronosuros Tire",
    productId: bike.id
);

batch.CreateItem<Part>(part);

Son olarak, toplu işlemde ExecuteAsync'i çağırın:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Yanıt alındıktan sonra yanıtın başarılı olup olmadığını inceleyin. Yanıt başarılı olduğunu gösteriyorsa sonuçları ayıklayın:

if (response.IsSuccessStatusCode)
{
    TransactionalBatchOperationResult<Product> productResponse;
    productResponse = response.GetOperationResultAtIndex<Product>(0);
    Product productResult = productResponse.Resource;

    TransactionalBatchOperationResult<Part> partResponse;
    partResponse = response.GetOperationResultAtIndex<Part>(1);
    Part partResult = partResponse.Resource;
}

Önemli

Bir hata varsa, başarısız olan işlem ilgili hatanın durum koduna sahip olur. Diğer tüm işlemlerin 424 durum kodu (başarısız bağımlılık) olacaktır. zaten var olan bir öğe oluşturmaya çalıştığı için işlem başarısız olursa, 409 (çakışma) durum kodu döndürülür. Durum kodu, işlem hatasının nedenini belirlemesini sağlar.

Java

İşlem toplu işlemi oluştururken CosmosBatch.createCosmosBatch'ı çağırın:

PartitionKey partitionKey = new PartitionKey("road-bikes");

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Ardından toplu işe birden çok işlem ekleyin:

Product bike = new Product();
bike.setId("68719520766");
bike.setCategory("road-bikes");
bike.setName("Chropen Road Bike");

batch.createItemOperation(bike);

Part part = new Part();
part.setId("68719519885");
part.setCategory("road-bikes");
part.setName("Tronosuros Tire");
part.setProductId(bike.getId());

batch.createItemOperation(part);

Son olarak, toplu iş ile executeCosmosBatch çağrısı yapmak için bir kapsayıcı örneği kullanın:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Yanıt alındıktan sonra yanıtın başarılı olup olmadığını inceleyin. Yanıt başarılı olduğunu gösteriyorsa sonuçları ayıklayın:

if (response.isSuccessStatusCode())
{
    List<CosmosBatchOperationResult> results = response.getResults();
}

Önemli

Bir hata varsa, başarısız olan işlem ilgili hatanın durum koduna sahip olur. Diğer tüm işlemlerin 424 durum kodu (başarısız bağımlılık) olacaktır. zaten var olan bir öğe oluşturmaya çalıştığı için işlem başarısız olursa, 409 (çakışma) durum kodu döndürülür. Durum kodu, işlem hatasının nedenini belirlemesini sağlar.

Python

Kapsayıcı örneği alma veya oluşturma:

container = database.create_container_if_not_exists(id="batch_container",
                                                        partition_key=PartitionKey(path='/road_bikes'))

Python'da İşlem Toplu İşlem işlemleri tekil işlem api'lerine çok benzer ve (operation_type_string, args_tuple, batch_operation_kwargs_dictionary) içeren tanımlama kümeleridir. Toplu işlem işlevselliğini göstermek için kullanılacak örnek öğeler aşağıda verilmiştir:

create_demo_item = {
    "id": "68719520766",
    "category": "road-bikes",
    "name": "Chropen Road Bike"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item1 = {
    "id": "68719519884",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item2 = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item3 = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, we'll upsert the item with id 68719519885
upsert_demo_item = {
    "id": "68719519885",
    "category": "road-bikes",
    "name": "Tronosuros Tire Upserted",
    "productId": "68719520768"
}

# for replace demo, we'll replace the read_demo_item2 with this item
replace_demo_item = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire replaced",
    "productId": "68719520769"
}

# for replace with etag match demo, we'll replace the read_demo_item3 with this item
# The use of etags and if-match/if-none-match options allows users to run conditional replace operations
# based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
# matches the passed in value. For more on optimistic concurrency control, see the link below:
# https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
replace_demo_item_if_match_operation = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tireh",
    "wasReplaced": "Replaced based on etag match"
    "productId": "68719520769"
}

Toplu işe eklenecek işlemleri hazırlayın:

create_item_operation = ("create", (create_demo_item,), {})
read_item_operation = ("read", ("68719519884",), {})
delete_item_operation = ("delete", ("68719519885",), {})
upsert_item_operation = ("upsert", (upsert_demo_item,), {})
replace_item_operation = ("replace", ("68719519886", replace_demo_item), {})
replace_item_if_match_operation = ("replace",
                                       ("68719519887", replace_demo_item_if_match_operation),
                                       {"if_match_etag": container.client_connection.last_response_headers.get("etag")})

İşlemleri toplu işe ekleyin:

batch_operations = [
        create_item_operation,
        read_item_operation,
        delete_item_operation,
        upsert_item_operation,
        replace_item_operation,
        replace_item_if_match_operation
    ]

Son olarak, toplu işlemi yürütür:

try:
    # Run that list of operations
    batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key="road_bikes")
    # Batch results are returned as a list of item operation results - or raise a CosmosBatchOperationError if
    # one of the operations failed within your batch request.
    print("\nResults for the batch operations: {}\n".format(batch_results))
except exceptions.CosmosBatchOperationError as e:
        error_operation_index = e.error_index
        error_operation_response = e.operation_responses[error_operation_index]
        error_operation = batch_operations[error_operation_index]
        print("\nError operation: {}, error operation response: {}\n".format(error_operation, error_operation_response))
    # [END handle_batch_error]

Toplu işlemde düzeltme eki işlemi ve replace_if_match_etag işlemi kullanma notları
Toplu işlem kwargs sözlüğü sınırlıdır ve yalnızca üç farklı anahtar değeri alır. Toplu iş içinde koşullu düzeltme eki uygulama kullanmak isteme durumunda, düzeltme eki işlemi için filter_predicate anahtarı kullanılabilir veya herhangi bir işlemle etag'leri kullanmak istemeniz durumunda if_match_etag/if_none_match_etag anahtarları da kullanılabilir.

batch_operations = [
       ("replace", (item_id, item_body), {"if_match_etag": etag}),
       ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
   ]

Önemli

Bir hata varsa, başarısız olan işlem ilgili hatanın durum koduna sahip olur. Diğer tüm işlemlerin 424 durum kodu (başarısız bağımlılık) olacaktır. zaten var olan bir öğe oluşturmaya çalıştığı için işlem başarısız olursa, 409 (çakışma) durum kodu döndürülür. Durum kodu, işlem hatasının nedenini belirlemesini sağlar.

İşlem toplu işlemleri nasıl yürütülür?

İşlem Toplu İşlemi yürütülürken, İşlem Toplu İşlemi'ndeki tüm işlemler gruplandırılır, tek bir yükte serileştirilir ve Azure Cosmos DB hizmetine tek bir istek olarak gönderilir.

Hizmet isteği alır ve işlem kapsamındaki tüm işlemleri yürütür ve aynı serileştirme protokolünü kullanarak bir yanıt döndürür. Bu yanıt bir başarı veya başarısızlıktır ve işlem başına tek tek işlem yanıtları sağlar.

SDK, sonucu doğrulamanız ve isteğe bağlı olarak iç işlem sonuçlarının her birini ayıklamanız için yanıtı kullanıma sunar.

Sınırlamalar

Şu anda bilinen iki sınır vardır:

• Azure Cosmos DB istek boyutu sınırı İşlem Toplu İş yükünün boyutunu 2 MB'ı aşmamak üzere kısıtlar ve yürütme süresi üst sınırı 5 saniyedir.
• Performansın beklendiği gibi ve SLA'lar içinde olduğundan emin olmak için İşlem Toplu İşlemi başına geçerli 100 işlem sınırı vardır.

Sonraki adımlar

• TransactionalBatch ile neler yapabileceğiniz hakkında daha fazla bilgi edinin

• Azure Cosmos DB .NET SDK'mızı kullanmanın diğer yolları için örneklerimizi ziyaret edin