Tranzakciós kötegműveletek az Azure Cosmos DB-ben

A KÖVETKEZŐRE VONATKOZIK: NoSQL

A tranzakciós köteg olyan pontműveletek egy csoportját írja le, amelyeknek sikeresnek vagy sikertelennek kell működnie egy tároló ugyanazon partíciókulcsával együtt. A műveletek definiálva vannak, hozzáadva a köteghez, és a köteg végrehajtása történik. Ha minden művelet sikeres a tranzakciós kötegműveletben leírt sorrendben, a tranzakció véglegesítése történik. Ha azonban egy művelet meghiúsul, a teljes tranzakció vissza lesz állítva.

Mi az a tranzakció az Azure Cosmos DB-ben?

A tipikus adatbázisok tranzakciói úgy határozhatók meg, mint egyetlen logikai munkaegységként végrehajtott műveletek sorozata. Minden tranzakció ACID (Atomitás, Konzisztencia, Elkülönítés, Tartósság) tulajdonsággaranciát biztosít.

• Az atomiság garantálja, hogy a tranzakción belül végrehajtott összes művelet egyetlen egységként lesz kezelve, és vagy mindegyik véglegesített, vagy egyik sem.
• A konzisztencia biztosítja, hogy az adatok mindig érvényes állapotban legyenek a tranzakciók között.
• Az elkülönítés garantálja, hogy két tranzakció ne zavarja egymást – számos kereskedelmi rendszer több elkülönítési szintet biztosít, amelyek az alkalmazás igényeinek megfelelően használhatók.
• A tartósság biztosítja, hogy az adatbázisban véglegesített módosítások mindig jelen legyenek. Az Azure Cosmos DB támogatja a teljes ACID-kompatibilis tranzakciókat pillanatkép-elkülönítéssel az ugyanazon logikai partíciókulcson belüli műveletekhez.

Tranzakciós kötegműveletek és tárolt eljárások

Az Azure Cosmos DB jelenleg támogatja a tárolt eljárásokat, amelyek a műveletek tranzakciós hatókörét is biztosítják. A tranzakciós kötegműveletek azonban a következő előnyöket kínálják:

• Nyelvi beállítás – A tranzakciós köteg támogatott az SDK-ban és a már meglévő nyelven, míg a tárolt eljárásokat JavaScriptben kell írni.
• Kódverziózás – Az alkalmazáskód verziószámozása és a CI/CD-folyamatra való előkészítése sokkal természetesebb, mint a tárolt eljárás frissítésének vezénylése, és annak biztosítása, hogy az átállás a megfelelő időben történjen. Emellett megkönnyíti a módosítások visszaállítását is.
• Teljesítmény – A tárolt eljárás végrehajtásához képest az egyenértékű műveletek késése akár 30%-kal is csökkenthető.
• Tartalom szerializálása – A tranzakciós kötegek minden egyes művelete egyéni szerializálási lehetőségeket használhat a hasznos adatokhoz.

Tranzakciós kötegművelet létrehozása

.NET

Tranzakciós kötegművelet létrehozásakor kezdje egy tárolópéldánysal, és hívja meg a CreateTransactionalBatch parancsot:

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

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Ezután adjon hozzá több műveletet a köteghez:

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

Végül hívja meg az ExecuteAsync parancsot a kötegen:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

A válasz beérkezése után ellenőrizze, hogy a válasz sikeres-e. Ha a válasz sikerességet jelez, nyerje ki az eredményeket:

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

Fontos

Ha hiba történik, a sikertelen művelet állapotkódja a megfelelő hibával fog rendelkezni. Az összes többi művelet 424 állapotkóddal (sikertelen függőség) fog rendelkezni. Ha a művelet meghiúsul, mert egy már létező elemet próbál létrehozni, a rendszer egy 409-s állapotkódot (ütközést) ad vissza. Az állapotkód lehetővé teszi a tranzakciós hiba okának azonosítását.

