DynamoDB PutItem dengan AWS CLI

aws dynamodb put-item menulis satu item utuh dan mengganti item mana pun yang sudah ada dengan primary key yang sama (aksi berbasis item membahas bedanya dengan update-item). Sumbangan CLI sendiri terhadap masalah ini adalah shell: --item menerima DynamoDB JSON sebagai satu argumen ber-quote, dan setiap nilai atribut bertipe.

Kode

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

Kalau berhasil, perintah ini tidak mencetak apa pun dan keluar dengan kode 0. Kalau item-nya sudah ada, kondisinya gagal:

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

Penjelasan

Kesunyian dan exit 0 adalah satu-satunya sinyal keberhasilan. put-item tidak mencetak JSON kecuali Anda meminta --return-values, jadi skrip yang men-grep stdout untuk mencari konfirmasi tidak akan pernah terpicu. Periksa $?. Menjalankan perintah di atas dua kali pada aws-cli/2.36.9 menghasilkan:

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 berarti "layanan menolak", bukan "CLI-nya rusak". AWS CLI menyisakan 252/253 untuk masalah sintaks dan konfigurasinya sendiri serta 255 untuk selebihnya, jadi sebuah ConditionalCheckFailedException, sebuah ValidationException, dan sebuah throttle sama-sama mendarat di 254 yang sama. Kalau skrip Anda perlu membedakan kegagalan kondisi yang memang diharapkan dari kesalahan sungguhan, urai nama error-nya, bukan exit code-nya. Perhatikan juga bahwa 2.36.9 memberi awalan aws: [ERROR]: pada pesannya, yang tidak dilakukan build lama; regex yang dijangkarkan pada ^An error occurred akan berhenti cocok secara diam-diam setelah CLI di-upgrade.

Tulis bersyarat yang gagal tetap menagih Anda. Kondisinya dievaluasi oleh layanan setelah ia menemukan item-nya, dan AWS menyatakannya secara eksplisit: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (diambil 2026-07-28). Loop percobaan ulang di sekitar put yang hanya-membuat akan menagih setiap percobaan. Sebagai gambaran skalanya, --return-consumed-capacity TOTAL pada put yang berhasil untuk item ~15 KB melaporkan "CapacityUnits": 15. Tulis dibulatkan ke 1 KB, bukan 4 KB seperti pada pembacaan.

--return-values-on-condition-check-failure berfungsi, tetapi CLI menyembunyikan jawabannya. Inilah flag yang memberi tahu Anda item mana yang menghalangi penulisan, tanpa pembacaan kedua. Tambahkan flag itu dan 2.36.9 mencetak:

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.

Item-nya ada di dalam response sepanjang waktu; formatter error bawaan menolak merendernya. Tambahkan --cli-error-format json untuk mendapatkannya. (--return-values ALL_OLD adalah sepupunya yang tanpa syarat dan hanya terpicu saat berhasil; ReturnValues membahas kelima opsinya.)

Urusan quoting adalah separuh pekerjaan yang lain. Argumen --item adalah satu token shell yang berisi JSON yang berisi angka ber-quote ({"N": "1994"}, tidak pernah 1994). Apa pun yang mengandung apostrof, dan item mana pun yang melewati beberapa ratus byte, lebih mudah ditulis sebagai --item file://song.json. --cli-input-json file://request.json melangkah lebih jauh dan menerima seluruh request, termasuk condition expression-nya, dan itu juga bentuk yang bisa Anda diff saat review.

Aliasnya bukan hiasan opsional. #cond0/#cond1 di-resolve menjadi Artist/SongTitle lewat --expression-attribute-names. Menulis namanya secara inline berjalan lancar sampai salah satunya bertabrakan dengan sebuah reserved word, dan di titik itu perintahnya gagal pada nama yang tidak Anda ubah.

Lakukan secara visual

Mengetik sendiri JSON bertipe untuk --item adalah tempat sebagian besar perintah ini mati. Konverter DynamoDB JSON gratis menerima JSON biasa dan mengembalikan bentuk {"S": …} / {"N": …} yang diminta flag itu, siap disimpan sebagai payload file://.

Untuk menambah dan menyunting item pada tabel Anda sendiri — satu form per atribut, pemilih tipe, salin hasilnya kembali sebagai perintah CLI — unduh DynoTable.

Panduan terkait

Condition expression DynamoDB — attribute_not_exists, optimistic locking, dan lainnya.
Tipe data DynamoDB — bagaimana setiap tipe atribut ditulis dalam DynamoDB JSON.
DynamoDB ConditionalCheckFailedException — yang dilempar kondisi hanya-membuat ketika item-nya sudah ada.
DynamoDB ValidationException — penampung segala untuk item atau expression yang cacat.

Referensi

Direproduksi 2026-07-28 dengan aws-cli/2.36.9 terhadap DynamoDB Local (amazon/dynamodb-local) pada port 9000. Exit code, teks error, dan pembacaan kapasitas di atas adalah keluaran yang ditangkap apa adanya. Klaim kapasitas untuk tulis yang gagal dikutip dari dokumentasi AWS alih-alih diukur: DynamoDB Local tidak mengembalikan ConsumedCapacity pada jalur kegagalan kondisi.