DynamoDB TransactWriteItems con la AWS CLI

L'intera transazione arriva a aws dynamodb transact-write-items come un unico array JSON --transact-items, quindi la parte interessante sono gli spigoli della CLI: dove si rompe il quoting, cosa significa il codice di uscita e il fatto che l'output di errore predefinito scarta proprio il campo che ti serve per fare debug di un annullamento. Cosa ti dà una transazione è uguale in ogni SDK.

Codice

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

Una transazione confermata non stampa nulla ed esce con 0. Non c'è alcun corpo di risposta da controllare, quindi in uno script il risultato è il codice di uscita.

Spiegazione

--transact-items — fino a 100 azioni Put / Update / Delete / ConditionCheck, 4 MB complessivi, valori in JSON DynamoDB. Le azioni possono attraversare tabelle diverse dello stesso account e della stessa regione, e due di esse non possono puntare allo stesso Item.
Tre codici di uscita, tre fallimenti diversi. 0 confermata. 252 significa che la convalida dei parametri della CLI stessa ha rifiutato la richiesta e non è stato inviato nulla. 254 significa che DynamoDB ha risposto e ha detto no. Su quella distinzione vale la pena ramificare: un 252 è un bug nel tuo JSON, un 254 può essere una condizione che ti aspettavi fallisse.

Il formato di errore predefinito scarta i motivi per azione. aws-cli v2 stampa il riepilogo e poi ti dice che sta trattenendo il dettaglio:

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.

Riesegui lo stesso comando con --cli-error-format json e la struttura arriva intatta, una voce per azione, nell'ordine di --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"
        }
    ]
}

Qui è fallita la condizione Awards >= 1 del primo update; None marca la seconda azione come innocente, e nota che non porta affatto un campo Message. Ogni altro codice è decodificato nella pagina di TransactionCanceledException.

Puntare due volte allo stesso Item non è un annullamento. Fallisce la convalida prima che si tenti qualsiasi cosa, ed è per questo che non ci sono motivi da stampare:
```
aws: [ERROR]: An error occurred (ValidationException) when calling the TransactWriteItems operation: Transaction request cannot include multiple operations on one item
```
ConditionCheck — afferma una condizione su un Item che la transazione non modifica, e mette il veto sull'intera transazione se fallisce.
--client-request-token — un token fisso rende le ri-esecuzioni idempotenti per 10 minuti. Riusa lo stesso token con un parametro qualsiasi cambiato e DynamoDB restituisce IdempotentParameterMismatch invece di applicare silenziosamente il nuovo payload.
Tieni l'array in un file. --transact-items file://transaction.json aggira completamente il quoting della shell, e il file è diffabile.

Il 2× si misura dalla shell

Esegui due volte lo stesso update su un singolo Item, una dentro una transazione e una fuori, entrambe con --return-consumed-capacity TOTAL. DynamoDB Local riporta 2.0 unità di capacità per la scrittura transazionale e 1.0 per quella semplice: la fase di prepare e quella di commit fatturano ciascuna.

È tutto l'argomento contro l'usare una transazione per default. Per l'atomicità su un singolo Item hai già uno strumento più economico in una scrittura condizionale, che fattura una volta sola. Per stimare il prezzo di un carico di lavoro che fa questo milioni di volte, il calcolatore dei prezzi DynamoDB prende direttamente il conteggio di scritture raddoppiato. Se la parte che vuoi smettere di fare è assemblare JSON DynamoDB in una shell, DynoTable modifica gli Item su una tabella reale e ti mostra l'espressione che ha generato.

Esempi correlati

DynamoDB TransactWriteItems in Node.js — la stessa transazione con AWS SDK v3.
DynamoDB TransactWriteItems in Python — la stessa transazione con boto3.
DynamoDB BatchWriteItem con la AWS CLI — scritture di massa quando non ti serve l'atomicità.
Transazioni DynamoDB — isolamento, idempotenza e quando le transazioni valgono la pena.
DynamoDB TransactionCanceledException — ogni codice di motivo di annullamento, decodificato.
"Too many actions in a TransactWriteItems call" — i limiti di 100 azioni e 4 MB per transazione.
"Transaction request cannot include multiple operations on one item" — un'azione per Item, per transazione.

Riferimenti

Ultima verifica 2026-07-28 rispetto alla documentazione ufficiale AWS collegata sopra.