DynamoDB TransactWriteItems avec l'AWS CLI

La transaction entière part vers aws dynamodb transact-write-items sous la forme d'un seul tableau JSON --transact-items : ce sont donc les arêtes de la CLI qui sont intéressantes ici — là où le quoting casse, ce que veut dire le code de sortie, et le fait que la sortie d'erreur par défaut supprime justement le champ dont tu as besoin pour déboguer une annulation. Ce qu'une transaction t'apporte est identique dans tous les SDK.

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

Une transaction validée n'affiche rien et sort avec le code 0. Il n'y a aucun corps de réponse à vérifier : dans un script, c'est le code de sortie qui fait office de résultat.

Explication

--transact-items — jusqu'à 100 actions Put / Update / Delete / ConditionCheck, 4 MB au total, valeurs en JSON DynamoDB. Les actions peuvent couvrir plusieurs tables du même compte et de la même Région, et deux d'entre elles ne peuvent pas viser le même élément.
Trois codes de sortie, trois échecs différents. 0 : validé. 252 : la validation de paramètres propre à la CLI a rejeté la requête et rien n'a été envoyé. 254 : DynamoDB a répondu et a dit non. Cette distinction mérite un branchement : un 252 est un bug dans ton JSON, un 254 peut être une condition dont tu attendais qu'elle échoue.

Le format d'erreur par défaut supprime les raisons par action. aws-cli v2 affiche le résumé puis t'annonce qu'il retient le détail :

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.

Relance la même commande avec --cli-error-format json et la structure arrive intacte, une entrée par action, dans l'ordre de --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"
        }
    ]
}

Ici, c'est la condition Awards >= 1 du premier update qui a échoué ; None marque la seconde action comme innocente, et remarque qu'elle ne porte aucun champ Message. Tous les autres codes sont décodés sur la page TransactionCanceledException.

Viser deux fois le même élément n'est pas une annulation. Ça échoue à la validation avant que quoi que ce soit ne soit tenté, et c'est pour ça qu'il n'y a aucune raison à afficher :
```
aws: [ERROR]: An error occurred (ValidationException) when calling the TransactWriteItems operation: Transaction request cannot include multiple operations on one item
```
ConditionCheck — affirme une condition sur un élément que la transaction ne modifie pas, et met son veto à toute la transaction si elle échoue.
--client-request-token — un token fixe rend les relances idempotentes pendant 10 minutes. Réutilise le même token avec un paramètre modifié et DynamoDB renvoie IdempotentParameterMismatch au lieu d'appliquer silencieusement la nouvelle charge.
Garde le tableau dans un fichier. --transact-items file://transaction.json contourne entièrement le quoting du shell, et le fichier est diffable.

Le facteur 2× se mesure depuis le shell

Exécute deux fois la même mise à jour d'un seul élément, une fois dans une transaction et une fois en dehors, les deux avec --return-consumed-capacity TOTAL. DynamoDB Local annonce 2.0 unités de capacité pour l'écriture transactionnelle et 1.0 pour l'écriture simple : la préparation et la validation sont facturées chacune.

C'est tout l'argument contre le réflexe de prendre une transaction par défaut. Pour de l'atomicité sur un seul élément, tu as déjà un outil moins cher avec l'écriture conditionnelle, qui n'est facturée qu'une fois. Pour chiffrer une charge de travail qui fait ça des millions de fois, le calculateur de tarifs DynamoDB prend directement le nombre d'écritures doublé. Et si c'est l'assemblage de JSON DynamoDB dans un shell que tu veux arrêter, DynoTable modifie des éléments sur une vraie table et te montre l'expression qu'il a générée.

Exemples liés

DynamoDB TransactWriteItems en Node.js — la même transaction avec l'AWS SDK v3.
DynamoDB TransactWriteItems en Python — la même transaction avec boto3.
DynamoDB BatchWriteItem avec l'AWS CLI — des écritures en masse quand tu n'as pas besoin d'atomicité.
Les transactions DynamoDB — isolation, idempotence, et quand les transactions en valent la peine.
DynamoDB TransactionCanceledException — chaque code de raison d'annulation, décodé.
"Too many actions in a TransactWriteItems call" — les limites de 100 actions et 4 MB par transaction.
"Transaction request cannot include multiple operations on one item" — une action par élément, par transaction.

Références

Dernière vérification le 2026-07-28 par rapport à la documentation officielle AWS liée ci-dessus.