Node.js (AWS SDK v3) ile DynamoDB PutItem

PutItem bütün bir öğe yazar ve aynı birincil anahtara sahip mevcut öğenin yerini alır (öğe tabanlı eylemler bunun UpdateItem'dan nasıl ayrıldığını anlatır). v3 istemcisi doğrudan DynamoDB JSON gönderir, dolayısıyla Item, düz JavaScript yerine { S: … } / { N: … } değerleri tutar.

Kod

import {DynamoDBClient, PutItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const command = new PutItemCommand({
  TableName: 'Music',
  Item: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'},
    AlbumTitle: {S: 'Danzon'},
    Year: {N: '1994'},
    Awards: {N: '0'}
  },
  ConditionExpression: 'attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)',
  ExpressionAttributeNames: {
    '#cond0': 'Artist',
    '#cond1': 'SongTitle'
  }
});

try {
  await client.send(command);
  console.log('Song written');
} catch (err) {
  if (err.name === 'ConditionalCheckFailedException') {
    console.log('A song with that key already exists — not overwritten');
  } else {
    throw err;
  }
}

Açıklama

err.name doğru denetimdir ve hatanın üzerindeki tek şey de değildir. Yukarıdaki başarısız koşulu yakalayıp nesneyi yazdırmak şunu verdi:

err.name                     ConditionalCheckFailedException
err instanceof Error         true
err.message                  The conditional request failed
err.$metadata.httpStatusCode 400

Her v3 hatası, durum kodunu, istek kimliğini ve deneme sayısını içeren $metadata'yı taşır; bir günlük satırında istediğiniz de budur. err.name modüler paketler arasında kararlıdır; instanceof ConditionalCheckFailedException de çalışır ama sınıfı bir değer içe aktarması olarak çeker, dolayısıyla paketleyiciler onu tutar.

Hata, yazmayı engelleyen öğeyi size verebilir. Komuta ReturnValuesOnConditionCheckFailure: 'ALL_OLD' ekleyin ve err.Item dolu gelsin: yukarıdaki çalıştırmada beş öznitelik, Year {"N":"1994"} olarak. Yalnızca-oluştur işleyicilerinin çoğu, orada zaten ne olduğunu öğrenmek için başarısızlıktan sonra bir GetItem yapar. O gidiş-dönüşten kaçınılabilir. (ReturnValues: 'ALL_OLD' bunun başarı yolundaki kuzenidir; ReturnValues gerisini anlatır.)

marshall() beklediğinizden daha fazla girdiyi reddeder. Bu sayfanın türlenmiş Item'ını DynamoDBDocumentClient ve düz nesnelerle değiştirmek her zamanki bir sonraki adımdır ve @aws-sdk/util-dynamodb varsayılan olarak katıdır. Gerçek üç fırlatma, birebir:

{Genre: undefined}   Pass options.removeUndefinedValues=true to remove undefined values from map/array/set.
{tags: new Set()}    Pass a non-empty set, or options.convertEmptyValues=true.
{n: 9007199254740993} Number 9007199254740992 is greater than Number.MAX_SAFE_INTEGER. Use NumberValue from @aws-sdk/lib-dynamodb.

İlki üretime ulaşandır: yok yerine undefined olan isteğe bağlı bir alan, marshal zamanında fırlatır ve DynamoDBDocumentClient.from(client, {marshallOptions}) içinde removeUndefinedValues: true standart çözümdür.

Üçüncü satırı yeniden okuyun. Değişmez 9007199254740993'tü; mesaj 9007199254740992'den söz ediyor. JavaScript, SDK değeri görmeden önce onu zaten yuvarlamıştı, dolayısıyla SDK aldığı şeyi bildiriyor. DynamoDB'nin N'yi bir dize olarak taşımasının bütün nedeni budur: 38 basamak duyarlılık tutar, bir JS number ise 15 ila 17 tutar. Gerçekte bir tanımlayıcı olan her şeyin yeri S'dir; gerçekte bir ondalık olan her şeyin yeri ise NumberValue ya da kendi biçimlendirdiğiniz bir dizedir.

ConditionExpression, hayır dediğinde bile yazma kapasitesine mal olur. AWS: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (2026-07-28 tarihinde alındı). Sıkı bir yalnızca-oluştur yeniden deneme döngüsü deneme başına faturalandırılır. Ölçek için: ~15 KB'lık bir öğenin başarılı bir put'u "CapacityUnits": 15 bildirdi; yazmalar, okumaların kullandığı 4 KB yerine 1 KB başına yukarı yuvarlanır.

Takma adlar yük taşır. #cond0/#cond1, ExpressionAttributeNames üzerinden Artist/SongTitle'a çözümlenir. Satır içi adlar, biri bir ayrılmış sözcükle çakışana kadar çalışır; sonra ifade, dokunmadığınız bir öznitelik yüzünden başarısız olur.

Görsel olarak yapın

Yukarıdaki marshalling kurallarını denetlemenin en kolay yolu iki biçimi yan yana görmektir. Ücretsiz DynamoDB JSON dönüştürücü, düz JSON'ı türlenmiş { S: … } biçimine ve geri çevirir; böylece göndermeden önce marshall()'ın ne üreteceğini doğrulayabilirsiniz.

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

İlgili kılavuzlar

DynamoDB koşul ifadeleri — attribute_not_exists, iyimser kilitleme ve dahası.
DynamoDB veri türleri — her öznitelik türünün nasıl yazıldığı.
DynamoDB ConditionalCheckFailedException — öğe zaten varken yalnızca-oluştur koşulunun ne fırlattığı.
DynamoDB ValidationException — hatalı biçimlendirilmiş bir öğe ya da ifade için genel toplayıcı.

Kaynaklar

2026-07-28 tarihinde Node v24.18.0 üzerinde @aws-sdk/client-dynamodb 3.1095.0 ve @aws-sdk/util-dynamodb 3.996.7 ile, 9000 numaralı porttaki DynamoDB Local'a (amazon/dynamodb-local) karşı yeniden üretildi. Hata dizeleri, nesne yapısı ve kapasite okuması yakalanmış çıktıdır, birebir kopyalanmıştır.