在 Java（AWS SDK v2）中使用 DynamoDB PutItem

PutItem 寫入整個項目，建立它、或取代任何具有相同 primary key 的既有項目。在 AWS SDK for Java 2.x 中，你建構一個 PutItemRequest，其 item map 以帶型別的 AttributeValue 持有每個屬性（字串用 .s(...)，數字用 .n(...)）。

Code

import java.util.HashMap;
import java.util.Map;

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;

public class PutItemExample {
    public static void main(String[] args) {
        try (DynamoDbClient ddb = DynamoDbClient.builder()
                .region(Region.US_EAST_1)
                .build()) {

            Map<String, AttributeValue> item = new HashMap<>();
            item.put("Artist", AttributeValue.builder().s("Arturo Sandoval").build());
            item.put("SongTitle", AttributeValue.builder().s("Cubano Chant").build());
            item.put("AlbumTitle", AttributeValue.builder().s("Danzon").build());
            item.put("Year", AttributeValue.builder().n("1994").build());
            item.put("Awards", AttributeValue.builder().n("0").build());

            Map<String, String> names = new HashMap<>();
            names.put("#cond0", "Artist");
            names.put("#cond1", "SongTitle");

            PutItemRequest request = PutItemRequest.builder()
                    .tableName("Music")
                    .item(item)
                    .conditionExpression("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)")
                    .expressionAttributeNames(names)
                    .build();

            try {
                ddb.putItem(request);
                System.out.println("Song written");
            } catch (ConditionalCheckFailedException e) {
                System.out.println("A song with that key already exists — not overwritten");
            }
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

說明

item — 必須包含表格的完整 primary key，以及任何其他屬性。數字在 N 型別下以字串表示（AttributeValue.builder().n("1994")）。
Put 會取代 — 沒有條件時，PutItem 會靜默覆寫任何具有相同 key 的既有項目。若只想改動少數屬性而不清掉其餘部分，請用 UpdateItem。
conditionExpression — 對 key 屬性使用 attribute_not_exists(...)，讓寫入成為一個只建立的插入；若項目已存在，寫入會以 ConditionalCheckFailedException 失敗。這是 DynamoDB 的樂觀鎖基本手法。#cond0/#cond1 別名透過 expressionAttributeNames 解析為 Artist/SongTitle（保留字安全）。
ConditionalCheckFailedException 繼承 DynamoDbException — 先捕捉它（上方的內層 try），讓失敗的條件與其他服務錯誤分開處理。
若要取回被覆寫的項目，請加上 .returnValues(ReturnValue.ALL_OLD)。
偏好單純的 Java 物件？DynamoDB Enhanced Client（software.amazon.awssdk.enhanced.dynamodb）會寫入帶註解的 bean 類別，而非 AttributeValue map。

改用視覺化操作

手寫條件式 put？DynamoDB Expression Builder 會組裝 ConditionExpression 並複製程式碼。

想在 GUI 中新增與編輯項目 — 每個屬性一個欄位、型別選擇器，以及複製為程式碼 — 下載 DynoTable。

References

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。

在 Java（AWS SDK v2）中使用 DynamoDB PutItem

Code

說明

改用視覺化操作

相關範例

References