DynamoDB TransactWriteItems mit der AWS CLI

Die gesamte Transaktion geht als ein einziges --transact-items JSON-Array an aws dynamodb transact-write-items — die Kanten der CLI sind also der interessante Teil: wo das Quoting bricht, was der Exit-Code bedeutet und die Tatsache, dass die Standard-Fehlerausgabe genau das Feld unterschlägt, das du zum Debuggen einer Stornierung brauchst. Was dir eine Transaktion bringt ist in jedem SDK gleich.

Code

aws dynamodb transact-write-items \
  --transact-items '[
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        "UpdateExpression": "SET #upd0 = #upd0 - :one",
        "ConditionExpression": "#upd0 >= :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}}
      }
    },
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        "UpdateExpression": "SET #upd0 = if_not_exists(#upd0, :zero) + :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}, ":zero": {"N": "0"}}
      }
    }
  ]'

Eine committete Transaktion gibt nichts aus und endet mit 0. Es gibt keinen Response-Body zu prüfen, in einem Skript ist der Exit-Code also das Ergebnis.

Erklärung

--transact-items — bis zu 100 Put- / Update- / Delete- / ConditionCheck-Aktionen, 4 MB insgesamt, Werte in DynamoDB JSON. Aktionen dürfen sich über Tabellen im selben Konto und derselben Region erstrecken, und keine zwei davon dürfen dasselbe Item betreffen.
Drei Exit-Codes, drei verschiedene Fehlschläge. 0 heißt committet. 252 heißt, die Parametervalidierung der CLI selbst hat die Anfrage abgelehnt und nichts wurde gesendet. 254 heißt, DynamoDB hat geantwortet und Nein gesagt. Diese Unterscheidung lohnt eine Verzweigung: Eine 252 ist ein Fehler in deinem JSON, eine 254 kann eine Bedingung sein, deren Scheitern du erwartet hast.

Das Standard-Fehlerformat unterschlägt die Gründe pro Aktion. aws-cli v2 gibt die Zusammenfassung aus und sagt dir dann, dass es das Detail zurückhält:

aws: [ERROR]: An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

Führe denselben Befehl mit --cli-error-format json erneut aus, und die Struktur kommt vollständig an, ein Eintrag pro Aktion, in der Reihenfolge von --transact-items:

{
    "Message": "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]",
    "Code": "TransactionCanceledException",
    "CancellationReasons": [
        {
            "Code": "ConditionalCheckFailed",
            "Message": "The conditional request failed"
        },
        {
            "Code": "None"
        }
    ]
}

Hier ist die Awards >= 1-Bedingung des ersten Updates gescheitert; None weist die zweite Aktion als unschuldig aus — und beachte, dass sie gar kein Message-Feld trägt. Jeder weitere Code ist auf der Seite zur TransactionCanceledException entschlüsselt.

Dasselbe Item zweimal anzusprechen ist keine Stornierung. Das scheitert an der Validierung, bevor irgendetwas versucht wird — deshalb gibt es auch keine Gründe auszugeben:
```
aws: [ERROR]: An error occurred (ValidationException) when calling the TransactWriteItems operation: Transaction request cannot include multiple operations on one item
```
ConditionCheck — prüft eine Bedingung auf einem Item, das die Transaktion nicht verändert, und legt bei Scheitern ihr Veto gegen die gesamte Transaktion ein.
--client-request-token — ein fester Token macht erneute Läufe für 10 Minuten idempotent. Verwende denselben Token mit auch nur einem geänderten Parameter, und DynamoDB liefert IdempotentParameterMismatch, statt stillschweigend die neue Nutzlast anzuwenden.
Halte das Array in einer Datei. --transact-items file://transaction.json umgeht das Shell-Quoting vollständig, und die Datei ist diffbar.

Das Doppelte lässt sich aus der Shell messen

Führe dasselbe Einzel-Item-Update zweimal aus, einmal in einer Transaktion und einmal außerhalb, beide mit --return-consumed-capacity TOTAL. DynamoDB Local meldet 2.0 Kapazitätseinheiten für den transaktionalen Write und 1.0 für den einfachen: Vorbereitung und Commit werden jeweils berechnet.

Das ist das ganze Argument dagegen, standardmäßig zur Transaktion zu greifen. Für Atomarität auf einem einzelnen Item hast du mit einem bedingten Write bereits ein günstigeres Werkzeug, das nur einmal berechnet wird. Um einen Workload zu kalkulieren, der das millionenfach macht, nimmt der DynamoDB-Preisrechner die verdoppelte Write-Anzahl direkt entgegen. Und wenn das Zusammenbauen von DynamoDB JSON in einer Shell das ist, womit du aufhören willst: DynoTable bearbeitet Items gegen eine echte Tabelle und zeigt dir die erzeugte Expression.

Referenzen

Zuletzt verifiziert am 2026-07-28 gegen die oben verlinkte offizielle AWS-Dokumentation.

DynamoDB TransactWriteItems mit der AWS CLI

Code

Erklärung

Das Doppelte lässt sich aus der Shell messen

Verwandte Beispiele

Referenzen