AWS CLI ile DynamoDB PutItem

aws dynamodb put-item bütün bir öğe yazar ve aynı birincil anahtara sahip mevcut her öğenin yerini alır (öğe tabanlı eylemler bunun update-item'dan nasıl ayrıldığını anlatır). CLI'ın soruna kendi katkısı kabuktur: --item, DynamoDB JSON biçimini tek bir tırnaklı argüman olarak alır ve her öznitelik değeri türlüdür.

Kod

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

Başarı durumunda komut hiçbir şey yazdırmaz ve 0 ile çıkar. Öğe zaten varsa koşul başarısız olur:

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

Açıklama

Sessizlik ve 0 çıkış kodu tek başarı sinyalidir. put-item, siz --return-values istemedikçe hiç JSON yazdırmaz; dolayısıyla onay için stdout'u grep'leyen bir betik asla tetiklenmez. $?'yı denetleyin. Yukarıdaki komutu aws-cli/2.36.9 üzerinde iki kez çalıştırmak şunu verdi:

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 bozuldu" değil, "hizmet hayır dedi" demektir. AWS CLI, 252/253'ü kendi söz dizimi ve yapılandırma sorunlarına, 255'i de geri kalan her şeye ayırır; dolayısıyla bir ConditionalCheckFailedException, bir ValidationException ve bir kısıtlama aynı 254'e düşer. Betiğinizin beklenen bir koşul başarısızlığını gerçek bir arızadan ayırması gerekiyorsa çıkış kodunu değil, hata adını ayrıştırın. Ayrıca 2.36.9'un mesajın önüne aws: [ERROR]: eklediğine dikkat edin; eski sürümler bunu yapmıyordu, dolayısıyla ^An error occurred ile başa sabitlenmiş bir regex bir CLI yükseltmesinden sonra sessizce eşleşmeyi bırakır.

Başarısız bir koşullu yazma yine de size mal olur. Koşul, hizmet tarafından öğe bulunduktan sonra değerlendirilir ve AWS açıkça şunu söyler: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (2026-07-28 tarihinde alındı). Yalnızca-oluştur nitelikli bir put'un etrafındaki yeniden deneme döngüsü her denemeyi faturalandırır. Ölçek için: ~15 KB'lık bir öğenin başarılı put'unda --return-consumed-capacity TOTAL, "CapacityUnits": 15 bildirdi. Yazmalar okumaların kullandığı 4 KB'a değil, 1 KB'a yuvarlanır.

--return-values-on-condition-check-failure çalışır, ama CLI cevabı saklar. Bu, ikinci bir okuma olmadan yazmayı hangi öğenin engellediğini söyleyen bayraktır. Ekleyin, 2.36.9 şunu yazdırır:

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.

Öğe baştan sona yanıtın içindedir; onu işlemeyi reddeden şey varsayılan hata biçimlendiricisidir. Almak için --cli-error-format json ekleyin. (--return-values ALL_OLD bunun koşulsuz kuzenidir ve yalnızca başarıda tetiklenir; ReturnValues beş seçeneğin tamamını anlatır.)

İşin diğer yarısı tırnaklamadır. --item argümanı, tırnaklı sayılar ({"N": "1994"}, asla 1994) içeren JSON içeren tek bir kabuk belirtecidir. İçinde kesme işareti olan her şey ve birkaç yüz baytı geçen her öğe --item file://song.json olarak daha kolaydır. --cli-input-json file://request.json daha ileri gider ve koşul ifadesi dahil isteğin tamamını alır — ki bu aynı zamanda incelemede diff'leyebileceğiniz biçimdir.

Takma adlar isteğe bağlı bir süs değildir. #cond0/#cond1, --expression-attribute-names üzerinden Artist/SongTitle'a çözümlenir. Adları satır içi yazmak, biri bir ayrılmış sözcükle çakışana kadar işe yarar; o noktada komut, sizin değiştirmediğiniz bir ad yüzünden başarısız olur.

Görsel olarak yapın

--item için elle türlü JSON yazmak, bu komutların çoğunun öldüğü yerdir. Ücretsiz DynamoDB JSON dönüştürücüsü sıradan JSON alır ve bayrağın istediği {"S": …} / {"N": …} biçimini file:// yükü olarak kaydetmeye hazır biçimde geri verir.

Kendi tablolarınıza karşı öğe eklemek ve düzenlemek — öznitelik başına bir form, tür seçiciler, sonucu bir CLI komutu olarak geri kopyalama — için DynoTable'ı indirin.

İlgili kılavuzlar

DynamoDB koşul ifadeleri — attribute_not_exists, iyimser kilitleme ve dahası.
DynamoDB veri türleri — her öznitelik türü DynamoDB JSON'unda nasıl yazılır.
DynamoDB ConditionalCheckFailedException — öğe zaten varken yalnızca-oluştur koşulunun fırlattığı şey.
DynamoDB ValidationException — bozuk bir öğe ya da ifade için genel karşılık.

Kaynaklar

2026-07-28 tarihinde aws-cli/2.36.9 ile, 9000 numaralı porttaki DynamoDB Local'a (amazon/dynamodb-local) karşı yeniden üretildi. Çıkış kodları, hata metni ve kapasite okuması birebir alınmıştır. Başarısız yazmanın kapasite iddiası ölçülmedi, AWS belgelerinden alıntılandı: DynamoDB Local, koşul başarısızlığı yolunda hiç ConsumedCapacity döndürmez.