使用 AWS CLI 的 DynamoDB PutItem

aws dynamodb put-item 會寫入一整筆項目，並取代任何具有相同主鍵的既有項目（以項目為單位的操作說明了這與 update-item 的差別）。CLI 自己額外帶來的麻煩是 shell：--item 接受的是 DynamoDB JSON，而且要當成單一個加引號的參數傳入，每個屬性值都帶型別。

程式碼

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

成功時這個指令什麼都不會印出，並以 0 結束。如果項目已經存在，條件就會失敗：

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

說明

沉默加上結束碼 0，是唯一的成功訊號。除非你要求 --return-values，否則 put-item 不會印出任何 JSON，所以一個靠 grep stdout 來確認的腳本永遠不會觸發。請檢查 $?。在 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 表示服務說不行，而不是 CLI 壞了。AWS CLI 把 252/253 保留給自己的語法與設定問題、255 給其他所有情況，所以 ConditionalCheckFailedException、ValidationException 與節流最後都落在同一個 254。如果你的腳本需要分辨「預期中的條件失敗」與「真正的故障」，請解析錯誤名稱，而不是結束碼。另外請注意 2.36.9 會在訊息前面加上 aws: [ERROR]: ，這是舊版沒有的；一個錨定在 ^An error occurred 的正規表達式，在 CLI 升級之後就會無聲地不再比對成功。

失敗的條件式寫入照樣要付錢。條件是由服務在找到項目之後才評估的，而 AWS 明確寫著「if the expression evaluates to false, DynamoDB still consumes write capacity units from the table」（擷取於 2026-07-28）。一個包在「只建立不覆寫」put 外面的重試迴圈，每一次嘗試都會計費。給你一個量級參考：對一筆約 15 KB 的項目成功執行 put 並加上 --return-consumed-capacity TOTAL，回報的是 "CapacityUnits": 15。寫入是以 1 KB 進位，不是讀取用的那個 4 KB。

--return-values-on-condition-check-failure 有作用，但 CLI 把答案藏起來了。這個旗標能在不做第二次讀取的情況下，告訴你是_哪一筆_項目擋住了寫入。加上它，2.36.9 會印出：

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.

那筆項目自始至終都在回應裡；是預設的錯誤格式化工具拒絕把它印出來。加上 --cli-error-format json 就拿得到。（--return-values ALL_OLD 是它不帶條件的表親，而且只在成功時觸發；ReturnValues 說明了那五個選項。）

引號處理是這件事的另一半。--item 參數是一個 shell token，裡面包著 JSON，JSON 裡又包著加引號的數字（{"N": "1994"}，絕不是 1994）。任何含有單引號的東西、以及任何超過幾百位元組的項目，用 --item file://song.json 都會輕鬆得多。--cli-input-json file://request.json 更進一步，直接接下整個請求（含條件運算式），而這也是你在審查時能拿來 diff 的形式。

那些別名不是可有可無的裝飾。#cond0/#cond1 透過 --expression-attribute-names 解析成 Artist/SongTitle。把名稱直接寫在裡面一直都行得通，直到其中一個撞上保留字為止 — 那時指令會因為一個你根本沒動過的名稱而失敗。

改用視覺化操作

手打 --item 要的那種帶型別 JSON，正是大多數這類指令陣亡的地方。免費的 DynamoDB JSON 轉換器吃進普通 JSON，回傳這個旗標要的 {"S": …} / {"N": …} 形式，可以直接存成 file:// 的內容。

想對你自己的資料表新增與編輯項目 — 每個屬性一個欄位、型別選擇器、把結果複製回一段 CLI 指令 — 請下載 DynoTable。

參考資料

已於 2026-07-28 以 aws-cli/2.36.9 對照連接埠 9000 上的 DynamoDB Local（amazon/dynamodb-local）重現。結束碼、錯誤文字與容量數據皆為擷取的實際輸出。失敗寫入的容量說法是引用自 AWS 文件而非實測：在條件失敗的路徑上，DynamoDB Local 不會回傳 ConsumedCapacity。

使用 AWS CLI 的 DynamoDB PutItem

程式碼

說明

改用視覺化操作

相關指南

參考資料