Utilisation des éléments : Java - Amazon DynamoDB

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 Document AWS SDK for Java pour effectuer des opérations CRUD (création, lecture, mise à jour et suppression) classiques sur des éléments Amazon DynamoDB dans 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 plus d’informations, consultez Java 1.x : DynamoDBMapper.

Cette section contient les exemples Java pour exécuter plusieurs actions d'élément d'API Java Document et plusieurs exemples opérationnels.

Placement 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, si vous souhaitez mettre à jour uniquement des attributs spécifiques, vous pouvez utiliser la méthode updateItem. Pour plus d’informations, consultez Mise à jour d'un élément.

Procédez comme suit :

  1. Créez une instance de la classe DynamoDB.

  2. Créez une instance de la classe Table pour représenter la table que vous souhaitez utiliser.

  3. 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 de ses attributs.

  4. Appelez la méthode putItemde l'objet Table, à l'aide de l'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.

Exemple
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); // Build a list of related items List<Number> relatedItems = new ArrayList<Number>(); relatedItems.add(341); relatedItems.add(472); relatedItems.add(649); //Build a map of product pictures Map<String, String> pictures = new HashMap<String, String>(); 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<String, List<String>> reviews = new HashMap<String, List<String>>(); List<String> fiveStarReviews = new ArrayList<String>(); 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<String> oneStarReviews = new ArrayList<String>(); 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<String>(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 a des attributs qui sont scalaires (String, Number, Boolean et Null), des ensembles (String Set) et des types de documents (List, Map).

Spécification de paramètres facultatifs

En même temps que les paramètres requis, vous pouvez également spécifier les paramètres facultatifs de la méthode putItem. Par exemple, l'extrait de code Java suivant utilise un paramètre facultatif pour spécifier une condition pour le chargement de l'élément. Si la condition que vous spécifiez n'est pas remplie, AWS SDK for Java lève une 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 requête. Le code définit la condition selon laquelle l'élément existant ayant la même clé primaire est remplacé uniquement s'il a un attribut ISBN qui correspond à une valeur spécifique.

  • Une carte pour ExpressionAttributeValues qui sera utilisée 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.

Exemple
Item item = new Item() .withPrimaryKey("Id", 104) .withString("Title", "Book 104 Title") .withString("ISBN", "444-4444444444") .withNumber("Price", 20) .withStringSet("Authors", new HashSet<String>(Arrays.asList("Author1", "Author2"))); Map<String, Object> expressionAttributeValues = new HashMap<String, Object>(); 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 avec un type de données DynamoDB natif.

Supposons que vous vouliez stocker le document JSON suivant, contenant des fournisseurs qui peuvent exécuter des commandes pour un produit spécifique.

Exemple
{ "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" ] } }

Vous pouvez utiliser la méthode withJSON pour 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

Pour récupérer un élément unique, utilisez la méthode getItem d'un objet Table. Procédez comme suit :

  1. Créez une instance de la classe DynamoDB.

  2. Créez une instance de la classe Table pour représenter la table que vous souhaitez utiliser.

  3. 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

En même temps que les paramètres requis, vous pouvez également spécifier les paramètres facultatifs pour la méthode getItem. Par exemple, l'extrait de code Java suivant utilise une méthode facultative pour récupérer uniquement une liste précise d'attributs et spécifier des lectures cohérentes fortes. (Pour en savoir plus sur la cohérence en lecture, consultez Cohérence en lecture.)

Vous pouvez utiliser une ProjectionExpression pour 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 plus d’informations, consultez Expressions de projections.

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 un 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.

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

Pour imprimer un Item dans un format contrôlable de visu, utilisez 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,vous stockez un document JSON dans un attribut Map nommé VendorInfo. Vous pouvez utiliser la méthode getItem pour extraire la totalité du document au format JSON. Ou vous pouvez utiliser la notation chemin pour extraire uniquement certains éléments du 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

