Transaktionale Batchvorgänge in Azure Cosmos DB

Beim Erstellen eines transaktionalen Batchvorgangs beginnen Sie mit einer Containerinstanz und rufen CreateTransactionalBatch auf:

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

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Fügen Sie als Nächstes mehrere Vorgänge zum Batch hinzu:

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

Rufen Sie schließlich ExecuteAsync für den Batch auf:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Nachdem die Antwort empfangen wurde, überprüfen Sie, ob die Antwort erfolgreich war. Wenn die Antwort einen Erfolg angibt, extrahieren Sie die Ergebnisse:

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

Rufen Sie beim Erstellen eines Transaktionsbatchvorgangs CosmosBatch.createCosmosBatch auf:

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

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Fügen Sie als Nächstes mehrere Vorgänge zum Batch hinzu:

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

Verwenden Sie schließlich eine Containerinstanz, um executeCosmosBatch mit dem Batch aufzurufen:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Nachdem die Antwort empfangen wurde, überprüfen Sie, ob die Antwort erfolgreich war. Wenn die Antwort einen Erfolg angibt, extrahieren Sie die Ergebnisse:

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

Rufen Sie eine Containerinstanz ab, oder erstellen Sie eine:

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

In Python ähneln Transaktionale Batchvorgänge den Singular-Operations-APIs und sind Tupel, die (operation_type_string, args_tuple, batch_operation_kwargs_dictionary) enthalten. Nachfolgend finden Sie Beispielelemente, die zum Veranschaulichen der Funktionsweise von Batchvorgängen verwendet werden:

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://video2.skills-academy.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"
}

Bereiten Sie die Vorgänge vor, die zum Batch hinzugefügt werden sollen:

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

Fügen Sie die Vorgänge zum Batch hinzu:

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

Führen Sie den Batch schließlich aus:

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]

Hinweis zur Verwendung des patch-Vorgangs und des replace_if_match_etag-Vorgangs im Batch
Der Vorgang „batch_operation_kwargs_dictionary“ ist eingeschränkt und akzeptiert nur drei verschiedene Schlüsselwerte. Wenn Sie bedingtes Patching innerhalb des Batchs verwenden möchten, kann der filter_predicate-Schlüssel für den patch-Vorgang verwendet werden. Falls Sie Etags mit einem der Vorgänge verwenden möchten, ist auch die Verwendung der if_match_etag- und if_none_match_etag-Schlüssel möglich.

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

Wenn ein Fehler auftritt, weist der fehlerhafte Vorgang einen Statuscode für den jeweiligen Fehler auf. Alle anderen Vorgänge weisen Statuscode 424 auf (Abhängigkeit mit Fehlern). Wenn der Vorgang fehlschlägt, weil versucht wird, ein bereits vorhandenes Element zu erstellen, wird der Statuscode 409 (Konflikt) zurückgegeben. Über die Statuscodes können Sie die Ursache eines Transaktionsfehlers ermitteln.

Ausführung von transaktionalen Batchvorgängen

Wenn der Transaktionsbatch ausgeführt wird, werden alle Vorgänge im Transaktionsbatch gruppiert, in eine einzelne Nutzdateneinheit serialisiert und als einzelne Anforderung an den Azure Cosmos DB-Dienst gesendet.

Der Dienst empfängt die Anforderung, führt alle Vorgänge innerhalb eines Transaktionsbereichs aus und gibt eine Antwort mit dem gleichen Serialisierungsprotokoll zurück. Diese Antwort ist entweder eine erfolgreiche oder fehlerhafte Ausführung und enthält alle einzelnen Vorgangsantworten.

Das SDK stellt Ihnen die Antwort bereit, damit Sie das Ergebnis überprüfen und optional die einzelnen internen Vorgangsergebnisse extrahieren können.

Einschränkungen

Derzeit bestehen zwei bekannte Einschränkungen:

• Die Größenbeschränkung für Anforderungen in Azure Cosmos DB legt fest, dass die Größe der Transaktionsbatchnutzdaten 2 MB nicht überschreiten darf und die maximale Ausführungszeit 5 Sekunden beträgt.
• Es besteht derzeit eine Begrenzung auf 100 Vorgänge pro Transaktionsbatch. Damit soll sichergestellt werden, dass die Leistung den Erwartungen entspricht und innerhalb der SLAs liegt.

Nächste Schritte

• Erfahren Sie mehr darüber, welche Möglichkeiten TransactionalBatch bietet.

• Sehen Sie sich die Beispiele an, um weitere Möglichkeiten zur Verwendung unseres Azure Cosmos DB .NET SDK kennenzulernen.