PutItem DynamoDB con la AWS CLI

aws dynamodb put-item scrive un item intero e sostituisce qualsiasi item esistente con la stessa chiave primaria (azioni basate sull'item spiega in cosa differisce da update-item). Il contributo della CLI al problema è la shell: --item prende DynamoDB JSON come un unico argomento tra virgolette, e ogni valore di attributo è tipizzato.

Codice

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

In caso di successo il comando non stampa nulla ed esce con 0. Se l'item esiste già, la condizione fallisce:

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

Spiegazione

Il silenzio e l'uscita con 0 sono l'unico segnale di successo. put-item non stampa alcun JSON a meno che tu non chieda --return-values, quindi uno script che cerca una conferma su stdout non scatterà mai. Controlla $?. Eseguendo il comando qui sopra due volte su aws-cli/2.36.9 si ottiene:

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 significa "il servizio ha detto no", non "la CLI si è rotta". La AWS CLI riserva 252/253 ai propri problemi di sintassi e configurazione e 255 a tutto il resto, quindi una ConditionalCheckFailedException, una ValidationException e un throttle finiscono tutti sullo stesso 254. Se il tuo script deve distinguere un fallimento di condizione atteso da un guasto vero, analizza il nome dell'errore, non il codice di uscita. Nota anche che la 2.36.9 antepone al messaggio aws: [ERROR]: , cosa che le build più vecchie non facevano; una regex ancorata a ^An error occurred smetterà silenziosamente di corrispondere dopo un aggiornamento della CLI.

Una scrittura condizionale fallita ti costa comunque. La condizione è valutata dal servizio dopo che ha localizzato l'item, e AWS è esplicita: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (consultato il 2026-07-28). Un loop di retry attorno a una put di sola creazione fattura ogni tentativo. Per dare una scala, --return-consumed-capacity TOTAL su una put riuscita di un item di ~15 KB ha riportato "CapacityUnits": 15. Le scritture arrotondano a 1 KB, non ai 4 KB usati dalle letture.

--return-values-on-condition-check-failure funziona, ma la CLI nasconde la risposta. È il flag che ti dice quale item ha bloccato la scrittura, senza una seconda lettura. Aggiungilo e la 2.36.9 stampa:

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'item è nella risposta per tutto il tempo; è il formattatore di errori predefinito che si rifiuta di renderizzarlo. Aggiungi --cli-error-format json per ottenerlo. (--return-values ALL_OLD è il cugino incondizionato e scatta solo in caso di successo; ReturnValues copre le cinque opzioni.)

Il quoting è l'altra metà del lavoro. L'argomento --item è un unico token di shell che contiene JSON che contiene numeri tra virgolette ({"N": "1994"}, mai 1994). Qualsiasi cosa con un apostrofo dentro, e qualsiasi item oltre qualche centinaio di byte, è più semplice come --item file://song.json. --cli-input-json file://request.json va oltre e prende l'intera richiesta, condition expression inclusa, che è anche la forma che puoi diffare in revisione.

Gli alias non sono decorazione opzionale. #cond0/#cond1 si risolvono in Artist/SongTitle tramite --expression-attribute-names. Scrivere i nomi inline funziona fino a quando uno di essi collide con una parola riservata, momento in cui il comando fallisce su un nome che non hai cambiato.

Fallo visivamente

Digitare a mano il JSON tipizzato per --item è il punto in cui muoiono la maggior parte di questi comandi. Il convertitore DynamoDB JSON gratuito prende JSON normale e restituisce la forma {"S": …} / {"N": …} che il flag vuole, pronta da salvare come payload file://.

Per aggiungere e modificare item sulle tue tabelle — un form per attributo, selettori di tipo, e copiare il risultato come comando CLI — scarica DynoTable.

Guide correlate

Condition expression di DynamoDB — attribute_not_exists, optimistic locking e altro.
Tipi di dati di DynamoDB — come ogni tipo di attributo si scrive in DynamoDB JSON.
DynamoDB ConditionalCheckFailedException — cosa solleva la condizione di sola creazione quando l'item esiste già.
DynamoDB ValidationException — il catch-all per un item o un'espressione malformati.

Riferimenti

Riprodotto il 2026-07-28 con aws-cli/2.36.9 contro DynamoDB Local (amazon/dynamodb-local) sulla porta 9000. I codici di uscita, il testo dell'errore e la lettura di capacità sono output catturato. L'affermazione sul costo della scrittura fallita è citata dalla documentazione AWS anziché misurata: DynamoDB Local non restituisce alcun ConsumedCapacity sul percorso di fallimento della condizione.