Transaktionale Batchvorgänge in Azure Cosmos DB

GILT FÜR: NoSQL

Ein transaktionaler Batch bezeichnet eine Gruppe von Punktvorgängen, die zusammen mit dem gleichen Partitionsschlüssel in einem Container entweder erfolgreich oder fehlerhaft ausgeführt werden müssen. Vorgänge werden definiert, zum Batch hinzugefügt, und der Batch wird ausgeführt. Wenn alle Vorgänge in der Reihenfolge, in der sie im transaktionalen Batchvorgang beschrieben sind, erfolgreich ausgeführt werden, wird für die Transaktion ein Commit ausgeführt. Wenn jedoch ein Vorgang fehlschlägt, wird für die gesamte Transaktion ein Rollback ausgeführt.

Was ist eine Transaktion in Azure Cosmos DB?

Eine Transaktion in einer typischen Datenbank kann als Folge von Vorgängen definiert werden, die als einzige logische Arbeitseinheit ausgeführt werden. Jede Transaktion bietet ACID-Eigenschaftsgarantien (Atomarität, Konsistenz, Isolation, Dauerhaftigkeit).

• Die Atomarität bzw. Unteilbarkeit gewährleistet, dass alle innerhalb einer Transaktion ausgeführten Vorgänge als eine einzige Einheit betrachtet werden und entweder alle Vorgänge committet werden oder keiner von ihnen.
• Die Konsistenz stellt sicher, dass die Daten zwischen den Transaktionen immer einen gültigen Zustand aufweisen.
• Die Isolation sorgt dafür, dass es niemals zu Konflikten zwischen zwei Transaktionen kommt. Viele kommerzielle Systeme bieten mehrere Isolationsstufen, die je nach Anforderungen der Anwendung genutzt werden können.
• Die Dauerhaftigkeit stellt sicher, dass jede Änderung, die in einer Datenbank committet wird, immer vorhanden ist. Azure Cosmos DB unterstützt vollständige ACID-konforme Transaktionen mit Momentaufnahmenisolation für Vorgänge innerhalb desselben logischen Partitionsschlüssels.

Transaktionale Batchvorgänge und gespeicherte Prozeduren

Azure Cosmos DB unterstützt derzeit gespeicherte Prozeduren, die auch den Transaktionsbereich für Vorgänge bereitstellen. Transaktionale Batchvorgänge bieten jedoch die folgenden Vorteile:

• Sprachoption: Transaktionale Batches werden im SDK und in der Sprache unterstützt, mit der Sie bereits arbeiten, während gespeicherte Prozeduren in JavaScript geschrieben werden müssen.
• Codeversionsverwaltung: Die Versionsverwaltung von Anwendungscode und dessen Integration in die CI/CD-Pipeline ist wesentlich natürlicher als die Aktualisierung einer gespeicherten Prozedur zu orchestrieren und sicherzustellen, dass der Rollover zum richtigen Zeitpunkt erfolgt. Außerdem wird das Rollback von Änderungen vereinfacht.
• Leistung: verringerte Latenz bei entsprechenden Vorgängen um bis zu 30 % im Vergleich zur Ausführung gespeicherter Prozeduren
• Serialisierung von Inhalten: Jeder Vorgang in einem Transaktionsbatch kann benutzerdefinierte Serialisierungsoptionen für seine Nutzlast verwenden.

Erstellen eines transaktionalen Batchvorgangs

.NET

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

Wichtig

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.

Java

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

Wichtig

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.

Python

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

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}),
   ]

Wichtig

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.