DynamoDB PutItem mit der AWS CLI

aws dynamodb put-item schreibt ein ganzes Item und ersetzt jedes vorhandene Item mit demselben Primärschlüssel (Item-basierte Aktionen erklärt, wie sich das von update-item unterscheidet). Was die CLI selbst zum Problem beiträgt, ist die Shell: --item nimmt DynamoDB JSON als ein einzelnes gequotetes Argument, und jeder Attributwert ist typisiert.

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

Bei Erfolg gibt der Befehl nichts aus und beendet sich mit 0. Existiert das Item bereits, schlägt die Bedingung fehl:

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

Erklärung

Schweigen und Exit 0 sind das einzige Erfolgssignal. put-item gibt kein JSON aus, solange du nicht --return-values verlangst — ein Skript, das stdout nach einer Bestätigung durchsucht, wird also nie auslösen. Prüfe $?. Der obige Befehl zweimal ausgeführt, mit aws-cli/2.36.9:

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 heißt „der Dienst hat Nein gesagt", nicht „die CLI ist kaputt". Die AWS CLI reserviert 252/253 für ihre eigenen Syntax- und Konfigurationsprobleme und 255 für alles Übrige — eine ConditionalCheckFailedException, eine ValidationException und eine Drosselung landen also alle auf derselben 254. Wenn dein Skript ein erwartetes Bedingungs-Fehlschlagen von einem echten Fehler unterscheiden muss, parse den Fehlernamen, nicht den Exit-Code. Beachte außerdem: 2.36.9 stellt der Meldung aws: [ERROR]: voran, was ältere Builds nicht taten — ein auf ^An error occurred verankerter Regex hört nach einem CLI-Upgrade also stillschweigend auf zu greifen.

Ein fehlgeschlagener bedingter Write kostet dich trotzdem. Die Bedingung wird vom Dienst ausgewertet, nachdem er das Item gefunden hat, und AWS ist eindeutig: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (abgerufen am 2026-07-28). Eine Retry-Schleife um einen Nur-Erstellen-Put stellt jeden Versuch in Rechnung. Zur Einordnung: --return-consumed-capacity TOTAL bei einem erfolgreichen Put eines ~15 KB großen Items meldete "CapacityUnits": 15. Writes runden auf 1 KB, nicht auf die 4 KB, die Reads verwenden.

--return-values-on-condition-check-failure funktioniert, aber die CLI versteckt die Antwort. Das ist das Flag, das dir sagt, welches Item den Write blockiert hat, ohne einen zweiten Read. Füge es hinzu, und 2.36.9 gibt aus:

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.

Das Item steckt die ganze Zeit in der Antwort; der Standard-Fehlerformatierer weigert sich nur, es darzustellen. Mit --cli-error-format json bekommst du es. (--return-values ALL_OLD ist der bedingungslose Vetter und greift nur bei Erfolg; ReturnValues behandelt die fünf Optionen.)

Quoting ist die andere Hälfte der Arbeit. Das --item-Argument ist ein Shell-Token, das JSON enthält, das wiederum gequotete Zahlen enthält ({"N": "1994"}, niemals 1994). Alles mit einem Apostroph darin und jedes Item jenseits von ein paar hundert Bytes ist als --item file://song.json einfacher. --cli-input-json file://request.json geht weiter und nimmt die gesamte Anfrage inklusive Condition Expression — und das ist auch die Form, die du im Review diffen kannst.

Die Aliase sind keine optionale Deko. #cond0/#cond1 lösen über --expression-attribute-names zu Artist/SongTitle auf. Die Namen direkt hineinzuschreiben funktioniert genau so lange, bis einer davon mit einem reservierten Wort kollidiert — und dann scheitert der Befehl an einem Namen, den du gar nicht angefasst hast.

Mach es visuell

Typisiertes JSON für --item von Hand zu tippen ist die Stelle, an der die meisten dieser Befehle sterben. Der kostenlose DynamoDB-JSON-Konverter nimmt gewöhnliches JSON und liefert die {"S": …}- / {"N": …}-Form zurück, die das Flag erwartet — fertig zum Speichern als file://-Payload.

Um Items in deinen eigenen Tabellen anzulegen und zu bearbeiten — ein Formular je Attribut, Typ-Auswahl, das Ergebnis als CLI-Befehl wieder herauskopieren — lade DynoTable herunter.

Verwandte Leitfäden

• DynamoDB Condition Expressions — attribute_not_exists, optimistisches Sperren und mehr.
• DynamoDB-Datentypen — wie jeder Attributtyp in DynamoDB JSON geschrieben wird.
• DynamoDB ConditionalCheckFailedException — was die Nur-Erstellen-Bedingung wirft, wenn das Item schon existiert.
• DynamoDB ValidationException — der Sammeltopf für ein fehlerhaftes Item oder eine fehlerhafte Expression.

Referenzen

• PutItem — Amazon DynamoDB API Reference
• put-item — AWS CLI Command Reference
• Understanding return codes — AWS CLI User Guide
• Condition expressions — Amazon DynamoDB Developer Guide
• Working with items and attributes — Amazon DynamoDB Developer Guide

Am 2026-07-28 mit aws-cli/2.36.9 gegen DynamoDB Local (amazon/dynamodb-local) auf Port 9000 reproduziert. Die Exit-Codes, der Fehlertext und der Kapazitätswert sind mitgeschnittene Ausgabe. Die Aussage zur Kapazität fehlgeschlagener Writes ist aus der AWS-Dokumentation zitiert und nicht gemessen: DynamoDB Local liefert auf dem Bedingungs-Fehlschlag-Pfad keine ConsumedCapacity.