Azure Cosmos DB'de işlemsel toplu işlemler

Şunlara uygulanır: ✅ NoSQL

Bir kapsayıcıda, aynı bölüm anahtarıyla birlikte ya başarıya ulaştırılması ya da başarısız olması gereken bir dizi işlem işlemi, "işlemsel toplu işlem" olarak adlandırılır. İş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 (atomiklik, tutarlılık, izolasyon ve 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şlendiğ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 engellemediğini 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.

İşlemsel toplu işlemler 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 – İşlemsel toplu işleme, 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% kadar azaltıldı.
İçerik serileştirme – İşlemsel toplu işlem içindeki her bir operasyon, yükü için özel serileştirme seçenekleri kullanabilir.

Transaksiyonel toplu işlem oluşturma

Kapsayıcı örneğiyle başlayın ve CreateTransactionalBatch'ı ç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 sahiptir. Diğer tüm işlemlerin 424 durum kodu (başarısız bağımlılık) vardı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 belirlemenize olanak tanır.

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şlemle executeCosmosBatch'i çağırmak 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

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

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

Python'da transaction toplu işlemler, tekil işlem API'lerine benzer ve operation_type_string, args_tuple, batch_operation_kwargs_dictionary içeren tuple'lardır. Aşağıdaki örnek öğeler toplu işlem işlevselliğini gösterir:


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:
# /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şleme 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ün.

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]

Uyarı

Toplu işlemde yama işlemi ve replace_if_match_etag işlemi kullanıyorsanız: Toplu işlem kwargs sözlüğü sınırlıdır ve toplamda yalnızca üç farklı anahtar değere sahiptir. Toplu iş içinde koşullu yama uygulamak istediğinizde, yama işlemi için filter_predicate anahtarı kullanılabilir veya etag'leri herhangi bir işlemde kullanmak istediğinizde 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

NewTransactionalBatch'ı çağır.

pk := azcosmos.NewPartitionKeyString("road-bikes")

batch := container.NewTransactionalBatch(pk)

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

type Bike struct {
	ID       string `json:"id"`
	Category string `json:"category"`
	Name     string `json:"name"`
}

bike := Bike{ID: "68719520766", Category: "road-bikes", Name: "Chropen Road Bike"}
bikeItem, _ := json.Marshal(bike)

batch.CreateItem(bikeItem, nil)

type BikePart struct {
	ID        string `json:"id"`
	Category  string `json:"category"`
	Name      string `json:"name"`
	ProductID string `json:"productID"`
}

part := BikePart{ID: "68719519885", Category: "road-bikes", Name: "Tronosuros Tire", ProductID: bike.ID}
bikePartItem, _ := json.Marshal(part)

batch.CreateItem(bikePartItem, nil)

Son olarak, toplu iş ile ExecuteTransactionalBatch'ı çağırmak için bir kapsayıcı örneği kullanın:

resp, _ := container.ExecuteTransactionalBatch(context.Background(), batch, nil)

if resp.Success {
	// execute conditional logic
}

Önemli

İşlem kümeleri nasıl yürütülür?

İşlem toplu işlemi yürütüldüğünde, toplu işlemdeki tüm işlemler gruplandırılarak tek bir yük haline getirilir 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ı, işlem toplu iş 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 işlem toplu işlemi başına geçerli 100 işlem sınırı vardır.

Sonraki adım

TransactionalBatch kullanımı

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-19

Aracılığıyla paylaş

Azure Cosmos DB'de işlemsel toplu işlemler

Azure Cosmos DB'de işlem nedir?

İşlemsel toplu işlemler ve saklı yordamlar

Transaksiyonel toplu işlem oluşturma

İşlem kümeleri nasıl yürütülür?

Sınırlamalar

Sonraki adım

Geri Bildirim

Ek kaynaklar