Vous pouvez utiliser la méthode toJSON pour convertir n'importe quel é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 affiche 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 fait référence à 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 permettant d'insérer ou de supprimer plusieurs éléments à l'aide de l'API de document AWS SDK for Java.

  1. Créez une instance de la classe DynamoDB.

  2. 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.

  3. Appelez la méthode batchWriteItem en fournissant le ou les objets TableWriteItems que vous avez créés à l'étape précédente.

  4. 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 une 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 plus d’informations, consultez Quotas de service, de compte et de table dans Amazon DynamoDB.

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ère 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érations d'écriture par lots à l'aide de l'API de document de AWS SDK for Java.

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.

  2. 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.

  3. Appelez la méthode batchGetItem en fournissant le ou 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<Item> items = outcome.getTableItems().get(tableName); for (Item item : items) { System.out.println(item); } }

Spécification de paramètres facultatifs

En même temps que les paramètres requis, 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 seuls les attributs Threads doivent être récupérés.

Exemple
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 qui ne sont pas spécifiés dans l'entrée, putItem va supprimer ces attributs de l'élément.

En général, nous vous recommandons d'utiliser updateItem chaque fois que vous voulez 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.

  2. 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'un niveau.

Une carte ExpressionAttributeValues est utilisée dans UpdateExpression. Les espaces réservés :val1 et :val2 seront remplacés lors de l'exécution avec les valeurs réelles pour Authors et Price.

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDB dynamoDB = new DynamoDB(client); Table table = dynamoDB.getTable("ProductCatalog"); Map<String, String> expressionAttributeNames = new HashMap<String, String>(); expressionAttributeNames.put("#A", "Authors"); expressionAttributeNames.put("#P", "Price"); expressionAttributeNames.put("#I", "ISBN"); Map<String, Object> expressionAttributeValues = new HashMap<String, Object>(); expressionAttributeValues.put(":val1", new HashSet<String>(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

Avec les paramètres requis, vous pouvez également spécifier des paramètres facultatifs pour la méthode updateItem, y compris une condition devant être satisfaite afin que la mise à jour puisse se produire. Si la condition que vous spécifiez n'est pas remplie, AWS SDK for Java lève une ConditionalCheckFailedException. Par exemple, l'extrait de code Java suivant met à jour de façon conditionnelle le prix d'un élément « book » avec la valeur 25. Il spécifie une ConditionExpression indiquant que le prix doit être mis à jour uniquement si le prix existant est 20.

Exemple
Table table = dynamoDB.getTable("ProductCatalog"); Map<String, String> expressionAttributeNames = new HashMap<String, String>(); expressionAttributeNames.put("#P", "Price"); Map<String, Object> expressionAttributeValues = new HashMap<String, Object>(); 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

Vous pouvez utiliser updateItem pour 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, utilisez une UpdateExpression avec une action set pour ajouter une valeur numérique à un attribut existant de type Number.

L'extrait de code suivant illustre cette action, en incrémentant l'attribut Quantity d'une unité. Il démontre également l'utilisation du paramètre ExpressionAttributeNames dans une UpdateExpression.

Table table = dynamoDB.getTable("ProductCatalog"); Map<String,String> expressionAttributeNames = new HashMap<String,String>(); expressionAttributeNames.put("#p", "PageCount"); Map<String,Object> expressionAttributeValues = new HashMap<String,Object>(); 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 voulez supprimer.

Procédez comme suit :

  1. Créez une instance du client DynamoDB.

  2. 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.

Exemple
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é uniquement si le livre n'est plus en publication (l'attribut InPublication est false).

Exemple
Map<String,Object> expressionAttributeValues = new HashMap<String,Object>(); expressionAttributeValues.put(":val", false); DeleteItemOutcome outcome = table.deleteItem("Id",103, "InPublication = :val", null, // ExpressionAttributeNames - not used in this example expressionAttributeValues);