Transaktionella batchåtgärder i Azure Cosmos DB

GÄLLER FÖR: NoSQL

Transaktionsbatch beskriver en grupp punktåtgärder som antingen måste lyckas eller misslyckas tillsammans med samma partitionsnyckel i en container. Åtgärder definieras, läggs till i batchen och batchen körs. Om alla åtgärder lyckas i den ordning de beskrivs i den transaktionella batchåtgärden kommer transaktionen att genomföras. Men om någon åtgärd misslyckas återställs hela transaktionen.

Vad är en transaktion i Azure Cosmos DB

En transaktion i en typisk databas kan definieras som en sekvens med åtgärder som utförs som en enda logisk arbetsenhet. Varje transaktion ger acid-egenskapsgarantier (Atomicity, Consistency, Isolation, Durability).

• Atomicitet garanterar att alla åtgärder som utförs i en transaktion behandlas som en enda enhet, och antingen är alla incheckade eller ingen av dem.
• Konsekvens säkerställer att data alltid är i ett giltigt tillstånd mellan transaktioner.
• Isolering garanterar att inga två transaktioner stör varandra – många kommersiella system tillhandahåller flera isoleringsnivåer som kan användas baserat på programmets behov.
• Hållbarhet säkerställer att alla ändringar som görs i en databas alltid kommer att finnas. Azure Cosmos DB stöder fullständiga ACID-kompatibla transaktioner med ögonblicksbildisolering för åtgärder inom samma logiska partitionsnyckel.

Transaktionella batchåtgärder och lagrade procedurer

Azure Cosmos DB stöder för närvarande lagrade procedurer, vilket även ger transaktionsomfånget för åtgärder. Transaktionella batchåtgärder erbjuder dock följande fördelar:

• Språkalternativ – Transaktionsbatch stöds på det SDK och språk som du redan arbetar med, medan lagrade procedurer måste skrivas i JavaScript.
• Kodversionshantering – Versionshantering av programkod och registrering på DIN CI/CD-pipeline är mycket mer naturligt än att samordna uppdateringen av en lagrad procedur och se till att rollover sker vid rätt tidpunkt. Det gör det också enklare att återställa ändringar.
• Prestanda – Kortare svarstid för motsvarande åtgärder med upp till 30 % jämfört med körningen av den lagrade proceduren.
• Innehållsserialisering – Varje åtgärd i en transaktionsbatch kan använda anpassade serialiseringsalternativ för nyttolasten.

Så här skapar du en transaktionsbatchåtgärd

.NET

När du skapar en transaktionell batchåtgärd börjar du med en containerinstans och anropar CreateTransactionalBatch:

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

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Lägg sedan till flera åtgärder i batchen:

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

Anropa slutligen ExecuteAsync på batchen:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

När svaret har tagits emot undersöker du om svaret lyckas. Om svaret indikerar ett lyckat resultat extraherar du resultatet:

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

Viktigt!

Om det uppstår ett fel har den misslyckade åtgärden statuskoden för motsvarande fel. Alla andra åtgärder har statuskoden 424 (misslyckat beroende). Om åtgärden misslyckas eftersom den försöker skapa ett objekt som redan finns returneras en statuskod på 409 (konflikt). Statuskoden gör det möjligt för en att identifiera orsaken till transaktionsfelet.

Java

När du skapar en transaktionell batchåtgärd anropar du CosmosBatch.createCosmosBatch:

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

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Lägg sedan till flera åtgärder i batchen:

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

Använd slutligen en containerinstans för att anropa executeCosmosBatch med batchen:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

När svaret har tagits emot undersöker du om svaret lyckas. Om svaret indikerar ett lyckat resultat extraherar du resultatet:

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

Viktigt!

Om det uppstår ett fel har den misslyckade åtgärden statuskoden för motsvarande fel. Alla andra åtgärder har statuskoden 424 (misslyckat beroende). Om åtgärden misslyckas eftersom den försöker skapa ett objekt som redan finns returneras en statuskod på 409 (konflikt). Statuskoden gör det möjligt för en att identifiera orsaken till transaktionsfelet.

Python

Hämta eller skapa en containerinstans:

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

I Python ser transactional Batch-åtgärder ut ungefär som api:erna för singularåtgärder och är tupplar som innehåller (operation_type_string, args_tuple batch_operation_kwargs_dictionary). Nedan visas exempelobjekt som ska användas för att demonstrera funktioner för batchåtgärder:

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

Förbered de åtgärder som ska läggas till i batchen:

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

Lägg till åtgärderna i batchen:

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

Kör slutligen batchen:

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]

Obs! För att använda korrigeringsåtgärd och replace_if_match_etag åtgärd i batchen
Kwargs-ordlistan för batchåtgärden är begränsad och tar bara totalt tre olika nyckelvärden. Om du vill använda villkorsstyrd korrigering i batchen är användningen av filter_predicate nyckel tillgänglig för korrigeringsåtgärden, eller om du vill använda etags med någon av åtgärderna, är även användningen av if_match_etag/if_none_match_etag nycklar tillgänglig.

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

Viktigt!

Om det uppstår ett fel har den misslyckade åtgärden statuskoden för motsvarande fel. Alla andra åtgärder har statuskoden 424 (misslyckat beroende). Om åtgärden misslyckas eftersom den försöker skapa ett objekt som redan finns returneras en statuskod på 409 (konflikt). Statuskoden gör det möjligt för en att identifiera orsaken till transaktionsfelet.

Så här körs transaktionella batchåtgärder

När transactional Batch körs grupperas alla åtgärder i transactional Batch, serialiseras till en enda nyttolast och skickas som en enda begäran till Azure Cosmos DB-tjänsten.

Tjänsten tar emot begäran och kör alla åtgärder inom ett transaktionsomfång och returnerar ett svar med samma serialiseringsprotokoll. Det här svaret är antingen ett lyckat eller ett fel och tillhandahåller enskilda åtgärdssvar per åtgärd.

SDK:t exponerar svaret så att du kan verifiera resultatet och eventuellt extrahera vart och ett av de interna åtgärdsresultaten.

Begränsningar

För närvarande finns det två kända gränser:

• Storleksgränsen för Azure Cosmos DB-begäranden begränsar storleken på transaktionsbatchnyttolasten till högst 2 MB och den maximala körningstiden är 5 sekunder.
• Det finns en aktuell gräns på 100 åtgärder per transaktionell batch för att säkerställa att prestanda är som förväntat och inom serviceavtal.

Nästa steg

• Läs mer om vad du kan göra med TransactionalBatch

• Besök våra exempel för fler sätt att använda vår Azure Cosmos DB .NET SDK