PutItem DynamoDB avec l'AWS CLI

aws dynamodb put-item écrit un élément entier et remplace tout élément existant portant la même clé primaire (les actions au niveau de l'élément expliquent en quoi cela diffère d'update-item). La contribution propre de la CLI au problème, c'est le shell : --item prend du DynamoDB JSON sous forme d'un seul argument entre guillemets, et chaque valeur d'attribut est typée.

Code

aws dynamodb put-item \
  --table-name 'Music' \
  --item '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"},"AlbumTitle":{"S":"Danzon"},"Year":{"N":"1994"},"Awards":{"N":"0"}}' \
  --condition-expression 'attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)' \
  --expression-attribute-names '{"#cond0":"Artist","#cond1":"SongTitle"}'

En cas de succès, la commande n'affiche rien et sort avec le code 0. Si l'élément existe déjà, la condition échoue :

An error occurred (ConditionalCheckFailedException) when calling the PutItem operation:
The conditional request failed

Explication

Le silence et le code de sortie 0 sont le seul signal de succès. put-item n'affiche aucun JSON tant que tu ne demandes pas --return-values : un script qui cherche une confirmation dans stdout ne se déclenchera jamais. Contrôle $?. Lancer deux fois la commande ci-dessus sur aws-cli/2.36.9 a donné :

first run:   (no output)                exit 0
second run:  aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed
             exit 254

254 signifie « le service a dit non », pas « la CLI a planté ». L'AWS CLI réserve 252/253 à ses propres problèmes de syntaxe et de configuration, et 255 à tout le reste : une ConditionalCheckFailedException, une ValidationException et un throttle atterrissent donc tous sur le même 254. Si ton script doit distinguer un échec de condition attendu d'une vraie faute, analyse le nom de l'erreur, pas le code de sortie. Note aussi que 2.36.9 préfixe le message par aws: [ERROR]: , ce que les versions plus anciennes ne faisaient pas ; une regex ancrée sur ^An error occurred cessera silencieusement de correspondre après une mise à jour de la CLI.

Une écriture conditionnelle en échec te coûte quand même. La condition est évaluée par le service après qu'il a localisé l'élément, et AWS est explicite : "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (récupéré le 2026-07-28). Une boucle de reprise autour d'un put « création uniquement » facture chaque tentative. Pour l'ordre de grandeur, --return-consumed-capacity TOTAL sur un put réussi d'un élément d'environ 15 Ko a rapporté "CapacityUnits": 15. Les écritures s'arrondissent au Ko, pas aux 4 Ko des lectures.

--return-values-on-condition-check-failure fonctionne, mais la CLI cache la réponse. C'est le flag qui te dit quel élément a bloqué l'écriture, sans seconde lecture. Ajoute-le et 2.36.9 affiche :

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed

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

L'élément est dans la réponse depuis le début ; c'est le formateur d'erreurs par défaut qui refuse de l'afficher. Ajoute --cli-error-format json pour l'obtenir. (--return-values ALL_OLD est le cousin inconditionnel et ne se déclenche qu'en cas de succès ; ReturnValues détaille les cinq options.)

L'échappement est l'autre moitié du travail. L'argument --item est un unique token shell contenant du JSON contenant des nombres entre guillemets ({"N": "1994"}, jamais 1994). Tout ce qui contient une apostrophe, et tout élément dépassant quelques centaines d'octets, passe plus facilement par --item file://song.json. --cli-input-json file://request.json va plus loin et prend la requête entière, expression de condition comprise — c'est aussi la forme que tu peux differ en revue.

Les alias ne sont pas de la décoration optionnelle. #cond0/#cond1 résolvent vers Artist/SongTitle via --expression-attribute-names. Écrire les noms en clair fonctionne jusqu'au jour où l'un d'eux entre en collision avec un mot réservé, et la commande échoue alors sur un nom que tu n'as pas touché.

Le faire visuellement

Taper à la main du JSON typé pour --item est l'endroit où meurent la plupart de ces commandes. Le convertisseur DynamoDB JSON gratuit prend du JSON ordinaire et renvoie la forme {"S": …} / {"N": …} attendue par le flag, prête à enregistrer comme charge utile file://.

Pour ajouter et modifier des éléments dans tes propres tables — un formulaire par attribut, des sélecteurs de type, la copie du résultat sous forme de commande CLI — télécharge DynoTable.

Guides liés

Expressions de condition DynamoDB — attribute_not_exists, verrouillage optimiste, et plus encore.
Types de données DynamoDB — comment chaque type d'attribut s'écrit en DynamoDB JSON.
DynamoDB ConditionalCheckFailedException — ce que lève la condition « création uniquement » quand l'élément existe déjà.
DynamoDB ValidationException — le fourre-tout d'un élément ou d'une expression malformés.

Références

Reproduit le 2026-07-28 avec aws-cli/2.36.9 sur DynamoDB Local (amazon/dynamodb-local) sur le port 9000. Les codes de sortie, le texte d'erreur et la mesure de capacité sont la sortie capturée. L'affirmation sur le coût d'une écriture en échec est citée de la documentation AWS plutôt que mesurée : DynamoDB Local ne renvoie aucun ConsumedCapacity sur le chemin de l'échec de condition.