DynamoDB PutItem en Java (AWS SDK v2)

PutItem écrit un élément entier, en le créant ou en remplaçant tout élément existant ayant la même clé primaire. Dans l'AWS SDK for Java 2.x tu construis un PutItemRequest dont la carte item contient chaque attribut comme AttributeValue typé (.s(...) pour les chaînes, .n(...) pour les nombres).

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());
        }
    }
}

Explication

item — doit contenir la clé primaire complète de la table, plus tout autre attribut. Les nombres sont des chaînes sous le type N (AttributeValue.builder().n("1994")).
L'insertion remplace — sans condition, PutItem écrase silencieusement un élément existant ayant la même clé. Utilise UpdateItem pour modifier quelques attributs sans écraser le reste.
conditionExpression — attribute_not_exists(...) sur les attributs de clé fait de l'écriture une insertion de création uniquement ; l'écriture échoue avec ConditionalCheckFailedException si l'élément existe déjà. C'est la primitive de verrouillage optimiste de DynamoDB. Les alias #cond0/#cond1 se résolvent en Artist/SongTitle via expressionAttributeNames (à l'abri des mots réservés).
ConditionalCheckFailedException étend DynamoDbException — capte-la en premier (le try interne ci-dessus) afin que la condition échouée soit gérée séparément des autres erreurs de service.
Pour récupérer l'élément écrasé, ajoute .returnValues(ReturnValue.ALL_OLD).
Tu préfères des objets Java simples ? Le DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) écrit des classes bean annotées au lieu de cartes AttributeValue.

À faire visuellement

Tu écris une insertion conditionnelle à la main ? Le DynamoDB Expression Builder assemble le ConditionExpression et copie le code.

Pour ajouter et éditer des éléments dans une interface graphique — un formulaire par attribut, des sélecteurs de type, et copie en tant que code — télécharge DynoTable.

Exemples liés

DynamoDB PutItem en Go — la même écriture conditionnelle avec l'AWS SDK for Go v2.
DynamoDB UpdateItem en Java — modifier des attributs spécifiques au lieu de remplacer l'élément.
Expressions de condition DynamoDB — attribute_not_exists, verrouillage optimiste, et plus encore.
DynamoDB ConditionalCheckFailedException — ce que lève la condition de création uniquement quand l'élément existe déjà.
DynamoDB ValidationException — le fourre-tout pour un élément ou une expression malformés.

References

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.