Transakční dávkové operace ve službě Azure Cosmos DB

PLATÍ PRO: NoSQL

Transakční dávka popisuje skupinu operací bodu, které musí být úspěšné nebo neúspěšné společně se stejným klíčem oddílu v kontejneru. Operace se definují, přidají do dávky a dávka se spustí. Pokud všechny operace proběhnou úspěšně v pořadí, v jakém jsou popsány v rámci transakční dávkové operace, transakce se potvrdí. Pokud ale nějaká operace selže, celá transakce se vrátí zpět.

Co je transakce ve službě Azure Cosmos DB

Transakce v typické databázi lze definovat jako posloupnost operací provedených jako jedna logická jednotka práce. Každá transakce poskytuje záruky vlastností ACID (Atomicity, Consistency, Isolation, Durability).

• Atomicita zaručuje, že všechny operace provedené uvnitř transakce jsou považovány za jednu jednotku a všechny z nich jsou potvrzeny nebo žádné z nich nejsou.
• Konzistence zajišťuje, že data jsou vždy v platném stavu napříč transakcemi.
• Izolace zaručuje, že žádné dvě transakce vzájemně nezasahují – mnoho komerčních systémů poskytuje více úrovní izolace, které lze použít na základě potřeb aplikace.
• Stálost zajišťuje, že všechny změny, které jsou potvrzeny v databázi, budou vždy přítomny. Azure Cosmos DB podporuje úplné transakce kompatibilní se službou ACID s izolací snímků pro operace v rámci stejného klíče logického oddílu.

Transakční dávkové operace a uložené procedury

Azure Cosmos DB v současné době podporuje uložené procedury, které také poskytují transakční obor operací. Transakční dávkové operace však nabízejí následující výhody:

• Možnost jazyka – Transakční dávka je podporována v sadě SDK a jazyce, se kterým už pracujete, zatímco uložené procedury musí být napsané v JavaScriptu.
• Správa verzí kódu – Kód aplikace pro správu verzí a jeho onboarding do kanálu CI/CD je mnohem přirozenější než orchestrace aktualizace uložené procedury a zajištění toho, aby se vrácení stalo ve správný čas. Usnadňuje také vrácení změn zpět.
• Výkon – Nižší latence ekvivalentních operací až o 30 % ve srovnání s prováděním uložené procedury.
• Serializace obsahu – Každá operace v transakční dávce může pro svou datovou část používat vlastní možnosti serializace.

Vytvoření transakční dávkové operace

.NET

Při vytváření transakční dávkové operace začněte s instancí kontejneru a volejte CreateTransactionalBatch:

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

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

V dalším kroku přidejte do dávky více operací:

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

Nakonec v dávce zavolejte ExecuteAsync :

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Po přijetí odpovědi zkontrolujte, jestli je odpověď úspěšná. Pokud odpověď značí úspěch, extrahujte výsledky:

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

Důležité

Pokud dojde k selhání, operace, která selhala, bude mít stavový kód odpovídající chyby. Všechny ostatní operace budou mít stavový kód 424 (neúspěšná závislost). Pokud operace selže, protože se pokusí vytvořit položku, která již existuje, vrátí se stavový kód 409 (konflikt). Stavový kód umožňuje určit příčinu selhání transakce.

Java

Při vytváření transakční dávkové operace volejte CosmosBatch.createCosmosBatch:

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

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

V dalším kroku přidejte do dávky více operací:

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

Nakonec pomocí instance kontejneru volejte executeCosmosBatch pomocí dávky:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Po přijetí odpovědi zkontrolujte, jestli je odpověď úspěšná. Pokud odpověď značí úspěch, extrahujte výsledky:

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

Důležité

Pokud dojde k selhání, operace, která selhala, bude mít stavový kód odpovídající chyby. Všechny ostatní operace budou mít stavový kód 424 (neúspěšná závislost). Pokud operace selže, protože se pokusí vytvořit položku, která již existuje, vrátí se stavový kód 409 (konflikt). Stavový kód umožňuje určit příčinu selhání transakce.

Python

Získání nebo vytvoření instance kontejneru:

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

V Pythonu vypadají transakční dávkové operace velmi podobně jako rozhraní API jednotlivých operací a jsou řazené kolekce členů obsahující (operation_type_string, args_tuple, batch_operation_kwargs_dictionary). Níže jsou uvedeny ukázkové položky, které se použijí k předvedení funkcí dávkových operací:

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"
}

Připravte operace, které se mají přidat do dávky:

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

Přidejte operace do dávky:

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

Nakonec spusťte dávku:

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]

Poznámka k použití operace opravy a replace_if_match_etag operace v dávce
Slovník kwargs dávkové operace je omezený a přijímá pouze celkem tři různé hodnoty klíče. V případě, že chcete použít podmíněné opravy v rámci dávky, je použití klíče filter_predicate k dispozici pro operaci opravy nebo v případě, že chcete používat značky etag s některou z operací, je k dispozici i použití klíčů if_match_etag/if_none_match_etag.

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

Důležité

Pokud dojde k selhání, operace, která selhala, bude mít stavový kód odpovídající chyby. Všechny ostatní operace budou mít stavový kód 424 (neúspěšná závislost). Pokud operace selže, protože se pokusí vytvořit položku, která již existuje, vrátí se stavový kód 409 (konflikt). Stavový kód umožňuje určit příčinu selhání transakce.

Jak se provádějí transakční dávkové operace

Při spuštění transakční dávky se všechny operace v transakční dávce seskupí, serializují do jedné datové části a odešlou se jako jeden požadavek do služby Azure Cosmos DB.

Služba obdrží požadavek a provede všechny operace v rámci transakčního oboru a vrátí odpověď pomocí stejného protokolu serializace. Tato odpověď je buď úspěšná, nebo neúspěšná, a poskytuje jednotlivé operace odpovědi na každou operaci.

Sada SDK zveřejňuje odpověď, aby ověřila výsledek, a volitelně extrahuje všechny výsledky interní operace.

Omezení

V současné době existují dvě známá omezení:

• Limit velikosti požadavku služby Azure Cosmos DB omezuje velikost datové části Transactional Batch na maximálně 2 MB a maximální doba provádění je 5 sekund.
• Pro zajištění očekávaného výkonu a v rámci smluv SLA existuje aktuální limit 100 operací na službu Transactional Batch.

Další kroky

• Další informace o tom, co můžete dělat s TransactionalBatch

• Další způsoby použití sady .NET SDK služby Azure Cosmos DB najdete v našich ukázkách .