PutItem do DynamoDB com a AWS CLI

aws dynamodb put-item escreve um item inteiro e substitui qualquer item existente com a mesma chave primária (ações baseadas em item explica como isso difere do update-item). A contribuição da própria CLI para o problema é o shell: --item recebe DynamoDB JSON como um único argumento entre aspas, e todo valor de atributo é tipado.

Código

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

Em caso de sucesso o comando não imprime nada e sai com 0. Se o item já existir, a condição falha:

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

Explicação

Silêncio e saída 0 são o único sinal de sucesso. O put-item não imprime JSON algum a menos que você peça --return-values, então um script que faz grep no stdout atrás de confirmação nunca vai disparar. Verifique o $?. Rodar o comando acima duas vezes no aws-cli/2.36.9 deu:

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 é "o serviço disse não", não "a CLI quebrou". A AWS CLI reserva 252/253 para seus próprios problemas de sintaxe e configuração e 255 para todo o resto, então uma ConditionalCheckFailedException, uma ValidationException e um throttle caem todos no mesmo 254. Se o seu script precisa distinguir uma falha de condição esperada de uma falha real, analise o nome do erro, não o código de saída. Note também que a 2.36.9 prefixa a mensagem com aws: [ERROR]: , o que builds mais antigas não faziam; uma regex ancorada em ^An error occurred vai silenciosamente parar de casar depois de uma atualização da CLI.

Uma escrita condicional que falha ainda te custa. A condição é avaliada pelo serviço depois que ele localizou o item, e a AWS é explícita: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (consultado em 2026-07-28). Um loop de retry em volta de um put do tipo criar-somente cobra cada tentativa. Para ter uma escala, --return-consumed-capacity TOTAL em um put bem-sucedido de um item de ~15 KB reportou "CapacityUnits": 15. Escritas arredondam para 1 KB, não para os 4 KB que as leituras usam.

--return-values-on-condition-check-failure funciona, mas a CLI esconde a resposta. Essa é a flag que te diz qual item bloqueou a escrita, sem uma segunda leitura. Adicione-a e a 2.36.9 imprime:

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.

O item está na resposta o tempo todo; o formatador de erro padrão se recusa a renderizá-lo. Adicione --cli-error-format json para obtê-lo. (--return-values ALL_OLD é o primo incondicional e só dispara em caso de sucesso; ReturnValues cobre as cinco opções.)

As aspas são a outra metade do trabalho. O argumento --item é um único token de shell contendo JSON contendo números entre aspas ({"N": "1994"}, nunca 1994). Qualquer coisa com um apóstrofo, e qualquer item além de algumas centenas de bytes, fica mais fácil como --item file://song.json. --cli-input-json file://request.json vai além e recebe a requisição inteira, expressão de condição incluída, que é também a forma que você consegue revisar num diff.

Os aliases não são decoração opcional. #cond0/#cond1 resolvem para Artist/SongTitle através de --expression-attribute-names. Escrever os nomes inline funciona até o momento em que um deles colide com uma palavra reservada, quando então o comando falha por um nome que você não mudou.

Faça isso visualmente

Digitar à mão o JSON tipado para --item é onde a maioria desses comandos morre. O conversor de DynamoDB JSON gratuito recebe JSON comum e devolve a forma {"S": …} / {"N": …} que a flag quer, pronta para salvar como o payload do file://.

Para adicionar e editar itens nas suas próprias tabelas — um formulário por atributo, seletores de tipo, copiar o resultado de volta como um comando de CLI — baixe o DynoTable.

Guias relacionados

Expressões de condição do DynamoDB — attribute_not_exists, travamento otimista e mais.
Tipos de dados do DynamoDB — como cada tipo de atributo é escrito em DynamoDB JSON.
DynamoDB ConditionalCheckFailedException — o que a condição de criar-somente lança quando o item já existe.
DynamoDB ValidationException — o pega-tudo para um item ou expressão malformados.

Referências

Reproduzido em 2026-07-28 com aws-cli/2.36.9 contra o DynamoDB Local (amazon/dynamodb-local) na porta 9000. Os códigos de saída, o texto do erro e a leitura de capacidade são saída capturada. A afirmação sobre a capacidade da escrita que falha é citada da documentação da AWS em vez de medida: o DynamoDB Local não retorna ConsumedCapacity no caminho de falha de condição.