Java

Tranzakciós kötegművelet létrehozásakor hívja meg a CosmosBatch.createCosmosBatch parancsot:

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

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Ezután adjon hozzá több műveletet a köteghez:

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

Végül használjon egy tárolópéldányt az executeCosmosBatch meghívásához a köteggel:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

A válasz beérkezése után ellenőrizze, hogy a válasz sikeres-e. Ha a válasz sikerességet jelez, nyerje ki az eredményeket:

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

Fontos

Ha hiba történik, a sikertelen művelet állapotkódja a megfelelő hibával fog rendelkezni. Az összes többi művelet 424 állapotkóddal (sikertelen függőség) fog rendelkezni. Ha a művelet meghiúsul, mert egy már létező elemet próbál létrehozni, a rendszer egy 409-s állapotkódot (ütközést) ad vissza. Az állapotkód lehetővé teszi a tranzakciós hiba okának azonosítását.

Python

Tárolópéldány lekérése vagy létrehozása:

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

A Pythonban a Tranzakciós Batch-műveletek nagyon hasonlítanak a szingular operations API-khoz, és a halmazokat (operation_type_string, args_tuple, batch_operation_kwargs_dictionary) tartalmazzák. Az alábbiakban a kötegműveleti funkciók bemutatására szolgáló mintaelemeket mutatjuk be:

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

Készítse elő a köteghez hozzáadni kívánt műveleteket:

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

Adja hozzá a műveleteket a köteghez:

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

Végül hajtsa végre a köteget:

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]

Megjegyzés javításművelet és replace_if_match_etag művelet kötegben való használatához
A kwargs batch művelet szótára korlátozott, és csak három különböző kulcsértéket vesz fel. Abban az esetben, ha feltételes javítást szeretne használni a kötegen belül, a filter_predicate kulcs használata elérhető a javítás műveletéhez, vagy ha etageket szeretne használni bármelyik művelethez, a if_match_etag/if_none_match_etag kulcsok használata is elérhető.

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

Fontos

Ha hiba történik, a sikertelen művelet állapotkódja a megfelelő hibával fog rendelkezni. Az összes többi művelet 424 állapotkóddal (sikertelen függőség) fog rendelkezni. Ha a művelet meghiúsul, mert egy már létező elemet próbál létrehozni, a rendszer egy 409-s állapotkódot (ütközést) ad vissza. Az állapotkód lehetővé teszi a tranzakciós hiba okának azonosítását.

Tranzakciós kötegműveletek végrehajtása

A tranzakciós köteg végrehajtásakor a tranzakciós köteg összes művelete csoportosítva lesz, egyetlen hasznos adatba szerializálva, és egyetlen kérésként érkezik az Azure Cosmos DB szolgáltatáshoz.

A szolgáltatás megkapja a kérést, és végrehajtja az összes műveletet egy tranzakciós hatókörön belül, és ugyanazt a szerializálási protokollt használó választ ad vissza. Ez a válasz vagy sikeres vagy sikertelen, és műveletenként egyedi műveleti válaszokat ad meg.

Az SDK közzéteszi a választ az eredmény ellenőrzéséhez, és opcionálisan kinyeri az egyes belső műveleti eredményeket.

Korlátozások

Jelenleg két ismert korlát létezik:

• Az Azure Cosmos DB kérelemméretkorlátja korlátozza a tranzakciós köteg hasznos adatainak méretét, hogy ne haladja meg a 2 MB-ot, és a maximális végrehajtási idő 5 másodperc.
• Tranzakciós kötegenként jelenleg 100 műveletre van korlátozva annak biztosítása, hogy a teljesítmény a vártnak megfelelően és az SLA-kon belül legyen.

Következő lépések

• További információ a TransactionalBatch használatával elvégezhető műveletekről

• Tekintse meg a mintákat az Azure Cosmos DB .NET SDK használatának további módjaiért