Utilisation d’éléments : Java

L’API de document AWS SDK pour Java vous permet d’effectuer des opérations CRUD (création, lecture, mise à jour et suppression) classiques sur des éléments Amazon DynamoDB dans une table.

Cette section comporte les exemples Java pour exécuter plusieurs actions d’élément d’API de document Java et plusieurs exemples opérationnels.

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 en savoir plus, consultez Mise à jour d’un élément.

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 lève une ConditionalCheckFailedException. L’extrait de code spécifie les paramètres facultatifs suivants dans la méthode putItem :

L’exemple suivant ajoute un nouvel élément livre à l’aide de ces paramètres facultatifs.

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

{
    "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 :

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

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 en savoir plus, consultez Utilisation d’expressions de projection dans DynamoDB.

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.

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,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"]}}}

GetItemSpec spec = new GetItemSpec()
    .withPrimaryKey("Id", 210)
    .withProjectionExpression("VendorInfo.V01, Title, Price");

Item item = table.getItem(spec);
System.out.println(item.toJSON());

{"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. Pour insérer ou supprimer plusieurs éléments à l’aide de l’API de document AWS SDK pour Java, procédez comme suit :

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 :

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 AWS SDK pour 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. Vous pouvez récupérer un seul élément à l’aide de la méthode getItem.

Procédez comme suit :

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

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

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 :

Procédez comme suit :

L’exemple de code Java suivant illustre 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<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

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 lève une 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.

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

Compteur atomique

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<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 souhaitez supprimer.

Procédez comme suit :

L’extrait de code Java suivant illustre ces tâches.

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

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