Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Utilisation des éléments : Java Vous pouvez utiliser l'API AWS SDK pour Java Document pour effectuer des opérations classiques de création, de lecture, de mise à jour et de suppression (CRUD) sur les éléments Amazon DynamoDB d'une table. **Note** Le kit SDK pour Java fournit également un modèle de persistance des objets qui vous permet de mapper vos classes côté client à des tables DynamoDB. Cette approche peut réduire la quantité de code que vous avez à écrire. Pour de plus amples informations, veuillez consulter [Java 1.x : Dynamo DBMapper](DynamoDBMapper.md). Cette section comporte les exemples Java pour exécuter plusieurs actions d’élément d’API de document Java et plusieurs exemples opérationnels. **Topics** + [ ## Insertion d’un élément ](#PutDocumentAPIJava) + [ ## Obtention d’un élément ](#JavaDocumentAPIGetItem) + [ ## Écriture par lots : insertion et suppression de plusieurs éléments ](#BatchWriteDocumentAPIJava) + [ ## Obtention par lots : obtention de plusieurs éléments ](#JavaDocumentAPIBatchGetItem) + [ ## Mise à jour d’un élément ](#JavaDocumentAPIItemUpdate) + [ ## Suppression d’un élément ](#DeleteMidLevelJava) + [ # Exemple : opérations CRUD à l'aide de l'API du AWS SDK pour Java document ](JavaDocumentAPICRUDExample.md) + [ # Exemple : opérations par lots à l'aide de l'API AWS SDK pour Java du document ](batch-operation-document-api-java.md) + [ # Exemple : gestion des attributs de type binaire à l'aide de l'API du AWS SDK pour Java document ](JavaDocumentAPIBinaryTypeExample.md) ## Insertion d’un élément La méthode `putItem` stocke un élément dans une table. Si l’élément existe, il remplace la totalité de l’élément. Au lieu de remplacer l’élément entier, vous pouvez mettre à jour uniquement des attributs spécifiques à l’aide de la méthode `updateItem`. Pour de plus amples informations, veuillez consulter [Mise à jour d’un élément](#JavaDocumentAPIItemUpdate). ------ #### [ Java v2 ] ``` 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.DynamoDbException; import software.amazon.awssdk.services.dynamodb.model.PutItemRequest; import software.amazon.awssdk.services.dynamodb.model.PutItemResponse; import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException; import java.util.HashMap; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html * * To place items into an Amazon DynamoDB table using the AWS SDK for Java V2, * its better practice to use the * Enhanced Client. See the EnhancedPutItem example. */ public class PutItem { public static void main(String[] args) { final String usage = """ Usage: Where: tableName - The Amazon DynamoDB table in which an item is placed (for example, Music3). key - The key used in the Amazon DynamoDB table (for example, Artist). keyval - The key value that represents the item to get (for example, Famous Band). albumTitle - The Album title (for example, AlbumTitle). AlbumTitleValue - The name of the album (for example, Songs About Life ). Awards - The awards column (for example, Awards). AwardVal - The value of the awards (for example, 10). SongTitle - The song title (for example, SongTitle). SongTitleVal - The value of the song title (for example, Happy Day). **Warning** This program will place an item that you specify into a table! """; if (args.length != 9) { System.out.println(usage); System.exit(1); } String tableName = args[0]; String key = args[1]; String keyVal = args[2]; String albumTitle = args[3]; String albumTitleValue = args[4]; String awards = args[5]; String awardVal = args[6]; String songTitle = args[7]; String songTitleVal = args[8]; Region region = Region.US_EAST_1; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .build(); putItemInTable(ddb, tableName, key, keyVal, albumTitle, albumTitleValue, awards, awardVal, songTitle, songTitleVal); System.out.println("Done!"); ddb.close(); } public static void putItemInTable(DynamoDbClient ddb, String tableName, String key, String keyVal, String albumTitle, String albumTitleValue, String awards, String awardVal, String songTitle, String songTitleVal) { HashMap itemValues = new HashMap<>(); itemValues.put(key, AttributeValue.builder().s(keyVal).build()); itemValues.put(songTitle, AttributeValue.builder().s(songTitleVal).build()); itemValues.put(albumTitle, AttributeValue.builder().s(albumTitleValue).build()); itemValues.put(awards, AttributeValue.builder().s(awardVal).build()); PutItemRequest request = PutItemRequest.builder() .tableName(tableName) .item(itemValues) .build(); try { PutItemResponse response = ddb.putItem(request); System.out.println(tableName + " was successfully updated. The request id is " + response.responseMetadata().requestId()); } catch (ResourceNotFoundException e) { System.err.format("Error: The Amazon DynamoDB table \"%s\" can't be found.\n", tableName); System.err.println("Be sure that it exists and that you've typed its name correctly!"); System.exit(1); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } } } ``` ------ #### [ Java v1 ] Procédez comme suit : 1. Créez une instance de la classe `DynamoDB`. 1. Créez une instance de la classe `Table` pour représenter la table que vous souhaitez utiliser. 1. Création d’une instance de la classe `Item` pour représenter le nouvel élément. Vous devez spécifier la clé primaire du nouvel élément et ses attributs. 1. Appelez la méthode `putItem` de l’objet `Table` à l’aide de l’objet `Item` que vous avez créé à l’étape précédente. L’exemple de code Java suivant présente les tâches précédentes. Le code écrit un nouvel élément dans la table `ProductCatalog`. **Example** ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); // Build a list of related items List relatedItems = new ArrayList(); relatedItems.add(341); relatedItems.add(472); relatedItems.add(649); //Build a map of product pictures Map pictures = new HashMap(); pictures.put("FrontView", "http://example.com/products/123_front.jpg"); pictures.put("RearView", "http://example.com/products/123_rear.jpg"); pictures.put("SideView", "http://example.com/products/123_left_side.jpg"); //Build a map of product reviews Map> reviews = new HashMap>(); List fiveStarReviews = new ArrayList(); fiveStarReviews.add("Excellent! Can't recommend it highly enough! Buy it!"); fiveStarReviews.add("Do yourself a favor and buy this"); reviews.put("FiveStar", fiveStarReviews); List oneStarReviews = new ArrayList(); oneStarReviews.add("Terrible product! Do not buy this."); reviews.put("OneStar", oneStarReviews); // Build the item Item item = new Item() .withPrimaryKey("Id", 123) .withString("Title", "Bicycle 123") .withString("Description", "123 description") .withString("BicycleType", "Hybrid") .withString("Brand", "Brand-Company C") .withNumber("Price", 500) .withStringSet("Color", new HashSet(Arrays.asList("Red", "Black"))) .withString("ProductCategory", "Bicycle") .withBoolean("InStock", true) .withNull("QuantityOnHand") .withList("RelatedItems", relatedItems) .withMap("Pictures", pictures) .withMap("Reviews", reviews); // Write the item to the table PutItemOutcome outcome = table.putItem(item); ``` Dans l’exemple précédent, l’élément comporte des attributs scalaires (`String`, `Number`, `Boolean` et `Null`), des ensembles (`String Set`) et des types de documents (`List`, `Map`). ------ ### Spécification de paramètres facultatifs Outre les paramètres obligatoires, vous pouvez également spécifier des paramètres facultatifs de la méthode `putItem`. Par exemple, l’extrait de code Java suivant spécifie une condition pour le chargement de l’élément à l’aide d’un paramètre facultatif. Si la condition que vous spécifiez n'est pas remplie, AWS SDK pour Java renvoie un`ConditionalCheckFailedException`. L’extrait de code spécifie les paramètres facultatifs suivants dans la méthode `putItem` : + Une `ConditionExpression` qui définit les conditions de la demande. Le code définit la condition selon laquelle l’élément existant ayant la même clé primaire est remplacé seulement s’il comporte un attribut ISBN égal à une valeur spécifique. + Un mappage pour `ExpressionAttributeValues` utilisé dans la condition. Dans ce cas, une seule substitution est nécessaire : l’espace réservé `:val` dans l’expression de condition est remplacé lors de l’exécution par la valeur ISBN réelle à vérifier. L’exemple suivant ajoute un nouvel élément livre à l’aide de ces paramètres facultatifs. **Example** ``` Item item = new Item() .withPrimaryKey("Id", 104) .withString("Title", "Book 104 Title") .withString("ISBN", "444-4444444444") .withNumber("Price", 20) .withStringSet("Authors", new HashSet(Arrays.asList("Author1", "Author2"))); Map expressionAttributeValues = new HashMap(); expressionAttributeValues.put(":val", "444-4444444444"); PutItemOutcome outcome = table.putItem( item, "ISBN = :val", // ConditionExpression parameter null, // ExpressionAttributeNames parameter - we're not using it for this example expressionAttributeValues); ``` ### PutItem et documents JSON Vous pouvez stocker un document JSON comme un attribut dans une table DynamoDB. Pour ce faire, utilisez la méthode `withJSON` de `Item`. Cette méthode analyse le document JSON et mappe chaque élément à un type de données DynamoDB natif. Supposons que vous souhaitiez stocker le document JSON suivant, comportant des fournisseurs qui peuvent exécuter des commandes pour un produit spécifique. **Example** ``` { "V01": { "Name": "Acme Books", "Offices": [ "Seattle" ] }, "V02": { "Name": "New Publishers, Inc.", "Offices": ["London", "New York" ] }, "V03": { "Name": "Better Buy Books", "Offices": [ "Tokyo", "Los Angeles", "Sydney" ] } } ``` La méthode `withJSON` vous permet de stocker cela dans la table `ProductCatalog`, dans un attribut `Map` nommé `VendorInfo`. L’extrait de code Java suivant montre comment procéder. ``` // Convert the document into a String. Must escape all double-quotes. String vendorDocument = "{" + " \"V01\": {" + " \"Name\": \"Acme Books\"," + " \"Offices\": [ \"Seattle\" ]" + " }," + " \"V02\": {" + " \"Name\": \"New Publishers, Inc.\"," + " \"Offices\": [ \"London\", \"New York\"" + "]" + "}," + " \"V03\": {" + " \"Name\": \"Better Buy Books\"," + "\"Offices\": [ \"Tokyo\", \"Los Angeles\", \"Sydney\"" + " ]" + " }" + " }"; Item item = new Item() .withPrimaryKey("Id", 210) .withString("Title", "Book 210 Title") .withString("ISBN", "210-2102102102") .withNumber("Price", 30) .withJSON("VendorInfo", vendorDocument); PutItemOutcome outcome = table.putItem(item); ``` ## Obtention d’un élément Récupérez un élément unique à l’aide de la méthode `getItem` d’un objet `Table`. Procédez comme suit : 1. Créez une instance de la classe `DynamoDB`. 1. Créez une instance de la classe `Table` pour représenter la table que vous souhaitez utiliser. 1. Appelez la méthode `getItem` de l’instance `Table`. Vous devez spécifier la clé primaire de l’élément que vous souhaitez récupérer. L’exemple de code Java suivant illustre les tâches précédentes. Le code obtient l’élément qui possède la clé de partition spécifiée. ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); Item item = table.getItem("Id", 210); ``` ### Spécification de paramètres facultatifs Outre les paramètres obligatoires, vous pouvez également spécifier des paramètres facultatifs de la méthode `getItem`. Par exemple, l’extrait de code Java suivant récupère uniquement une liste précise d’attributs et spécifie des lectures fortement cohérentes à l’aide d’une méthode facultative. (Pour en savoir plus sur la cohérence en lecture, consultez [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md).) Une `ProjectionExpression` vous permet de récupérer uniquement certains attributs ou éléments, plutôt qu’un élément entier. Une `ProjectionExpression` peut spécifier des attributs de niveau supérieur ou imbriqués à l’aide de chemins d’accès au document. Pour de plus amples informations, veuillez consulter [Utilisation d’expressions de projection dans DynamoDB](Expressions.ProjectionExpressions.md). Les paramètres de la méthode `getItem` ne vous permettent pas de spécifier une cohérence en lecture. Cependant, vous pouvez créer une `GetItemSpec`, qui fournit un accès complet à l’ensemble des entrées de l’opération `GetItem` de bas niveau. L’exemple de code ci-dessous crée une `GetItemSpec` et utilise cette spécification comme entrée de la méthode `getItem`. **Example** ``` GetItemSpec spec = new GetItemSpec() .withPrimaryKey("Id", 206) .withProjectionExpression("Id, Title, RelatedItems[0], Reviews.FiveStar") .withConsistentRead(true); Item item = table.getItem(spec); System.out.println(item.toJSONPretty()); ``` Imprimez un `Item` dans un format contrôlable de visu à l’aide de la méthode `toJSONPretty`. La sortie de l’exemple précédent se présente comme suit. ``` { "RelatedItems" : [ 341 ], "Reviews" : { "FiveStar" : [ "Excellent! Can't recommend it highly enough! Buy it!", "Do yourself a favor and buy this" ] }, "Id" : 123, "Title" : "20-Bicycle 123" } ``` ### GetItem et documents JSON Dans la section [PutItem et documents JSON](#PutItemJavaDocumentAPI.JSON),vous stockez un document JSON dans un attribut `Map` nommé `VendorInfo`. La méthode `getItem` vous permet d’extraire la totalité du document au format JSON. Vous pouvez également extraire uniquement certains éléments du document à l’aide de la notation du chemin d’accès au document. L’extrait de code Java suivant illustre ces techniques. ``` GetItemSpec spec = new GetItemSpec() .withPrimaryKey("Id", 210); System.out.println("All vendor info:"); spec.withProjectionExpression("VendorInfo"); System.out.println(table.getItem(spec).toJSON()); System.out.println("A single vendor:"); spec.withProjectionExpression("VendorInfo.V03"); System.out.println(table.getItem(spec).toJSON()); System.out.println("First office location for this vendor:"); spec.withProjectionExpression("VendorInfo.V03.Offices[0]"); System.out.println(table.getItem(spec).toJSON()); ``` La sortie de l’exemple précédent se présente comme suit. ``` All vendor info: {"VendorInfo":{"V03":{"Name":"Better Buy Books","Offices":["Tokyo","Los Angeles","Sydney"]},"V02":{"Name":"New Publishers, Inc.","Offices":["London","New York"]},"V01":{"Name":"Acme Books","Offices":["Seattle"]}}} A single vendor: {"VendorInfo":{"V03":{"Name":"Better Buy Books","Offices":["Tokyo","Los Angeles","Sydney"]}}} First office location for a single vendor: {"VendorInfo":{"V03":{"Offices":["Tokyo"]}}} ``` **Note** La méthode `toJSON` vous permet de convertir tout élément (ou ses attributs) en une chaîne au format JSON. L’extrait de code suivant récupère plusieurs attributs de niveau supérieur et imbriqués et imprime les résultats au format JSON. ``` GetItemSpec spec = new GetItemSpec() .withPrimaryKey("Id", 210) .withProjectionExpression("VendorInfo.V01, Title, Price"); Item item = table.getItem(spec); System.out.println(item.toJSON()); ``` Le résultat se présente comme suit. ``` {"VendorInfo":{"V01":{"Name":"Acme Books","Offices":["Seattle"]}},"Price":30,"Title":"Book 210 Title"} ``` ## Écriture par lots : insertion et suppression de plusieurs éléments L’*écriture par lots* désigne l’insertion et la suppression de plusieurs éléments dans un lot. La méthode `batchWriteItem` vous permet d’insérer et de supprimer plusieurs éléments d’une ou de plusieurs tables en un seul appel. Voici les étapes à suivre pour placer ou supprimer plusieurs éléments à l'aide de l'API AWS SDK pour Java Document. 1. Créez une instance de la classe `DynamoDB`. 1. Créez une instance de la classe `TableWriteItems` qui décrit toutes les opérations d’insertion et de suppression pour une table. Si vous souhaitez écrire sur plusieurs tables en une opération unique d’écriture par lots, vous devez créer une instance `TableWriteItems` par table. 1. Appelez la méthode `batchWriteItem` en fournissant les objets `TableWriteItems` que vous avez créés à l’étape précédente. 1. Traitez la réponse. Vous devez vérifier si des éléments de requêtes non traités ont été renvoyés dans la réponse. Cela peut se produire si vous atteignez le quota de débit alloué ou en cas d’autre erreur temporaire. En outre, DynamoDB limite la taille de demande et le nombre d’opérations que vous pouvez spécifier dans une demande. Si vous dépassez ces limites, DynamoDB rejette la demande. Pour de plus amples informations, veuillez consulter [Quotas dans Amazon DynamoDB](ServiceQuotas.md). L’exemple de code Java suivant illustre les tâches précédentes. L’exemple effectue une opération `batchWriteItem` sur deux tables : `Forum` et `Thread`. Les objets `TableWriteItems` correspondants permettent de définir les actions suivantes : + Insérer un élément dans la table `Forum` + Insérer et supprimer un élément de la table `Thread` Le code appelle ensuite `batchWriteItem` pour effectuer l’opération. ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); TableWriteItems forumTableWriteItems = new TableWriteItems("Forum") .withItemsToPut( new Item() .withPrimaryKey("Name", "Amazon RDS") .withNumber("Threads", 0)); TableWriteItems threadTableWriteItems = new TableWriteItems("Thread") .withItemsToPut( new Item() .withPrimaryKey("ForumName","Amazon RDS","Subject","Amazon RDS Thread 1") .withHashAndRangeKeysToDelete("ForumName","Some partition key value", "Amazon S3", "Some sort key value"); BatchWriteItemOutcome outcome = dynamoDB.batchWriteItem(forumTableWriteItems, threadTableWriteItems); // Code for checking unprocessed items is omitted in this example ``` Pour obtenir un exemple pratique, consultez [Exemple : opération d'écriture par lots à l'aide de l'API du AWS SDK pour Java document](batch-operation-document-api-java.md#JavaDocumentAPIBatchWrite). ## Obtention par lots : obtention de plusieurs éléments La méthode `batchGetItem` vous permet de récupérer plusieurs éléments d’une ou de plusieurs tables. Pour récupérer un seul élément, vous pouvez utiliser la méthode `getItem`. Procédez comme suit : 1. Créez une instance de la classe `DynamoDB`. 1. Créez une instance de la classe `TableKeysAndAttributes` qui décrit une liste de valeurs de clé primaire à récupérer dans une table. Si vous souhaitez lire depuis plusieurs tables dans une opération unique d’obtention par lots, vous devez créer une instance `TableKeysAndAttributes` par table. 1. Appelez la méthode `batchGetItem` en fournissant les objets `TableKeysAndAttributes` que vous avez créés à l’étape précédente. L’exemple de code Java suivant illustre les tâches précédentes. L’exemple récupère deux éléments dans la table `Forum` et trois éléments dans la table `Thread`. ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); TableKeysAndAttributes forumTableKeysAndAttributes = new TableKeysAndAttributes(forumTableName); forumTableKeysAndAttributes.addHashOnlyPrimaryKeys("Name", "Amazon S3", "Amazon DynamoDB"); TableKeysAndAttributes threadTableKeysAndAttributes = new TableKeysAndAttributes(threadTableName); threadTableKeysAndAttributes.addHashAndRangePrimaryKeys("ForumName", "Subject", "Amazon DynamoDB","DynamoDB Thread 1", "Amazon DynamoDB","DynamoDB Thread 2", "Amazon S3","S3 Thread 1"); BatchGetItemOutcome outcome = dynamoDB.batchGetItem( forumTableKeysAndAttributes, threadTableKeysAndAttributes); for (String tableName : outcome.getTableItems().keySet()) { System.out.println("Items in table " + tableName); List items = outcome.getTableItems().get(tableName); for (Item item : items) { System.out.println(item); } } ``` ### Spécification de paramètres facultatifs Outre les paramètres obligatoires, vous pouvez également spécifier des paramètres facultatifs lorsque vous utilisez `batchGetItem`. Par exemple, vous pouvez fournir une `ProjectionExpression` avec chaque `TableKeysAndAttributes` que vous définissez. Cela vous permet de spécifier les attributs que vous souhaitez récupérer à partir de la table. L’exemple de code suivant extrait trois éléments de la table `Forum`. Le paramètre `withProjectionExpression` spécifie que seul l’attribut `Threads` doit être récupéré. **Example** ``` TableKeysAndAttributes forumTableKeysAndAttributes = new TableKeysAndAttributes("Forum") .withProjectionExpression("Threads"); forumTableKeysAndAttributes.addHashOnlyPrimaryKeys("Name", "Amazon S3", "Amazon DynamoDB"); BatchGetItemOutcome outcome = dynamoDB.batchGetItem(forumTableKeysAndAttributes); ``` ## Mise à jour d’un élément La méthode `updateItem` d’un objet `Table` peut mettre à jour les valeurs d’attribut existantes, ajouter de nouveaux attributs ou supprimer des attributs d’un élément existant. La méthode `updateItem` se comporte comme suit : + Si un élément n’existe pas (aucun élément dans la table avec la clé primaire spécifiée), `updateItem` ajoute un nouvel élément à la table + Si un élément existe, `updateItem` effectue la mise à jour comme indiqué par le paramètre `UpdateExpression`. **Note** Il est également possible de « mettre à jour » un élément à l’aide de `putItem`. Par exemple, si vous appelez `putItem` pour ajouter un élément à la table, mais qu’il y a déjà un élément avec la clé primaire spécifiée, `putItem` remplace l’élément entier. S’il y a des attributs dans l’élément existant non spécifiés dans l’entrée, `putItem` supprime ces attributs de l’élément. En général, nous vous recommandons d’utiliser `updateItem` chaque fois que vous souhaitez modifier des attributs d’élément. La méthode `updateItem` modifie uniquement les attributs d’élément que vous spécifiez dans l’entrée et les autres attributs de l’élément demeurent inchangés. Procédez comme suit : 1. Créez une instance de la classe `Table` pour représenter la table que vous souhaitez utiliser. 1. Appelez la méthode `updateTable` de l’instance `Table`. Vous devez spécifier la clé primaire de l’élément que vous souhaitez récupérer, avec une `UpdateExpression` qui décrit les attributs à modifier et comment les modifier. L’exemple de code Java suivant présente les tâches précédentes. Le code met à jour un élément livre de la table `ProductCatalog`. Il ajoute un nouvel auteur à l’ensemble `Authors` et supprime l’attribut `ISBN` existant. Il permet également de réduire le prix d’une unité. Un mappage `ExpressionAttributeValues` est utilisé dans l’`UpdateExpression`. Les espaces réservés `:val1` et `:val2` sont remplacés lors de l’exécution par les valeurs réelles pour `Authors` et `Price`. ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); Map expressionAttributeNames = new HashMap(); expressionAttributeNames.put("#A", "Authors"); expressionAttributeNames.put("#P", "Price"); expressionAttributeNames.put("#I", "ISBN"); Map expressionAttributeValues = new HashMap(); expressionAttributeValues.put(":val1", new HashSet(Arrays.asList("Author YY","Author ZZ"))); expressionAttributeValues.put(":val2", 1); //Price UpdateItemOutcome outcome = table.updateItem( "Id", // key attribute name 101, // key attribute value "add #A :val1 set #P = #P - :val2 remove #I", // UpdateExpression expressionAttributeNames, expressionAttributeValues); ``` ### Spécification de paramètres facultatifs Outre les paramètres obligatoires, vous pouvez également spécifier des paramètres facultatifs pour la méthode `updateItem`, y compris une condition à remplir afin que la mise à jour puisse se produire. Si la condition que vous spécifiez n'est pas remplie, AWS SDK pour Java renvoie un`ConditionalCheckFailedException`. Par exemple, l’extrait de code Java suivant redéfinit de façon conditionnelle le prix d’un élément livre sur la valeur 25. Il spécifie une `ConditionExpression` indiquant que le prix doit être mis à jour seulement s’il est de 20. **Example** ``` Table table = dynamoDB.getTable("ProductCatalog"); Map expressionAttributeNames = new HashMap(); expressionAttributeNames.put("#P", "Price"); Map expressionAttributeValues = new HashMap(); expressionAttributeValues.put(":val1", 25); // update Price to 25... expressionAttributeValues.put(":val2", 20); //...but only if existing Price is 20 UpdateItemOutcome outcome = table.updateItem( new PrimaryKey("Id",101), "set #P = :val1", // UpdateExpression "#P = :val2", // ConditionExpression expressionAttributeNames, expressionAttributeValues); ``` ### Compteurs atomiques `updateItem` vous permet d’implémenter un compteur atomique, où vous incrémentez ou décrémentez la valeur d’un attribut existant sans interférer avec d’autres demandes d’écriture. Pour incrémenter un compteur atomique, ajoutez une valeur numérique à un attribut existant de type `Number` à l’aide d’une `UpdateExpression` avec une action `set`. L’extrait de code suivant illustre cette action, en incrémentant l’attribut `Quantity` d’une unité. Il montre également comment utiliser le paramètre `ExpressionAttributeNames` dans une `UpdateExpression`. ``` Table table = dynamoDB.getTable("ProductCatalog"); Map expressionAttributeNames = new HashMap(); expressionAttributeNames.put("#p", "PageCount"); Map expressionAttributeValues = new HashMap(); expressionAttributeValues.put(":val", 1); UpdateItemOutcome outcome = table.updateItem( "Id", 121, "set #p = #p + :val", expressionAttributeNames, expressionAttributeValues); ``` ## Suppression d’un élément La méthode `deleteItem` supprime un élément d’une table. Vous devez fournir la clé primaire de l’élément que vous souhaitez supprimer. Procédez comme suit : 1. Créez une instance du client `DynamoDB`. 1. Appelez la méthode `deleteItem` en fournissant la clé de l’élément que vous souhaitez supprimer. L’extrait de code Java suivant illustre ces tâches. **Example** ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); DeleteItemOutcome outcome = table.deleteItem("Id", 101); ``` ### Spécification de paramètres facultatifs Vous pouvez spécifier des paramètres facultatifs pour `deleteItem`. Par exemple, l’extrait de code Java suivant comprend une `ConditionExpression`, indiquant qu’un élément livre dans `ProductCatalog` peut être supprimé seulement si le livre n’est plus en publication. (L’attribut `InPublication` est false.) **Example** ``` Map expressionAttributeValues = new HashMap(); expressionAttributeValues.put(":val", false); DeleteItemOutcome outcome = table.deleteItem("Id",103, "InPublication = :val", null, // ExpressionAttributeNames - not used in this example expressionAttributeValues); ``` # Exemple : opérations CRUD à l'aide de l'API du AWS SDK pour Java document L’exemple de code suivant illustre des opérations CRUD sur un élément Amazon DynamoDB. L’exemple crée un élément, le récupère, exécute plusieurs mises à jour et supprime finalement l’élément. **Note** Le kit SDK pour Java fournit également un modèle de persistance des objets qui vous permet de mapper vos classes côté client à des tables DynamoDB. Cette approche peut réduire la quantité de code que vous avez à écrire. Pour de plus amples informations, veuillez consulter [Java 1.x : Dynamo DBMapper](DynamoDBMapper.md). **Note** Cet exemple de code part du principe que vous avez déjà chargé des données dans DynamoDB pour votre compte en suivant les instructions de la section [Création de tables et chargement de données pour des exemples de code dans DynamoDB](SampleData.md). Pour step-by-step obtenir des instructions sur l'exécution de l'exemple suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md). ``` package com.amazonaws.codesamples.document; import java.io.IOException; import java.util.Arrays; import java.util.HashMap; import java.util.HashSet; import java.util.Map; import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; import com.amazonaws.services.dynamodbv2.document.DeleteItemOutcome; import com.amazonaws.services.dynamodbv2.document.DynamoDB; import com.amazonaws.services.dynamodbv2.document.Item; import com.amazonaws.services.dynamodbv2.document.Table; import com.amazonaws.services.dynamodbv2.document.UpdateItemOutcome; import com.amazonaws.services.dynamodbv2.document.spec.DeleteItemSpec; import com.amazonaws.services.dynamodbv2.document.spec.UpdateItemSpec; import com.amazonaws.services.dynamodbv2.document.utils.NameMap; import com.amazonaws.services.dynamodbv2.document.utils.ValueMap; import com.amazonaws.services.dynamodbv2.model.ReturnValue; public class DocumentAPIItemCRUDExample { static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); static DynamoDB dynamoDB = new DynamoDB(client); static String tableName = "ProductCatalog"; public static void main(String[] args) throws IOException { createItems(); retrieveItem(); // Perform various updates. updateMultipleAttributes(); updateAddNewAttribute(); updateExistingAttributeConditionally(); // Delete the item. deleteItem(); } private static void createItems() { Table table = dynamoDB.getTable(tableName); try { Item item = new Item().withPrimaryKey("Id", 120).withString("Title", "Book 120 Title") .withString("ISBN", "120-1111111111") .withStringSet("Authors", new HashSet(Arrays.asList("Author12", "Author22"))) .withNumber("Price", 20).withString("Dimensions", "8.5x11.0x.75").withNumber("PageCount", 500) .withBoolean("InPublication", false).withString("ProductCategory", "Book"); table.putItem(item); item = new Item().withPrimaryKey("Id", 121).withString("Title", "Book 121 Title") .withString("ISBN", "121-1111111111") .withStringSet("Authors", new HashSet(Arrays.asList("Author21", "Author 22"))) .withNumber("Price", 20).withString("Dimensions", "8.5x11.0x.75").withNumber("PageCount", 500) .withBoolean("InPublication", true).withString("ProductCategory", "Book"); table.putItem(item); } catch (Exception e) { System.err.println("Create items failed."); System.err.println(e.getMessage()); } } private static void retrieveItem() { Table table = dynamoDB.getTable(tableName); try { Item item = table.getItem("Id", 120, "Id, ISBN, Title, Authors", null); System.out.println("Printing item after retrieving it...."); System.out.println(item.toJSONPretty()); } catch (Exception e) { System.err.println("GetItem failed."); System.err.println(e.getMessage()); } } private static void updateAddNewAttribute() { Table table = dynamoDB.getTable(tableName); try { UpdateItemSpec updateItemSpec = new UpdateItemSpec().withPrimaryKey("Id", 121) .withUpdateExpression("set #na = :val1").withNameMap(new NameMap().with("#na", "NewAttribute")) .withValueMap(new ValueMap().withString(":val1", "Some value")) .withReturnValues(ReturnValue.ALL_NEW); UpdateItemOutcome outcome = table.updateItem(updateItemSpec); // Check the response. System.out.println("Printing item after adding new attribute..."); System.out.println(outcome.getItem().toJSONPretty()); } catch (Exception e) { System.err.println("Failed to add new attribute in " + tableName); System.err.println(e.getMessage()); } } private static void updateMultipleAttributes() { Table table = dynamoDB.getTable(tableName); try { UpdateItemSpec updateItemSpec = new UpdateItemSpec().withPrimaryKey("Id", 120) .withUpdateExpression("add #a :val1 set #na=:val2") .withNameMap(new NameMap().with("#a", "Authors").with("#na", "NewAttribute")) .withValueMap( new ValueMap().withStringSet(":val1", "Author YY", "Author ZZ").withString(":val2", "someValue")) .withReturnValues(ReturnValue.ALL_NEW); UpdateItemOutcome outcome = table.updateItem(updateItemSpec); // Check the response. System.out.println("Printing item after multiple attribute update..."); System.out.println(outcome.getItem().toJSONPretty()); } catch (Exception e) { System.err.println("Failed to update multiple attributes in " + tableName); System.err.println(e.getMessage()); } } private static void updateExistingAttributeConditionally() { Table table = dynamoDB.getTable(tableName); try { // Specify the desired price (25.00) and also the condition (price = // 20.00) UpdateItemSpec updateItemSpec = new UpdateItemSpec().withPrimaryKey("Id", 120) .withReturnValues(ReturnValue.ALL_NEW).withUpdateExpression("set #p = :val1") .withConditionExpression("#p = :val2").withNameMap(new NameMap().with("#p", "Price")) .withValueMap(new ValueMap().withNumber(":val1", 25).withNumber(":val2", 20)); UpdateItemOutcome outcome = table.updateItem(updateItemSpec); // Check the response. System.out.println("Printing item after conditional update to new attribute..."); System.out.println(outcome.getItem().toJSONPretty()); } catch (Exception e) { System.err.println("Error updating item in " + tableName); System.err.println(e.getMessage()); } } private static void deleteItem() { Table table = dynamoDB.getTable(tableName); try { DeleteItemSpec deleteItemSpec = new DeleteItemSpec().withPrimaryKey("Id", 120) .withConditionExpression("#ip = :val").withNameMap(new NameMap().with("#ip", "InPublication")) .withValueMap(new ValueMap().withBoolean(":val", false)).withReturnValues(ReturnValue.ALL_OLD); DeleteItemOutcome outcome = table.deleteItem(deleteItemSpec); // Check the response. System.out.println("Printing item that was deleted..."); System.out.println(outcome.getItem().toJSONPretty()); } catch (Exception e) { System.err.println("Error deleting item in " + tableName); System.err.println(e.getMessage()); } } } ``` # Exemple : opérations par lots à l'aide de l'API AWS SDK pour Java du document Cette section fournit des exemples d'opérations d'écriture et d'obtention par lots dans Amazon DynamoDB à l'aide AWS SDK pour Java de l'API Document. **Note** Le kit SDK pour Java fournit également un modèle de persistance des objets qui vous permet de mapper vos classes côté client à des tables DynamoDB. Cette approche peut réduire la quantité de code que vous avez à écrire. Pour de plus amples informations, veuillez consulter [Java 1.x : Dynamo DBMapper](DynamoDBMapper.md). **Topics** + [ ## Exemple : opération d'écriture par lots à l'aide de l'API du AWS SDK pour Java document ](#JavaDocumentAPIBatchWrite) + [ ## Exemple : opération d'obtention par lots à l'aide de l'API du AWS SDK pour Java document ](#JavaDocumentAPIBatchGet) ## Exemple : opération d'écriture par lots à l'aide de l'API du AWS SDK pour Java document L’exemple de code Java suivant exécute les opérations « put » et « delete » suivantes à l’aide de la méthode `batchWriteItem` : + Insère un élément dans la table `Forum`. + Insère un élément et supprime un élément de la table `Thread`. Vous pouvez spécifier tout nombre de demandes put et delete sur une ou plusieurs tables lors de la création de votre demande d’écriture par lots. Cependant, `batchWriteItem` limite la taille d’une demande d’écriture par lots et le nombre d’opérations « put » et « delete » d’une même opération d’écriture par lots. Si votre demande dépasse ces limites, elle est rejetée. Si votre table n’a pas suffisamment de débit alloué pour traiter cette demande, les éléments non traités de la demande sont renvoyés dans la réponse. L’exemple suivant vérifie la réponse pour voir si elle comporte des éléments de demande non traités. Si tel est le cas, une boucle est parcourue et la demande `batchWriteItem` est renvoyée avec les articles non traités de la demande. Si vous avez suivi les exemples de ce guide, vous devez déjà avoir créé les tables `Forum` et `Thread`. Vous pouvez également créer ces tables et charger des exemples de données par programmation. Pour de plus amples informations, veuillez consulter [Création de tableaux d'exemple et téléchargement de données à l'aide du AWS SDK pour Java](AppendixSampleDataCodeJava.md). Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md). **Example** ``` package com.amazonaws.codesamples.document; import java.io.IOException; import java.util.Arrays; import java.util.HashSet; import java.util.List; import java.util.Map; import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; import com.amazonaws.services.dynamodbv2.document.BatchWriteItemOutcome; import com.amazonaws.services.dynamodbv2.document.DynamoDB; import com.amazonaws.services.dynamodbv2.document.Item; import com.amazonaws.services.dynamodbv2.document.TableWriteItems; import com.amazonaws.services.dynamodbv2.model.WriteRequest; public class DocumentAPIBatchWrite { static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); static DynamoDB dynamoDB = new DynamoDB(client); static String forumTableName = "Forum"; static String threadTableName = "Thread"; public static void main(String[] args) throws IOException { writeMultipleItemsBatchWrite(); } private static void writeMultipleItemsBatchWrite() { try { // Add a new item to Forum TableWriteItems forumTableWriteItems = new TableWriteItems(forumTableName) // Forum .withItemsToPut(new Item().withPrimaryKey("Name", "Amazon RDS").withNumber("Threads", 0)); // Add a new item, and delete an existing item, from Thread // This table has a partition key and range key, so need to specify // both of them TableWriteItems threadTableWriteItems = new TableWriteItems(threadTableName) .withItemsToPut( new Item().withPrimaryKey("ForumName", "Amazon RDS", "Subject", "Amazon RDS Thread 1") .withString("Message", "ElastiCache Thread 1 message") .withStringSet("Tags", new HashSet(Arrays.asList("cache", "in-memory")))) .withHashAndRangeKeysToDelete("ForumName", "Subject", "Amazon S3", "S3 Thread 100"); System.out.println("Making the request."); BatchWriteItemOutcome outcome = dynamoDB.batchWriteItem(forumTableWriteItems, threadTableWriteItems); do { // Check for unprocessed keys which could happen if you exceed // provisioned throughput Map> unprocessedItems = outcome.getUnprocessedItems(); if (outcome.getUnprocessedItems().size() == 0) { System.out.println("No unprocessed items found"); } else { System.out.println("Retrieving the unprocessed items"); outcome = dynamoDB.batchWriteItemUnprocessed(unprocessedItems); } } while (outcome.getUnprocessedItems().size() > 0); } catch (Exception e) { System.err.println("Failed to retrieve items: "); e.printStackTrace(System.err); } } } ``` ## Exemple : opération d'obtention par lots à l'aide de l'API du AWS SDK pour Java document L’exemple de code Java suivant récupère plusieurs éléments des tables `Forum` et `Thread` à l’aide de la méthode `batchGetItem`. La demande `BatchGetItemRequest` spécifie les noms de table et une liste des clés pour chaque élément à obtenir. L’exemple traite la réponse en imprimant les éléments récupérés. **Note** Cet exemple de code part du principe que vous avez déjà chargé des données dans DynamoDB pour votre compte en suivant les instructions de la section [Création de tables et chargement de données pour des exemples de code dans DynamoDB](SampleData.md). Pour step-by-step obtenir des instructions sur l'exécution de l'exemple suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md). **Example** ``` package com.amazonaws.codesamples.document; import java.io.IOException; import java.util.List; import java.util.Map; import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; import com.amazonaws.services.dynamodbv2.document.BatchGetItemOutcome; import com.amazonaws.services.dynamodbv2.document.DynamoDB; import com.amazonaws.services.dynamodbv2.document.Item; import com.amazonaws.services.dynamodbv2.document.TableKeysAndAttributes; import com.amazonaws.services.dynamodbv2.model.KeysAndAttributes; public class DocumentAPIBatchGet { static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); static DynamoDB dynamoDB = new DynamoDB(client); static String forumTableName = "Forum"; static String threadTableName = "Thread"; public static void main(String[] args) throws IOException { retrieveMultipleItemsBatchGet(); } private static void retrieveMultipleItemsBatchGet() { try { TableKeysAndAttributes forumTableKeysAndAttributes = new TableKeysAndAttributes(forumTableName); // Add a partition key forumTableKeysAndAttributes.addHashOnlyPrimaryKeys("Name", "Amazon S3", "Amazon DynamoDB"); TableKeysAndAttributes threadTableKeysAndAttributes = new TableKeysAndAttributes(threadTableName); // Add a partition key and a sort key threadTableKeysAndAttributes.addHashAndRangePrimaryKeys("ForumName", "Subject", "Amazon DynamoDB", "DynamoDB Thread 1", "Amazon DynamoDB", "DynamoDB Thread 2", "Amazon S3", "S3 Thread 1"); System.out.println("Making the request."); BatchGetItemOutcome outcome = dynamoDB.batchGetItem(forumTableKeysAndAttributes, threadTableKeysAndAttributes); Map unprocessed = null; do { for (String tableName : outcome.getTableItems().keySet()) { System.out.println("Items in table " + tableName); List items = outcome.getTableItems().get(tableName); for (Item item : items) { System.out.println(item.toJSONPretty()); } } // Check for unprocessed keys which could happen if you exceed // provisioned // throughput or reach the limit on response size. unprocessed = outcome.getUnprocessedKeys(); if (unprocessed.isEmpty()) { System.out.println("No unprocessed keys found"); } else { System.out.println("Retrieving the unprocessed keys"); outcome = dynamoDB.batchGetItemUnprocessed(unprocessed); } } while (!unprocessed.isEmpty()); } catch (Exception e) { System.err.println("Failed to retrieve items."); System.err.println(e.getMessage()); } } } ``` # Exemple : gestion des attributs de type binaire à l'aide de l'API du AWS SDK pour Java document L’exemple de code Java suivant illustre la gestion des attributs de type binaire. L’exemple ajoute un élément à la table `Reply`. L’élément inclut un attribut de type binaire (`ExtendedMessage`) qui stocke les données compressées. Ensuite, l’exemple récupère l’élément et imprime toutes les valeurs d’attribut. À titre d’illustration, l’exemple compresse un exemple de flux et l’affecte à l’attribut `ExtendedMessage` à l’aide de la classe `GZIPOutputStream`. Lorsque le binary attribute est récupéré, il est décompressé à l’aide de la classe `GZIPInputStream`. **Note** Le kit SDK pour Java fournit également un modèle de persistance des objets qui vous permet de mapper vos classes côté client à des tables DynamoDB. Cette approche peut réduire la quantité de code que vous avez à écrire. Pour de plus amples informations, veuillez consulter [Java 1.x : Dynamo DBMapper](DynamoDBMapper.md). Si vous avez suivi la section [Création de tables et chargement de données pour des exemples de code dans DynamoDB](SampleData.md), vous devez déjà avoir créé la table `Reply`. Vous pouvez également créer cette table par programmation. Pour de plus amples informations, veuillez consulter [Création de tableaux d'exemple et téléchargement de données à l'aide du AWS SDK pour Java](AppendixSampleDataCodeJava.md). Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md). **Example** ``` package com.amazonaws.codesamples.document; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.ByteBuffer; import java.text.SimpleDateFormat; import java.util.Date; import java.util.TimeZone; import java.util.zip.GZIPInputStream; import java.util.zip.GZIPOutputStream; import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; import com.amazonaws.services.dynamodbv2.document.DynamoDB; import com.amazonaws.services.dynamodbv2.document.Item; import com.amazonaws.services.dynamodbv2.document.Table; import com.amazonaws.services.dynamodbv2.document.spec.GetItemSpec; public class DocumentAPIItemBinaryExample { static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); static DynamoDB dynamoDB = new DynamoDB(client); static String tableName = "Reply"; static SimpleDateFormat dateFormatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"); public static void main(String[] args) throws IOException { try { // Format the primary key values String threadId = "Amazon DynamoDB#DynamoDB Thread 2"; dateFormatter.setTimeZone(TimeZone.getTimeZone("UTC")); String replyDateTime = dateFormatter.format(new Date()); // Add a new reply with a binary attribute type createItem(threadId, replyDateTime); // Retrieve the reply with a binary attribute type retrieveItem(threadId, replyDateTime); // clean up by deleting the item deleteItem(threadId, replyDateTime); } catch (Exception e) { System.err.println("Error running the binary attribute type example: " + e); e.printStackTrace(System.err); } } public static void createItem(String threadId, String replyDateTime) throws IOException { Table table = dynamoDB.getTable(tableName); // Craft a long message String messageInput = "Long message to be compressed in a lengthy forum reply"; // Compress the long message ByteBuffer compressedMessage = compressString(messageInput.toString()); table.putItem(new Item().withPrimaryKey("Id", threadId).withString("ReplyDateTime", replyDateTime) .withString("Message", "Long message follows").withBinary("ExtendedMessage", compressedMessage) .withString("PostedBy", "User A")); } public static void retrieveItem(String threadId, String replyDateTime) throws IOException { Table table = dynamoDB.getTable(tableName); GetItemSpec spec = new GetItemSpec().withPrimaryKey("Id", threadId, "ReplyDateTime", replyDateTime) .withConsistentRead(true); Item item = table.getItem(spec); // Uncompress the reply message and print String uncompressed = uncompressString(ByteBuffer.wrap(item.getBinary("ExtendedMessage"))); System.out.println("Reply message:\n" + " Id: " + item.getString("Id") + "\n" + " ReplyDateTime: " + item.getString("ReplyDateTime") + "\n" + " PostedBy: " + item.getString("PostedBy") + "\n" + " Message: " + item.getString("Message") + "\n" + " ExtendedMessage (uncompressed): " + uncompressed + "\n"); } public static void deleteItem(String threadId, String replyDateTime) { Table table = dynamoDB.getTable(tableName); table.deleteItem("Id", threadId, "ReplyDateTime", replyDateTime); } private static ByteBuffer compressString(String input) throws IOException { // Compress the UTF-8 encoded String into a byte[] ByteArrayOutputStream baos = new ByteArrayOutputStream(); GZIPOutputStream os = new GZIPOutputStream(baos); os.write(input.getBytes("UTF-8")); os.close(); baos.close(); byte[] compressedBytes = baos.toByteArray(); // The following code writes the compressed bytes to a ByteBuffer. // A simpler way to do this is by simply calling // ByteBuffer.wrap(compressedBytes); // However, the longer form below shows the importance of resetting the // position of the buffer // back to the beginning of the buffer if you are writing bytes directly // to it, since the SDK // will consider only the bytes after the current position when sending // data to DynamoDB. // Using the "wrap" method automatically resets the position to zero. ByteBuffer buffer = ByteBuffer.allocate(compressedBytes.length); buffer.put(compressedBytes, 0, compressedBytes.length); buffer.position(0); // Important: reset the position of the ByteBuffer // to the beginning return buffer; } private static String uncompressString(ByteBuffer input) throws IOException { byte[] bytes = input.array(); ByteArrayInputStream bais = new ByteArrayInputStream(bytes); ByteArrayOutputStream baos = new ByteArrayOutputStream(); GZIPInputStream is = new GZIPInputStream(bais); int chunkSize = 1024; byte[] buffer = new byte[chunkSize]; int length = 0; while ((length = is.read(buffer, 0, chunkSize)) != -1) { baos.write(buffer, 0, length); } String result = new String(baos.toByteArray(), "UTF-8"); is.close(); baos.close(); bais.close(); return result; } } ```