Transactionele batchbewerkingen in Azure Cosmos DB

VAN TOEPASSING OP: NoSQL

Transactionele batch beschrijft een groep puntbewerkingen die samen met dezelfde partitiesleutel in een container moeten slagen of mislukken. Bewerkingen worden gedefinieerd, toegevoegd aan de batch en de batch wordt uitgevoerd. Als alle bewerkingen slagen in de volgorde waarin ze worden beschreven in de transactionele batchbewerking, wordt de transactie doorgevoerd. Als een bewerking echter mislukt, wordt de hele transactie teruggedraaid.

Wat is een transactie in Azure Cosmos DB?

Een transactie in een typische database kan worden gedefinieerd als een reeks bewerkingen die worden uitgevoerd als één logische werkeenheid. Elke transactie biedt ACID-eigenschapsgaranties (Atomiciteit, Consistentie, Isolatie, Duurzaamheid).

• Atomiciteit garandeert dat alle bewerkingen die binnen een transactie worden uitgevoerd, worden behandeld als één eenheid, en dat ze allemaal worden doorgevoerd of geen van deze bewerkingen.
• Consistentie zorgt ervoor dat de gegevens altijd een geldige status hebben tussen transacties.
• Isolatie garandeert dat geen twee transacties elkaar verstoren: veel commerciële systemen bieden meerdere isolatieniveaus die kunnen worden gebruikt op basis van de toepassingsbehoeften.
• Duurzaamheid zorgt ervoor dat elke wijziging die wordt doorgevoerd in een database altijd aanwezig is. Azure Cosmos DB ondersteunt volledige ACID-compatibele transacties met momentopname-isolatie voor bewerkingen binnen dezelfde logische partitiesleutel.

Transactionele batchbewerkingen en opgeslagen procedures

Azure Cosmos DB ondersteunt momenteel opgeslagen procedures, die ook het transactionele bereik bieden voor bewerkingen. Transactionele batchbewerkingen bieden echter de volgende voordelen:

• Taaloptie : transactionele batch wordt ondersteund op de SDK en de taal waarmee u al werkt, terwijl opgeslagen procedures moeten worden geschreven in JavaScript.
• Codeversiebeheer : toepassingscode voor versiebeheer en onboarding in uw CI/CD-pijplijn is veel natuurlijker dan het organiseren van de update van een opgeslagen procedure en ervoor zorgen dat de rollover op het juiste moment plaatsvindt. Het maakt ook het terugdraaien van wijzigingen eenvoudiger.
• Prestaties : verminderde latentie voor equivalente bewerkingen met maximaal 30% in vergelijking met de uitvoering van de opgeslagen procedure.
• Inhoudsserialisatie : elke bewerking in een transactionele batch kan aangepaste serialisatieopties gebruiken voor de nettolading.

Een transactionele batchbewerking maken

.NET

Wanneer u een transactionele batchbewerking maakt, begint u met een containerinstantie en roept u CreateTransactionalBatch aan:

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

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Voeg vervolgens meerdere bewerkingen toe aan de batch:

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

Roep ten slotte ExecuteAsync aan in de batch:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Zodra het antwoord is ontvangen, controleert u of het antwoord is geslaagd. Als het antwoord aangeeft dat het is gelukt, extraheert u de resultaten:

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

Belangrijk

Als er een fout optreedt, heeft de mislukte bewerking een statuscode van de bijbehorende fout. Alle andere bewerkingen hebben een 424-statuscode (mislukte afhankelijkheid). Als de bewerking mislukt omdat er wordt geprobeerd een item te maken dat al bestaat, wordt een statuscode van 409 (conflict) geretourneerd. Met de statuscode kunt u de oorzaak van transactiefouten identificeren.

Java

Wanneer u een transactionele batchbewerking maakt, roept u CosmosBatch.createCosmosBatch aan:

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

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Voeg vervolgens meerdere bewerkingen toe aan de batch:

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

Gebruik ten slotte een containerinstantie om executeCosmosBatch aan te roepen met de batch:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Zodra het antwoord is ontvangen, controleert u of het antwoord is geslaagd. Als het antwoord aangeeft dat het is gelukt, extraheert u de resultaten:

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

Belangrijk

Als er een fout optreedt, heeft de mislukte bewerking een statuscode van de bijbehorende fout. Alle andere bewerkingen hebben een 424-statuscode (mislukte afhankelijkheid). Als de bewerking mislukt omdat er wordt geprobeerd een item te maken dat al bestaat, wordt een statuscode van 409 (conflict) geretourneerd. Met de statuscode kunt u de oorzaak van transactiefouten identificeren.

Python

Een containerinstantie ophalen of maken:

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

In Python lijken transactionele Batch-bewerkingen erg op de enkelvoudige bewerkings-API's en zijn tuples die (operation_type_string, args_tuple, batch_operation_kwargs_dictionary) bevatten. Hieronder vindt u voorbeelditems die worden gebruikt om de functionaliteit van batchbewerkingen te demonstreren:

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

Bereid de bewerkingen voor die moeten worden toegevoegd aan de batch:

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

Voeg de bewerkingen toe aan de batch:

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

Voer ten slotte de batch uit:

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]

Opmerking voor het gebruik van patchbewerking en replace_if_match_etag bewerking in de batch
De kwargs-woordenlijst voor batchbewerking is beperkt en neemt slechts drie verschillende sleutelwaarden in beslag. In het geval van het gebruik van voorwaardelijke patching in de batch, is het gebruik van filter_predicate sleutel beschikbaar voor de patchbewerking, of in het geval van het gebruik van etags met een van de bewerkingen, is het gebruik van de if_match_etag/if_none_match_etag sleutels ook beschikbaar.

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

Belangrijk

Als er een fout optreedt, heeft de mislukte bewerking een statuscode van de bijbehorende fout. Alle andere bewerkingen hebben een 424-statuscode (mislukte afhankelijkheid). Als de bewerking mislukt omdat er wordt geprobeerd een item te maken dat al bestaat, wordt een statuscode van 409 (conflict) geretourneerd. Met de statuscode kunt u de oorzaak van transactiefouten identificeren.

Hoe worden transactionele batchbewerkingen uitgevoerd

Wanneer de Transactionele Batch wordt uitgevoerd, worden alle bewerkingen in de transactionele batch gegroepeerd, geserialiseerd in één nettolading en verzonden als één aanvraag naar de Azure Cosmos DB-service.

De service ontvangt de aanvraag en voert alle bewerkingen uit binnen een transactioneel bereik en retourneert een antwoord met hetzelfde serialisatieprotocol. Dit antwoord is een succes of een fout en levert afzonderlijke bewerkingsreacties per bewerking.

De SDK toont het antwoord voor u om het resultaat te verifiëren en, optioneel, elk van de interne bewerkingsresultaten te extraheren.

Beperkingen

Er zijn momenteel twee bekende limieten:

• De maximale aanvraaggrootte van Azure Cosmos DB beperkt de grootte van de transactionele Batch-nettolading tot niet meer dan 2 MB en de maximale uitvoeringstijd is 5 seconden.
• Er is een huidige limiet van 100 bewerkingen per transactionele batch om ervoor te zorgen dat de prestaties naar verwachting en binnen SLA's worden uitgevoerd.

Volgende stappen

• Meer informatie over wat u kunt doen met TransactionalBatch

• Bezoek onze voorbeelden voor meer manieren om onze Azure Cosmos DB .NET SDK te gebruiken