Utilisation des éléments et des attributs - Amazon DynamoDB

Utilisation des éléments et des attributs

Dans Amazon DynamoDB, un élément est une collection d'attributs. Chaque attribut a un nom et une valeur. Une valeur d'attribut peut être de type scalar, set ou document. Pour plus d'informations, consultez Fonctionnement d'Amazon DynamoDB.

DynamoDB fournit quatre opérations correspondant aux fonctionnalités de base de création, lecture, mise à jour et suppression (CRUD). Toutes ces opérations sont atomiques.

  • PutItem – Création d'un élément.

  • GetItem – Lecture d'un élément.

  • UpdateItem – Mise à jour d'un élément.

  • DeleteItem – Suppression d'un élément.

Pour chacune de ces opérations, vous devez indiquer la clé primaire de l'élément que vous souhaitez utiliser. Par exemple, pour lire un élément avec GetItem, vous devez spécifier la clé de partition et la clé de tri (le cas échéant) de cet élément.

Outre les quatre opérations CRUD de base, DynamoDB offre les fonctionnalités suivantes :

  • BatchGetItem – Lecture de 100 éléments au plus à partir d'une ou de plusieurs tables.

  • BatchWriteItem – Création ou suppression de 25 éléments au plus dans une ou plusieurs tables.

Ces opérations par lot peuvent associer plusieurs opérations CRUD dans une même demande. En outre, les opérations par lot lisent et écrivent des éléments en parallèle afin de réduire les latences de réponse.

Cette section explique comment utiliser ces opérations. Elle comprend des rubriques connexes, telles que les mises à jour conditionnelles et les compteurs atomiques. Cette section inclut également un exemple de code qui utilise les kits SDK AWS.

Lecture d'un élément

Pour lire un élément à partir d'une table DynamoDB, utilisez l'opération GetItem. Vous devez fournir le nom de la table, ainsi que la clé primaire de l'élément que vous voulez.

Exemple

L'exemple AWS CLI suivant montre comment lire un élément dans la table ProductCatalog.

aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}'
Note

Avec GetItem, vous devez spécifier la totalité de la clé primaire, pas simplement une partie. Par exemple, si une table possède une clé primaire composite (clé de partition et clé de tri), vous devez fournir une valeur pour la clé de partition et une valeur pour la clé de tri.

Une demande GetItem effectue une lecture éventuellement cohérente (eventually consistent) par défaut. Vous pouvez utiliser le paramètre ConsistentRead pour demander une lecture fortement cohérente à la place. (Celle-ci consomme des unités supplémentaires de capacité de lecture, mais renvoie la version la plus récente de l'élément.)

GetItem retourne tous les attributs de l'élément. Vous pouvez utiliser une expression de projection pour renvoyer uniquement certains des attributs. Pour plus d'informations, consultez Expressions de projections.

Pour renvoyer le nombre d'unités de capacité de lecture consommées par l'opération GetItem, définissez le paramètre ReturnConsumedCapacity sur la valeur TOTAL.

Exemple

L'exemple AWS Command Line Interface suivant (AWS CLI) présente certains des paramètres GetItem facultatifs.

aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL

Ecriture d'un élément

Pour créer, mettre à jour ou supprimer un élément dans une table DynamoDB, utilisez l'une des opérations suivantes :

  • PutItem

  • UpdateItem

  • DeleteItem

Pour chacune de ces opérations, vous devez spécifier la totalité de la clé primaire, pas simplement une partie. Par exemple, si une table possède une clé primaire composite (clé de partition et clé de tri), vous devez fournir une valeur pour la clé de partition et une valeur pour la clé de tri.

Pour renvoyer le nombre d'unités de capacité d'écriture consommées par l'une de ces opérations, définissez le paramètre ReturnConsumedCapacity sur l'une des valeurs suivantes :

  • TOTAL – Renvoie le nombre total d'unités de capacité d'écriture consommées.

  • INDEXES – Renvoie le nombre total d'unités de capacité de lecture consommées, avec les sous-totaux correspondant à la table et aux index secondaires concernés par l'opération.

  • NONE – Aucun détail concernant la capacité d'écriture n'est renvoyé. (Il s'agit de l'option par défaut.)

PutItem

PutItem crée un élément. Si un élément avec la même clé existe déjà dans la table, il est remplacé par le nouvel élément.

Exemple

Écrivez un nouvel élément dans la table Thread. La clé primaire de la table Thread est composée de ForumName (clé de partition) et Subject (clé de tri).

aws dynamodb put-item \ --table-name Thread \ --item file://item.json

Les arguments de la fonction --item sont stockés dans le fichier item.json.

{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} }

UpdateItem

S'il n'existe aucun élément associé à la clé spécifiée, UpdateItem en crée un. Dans le cas contraire, l'opération modifie les attributs d'un élément existant.

Vous utilisez une expression de mise à jour pour préciser les attributs à modifier, ainsi que leurs nouvelles valeurs. Pour plus d'informations, consultez Expressions de mise à jour.

Au sein de l'expression de mise à jour, vous utilisez des valeurs d'attributs d'expressions comme espaces réservés pour les valeurs réelles. Pour plus d'informations, consultez Valeurs d'attributs d'expressions.

Exemple

Modifiez plusieurs attributs dans l'élément Thread. Le paramètre ReturnValues facultatif présente l'élément tel qu'il apparaît après la mise à jour. Pour plus d'informations, consultez Valeurs renvoyées.

aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW

Les arguments de la fonction --key sont stockés dans le fichier key.json.

{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} }

Les arguments de la fonction --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} }

DeleteItem

DeleteItem supprime l'élément avec la clé spécifiée.

Exemple

L'exemple AWS CLI suivant illustre la suppression de l'élément Thread.

aws dynamodb delete-item \ --table-name Thread \ --key file://key.json

Valeurs renvoyées

Dans certains cas, vous souhaitez que DynamoDB renvoie certaines valeurs d'attribut telles qu'elles apparaissent avant ou après leur modification. Les opérations PutItem, UpdateItem et DeleteItem ont un paramètre ReturnValues que vous pouvez utiliser pour renvoyer les valeurs d'attribut avant ou après leur modification.

La valeur par défaut de ReturnValues est NONE, ce qui signifie que DynamoDB ne renvoie aucune information concernant les attributs qui ont été modifiés.

Les autres paramètres valides pour ReturnValues sont les suivants, classés par opération d'API DynamoDB.

PutItem

  • ReturnValues: ALL_OLD

    • Si vous remplacez un élément existant, ALL_OLD renvoie l'élément entier tel qu'il apparaissait avant son remplacement.

    • Si vous écrivez un élément qui n'existe pas, ALL_OLD n'a aucun effet.

UpdateItem

L'utilisation la plus courante d'UpdateItem est la mise à jour d'un élément existant. Cependant, UpdateItem effectue une opération de mise à jour/insertion, ce qui signifie qu'il crée automatiquement l'élément si celui-ci n'existe pas.

  • ReturnValues: ALL_OLD

    • Si vous mettez à jour un élément existant, ALL_OLD renvoie l'élément entier tel qu'il apparaissait avant sa mise à jour.

    • Si vous mettez à jour un élément qui n'existe pas (upsert), ALL_OLD n'a aucun effet.

  • ReturnValues: ALL_NEW

    • Si vous mettez à jour un élément existant, ALL_NEW renvoie l'élément entier tel qu'il apparaît après la mise à jour.

    • Si vous mettez à jour un élément qui n'existe pas (upsert), ALL_NEW renvoie l'élément entier.

  • ReturnValues: UPDATED_OLD

    • Si vous mettez à jour un élément existant, UPDATED_OLD renvoie uniquement les attributs mis à jour tels qu'ils apparaissaient avant leur mise à jour.

    • Si vous mettez à jour un élément qui n'existe pas (upsert), UPDATED_OLD n'a aucun effet.

  • ReturnValues: UPDATED_NEW

    • Si vous mettez à jour un élément existant, UPDATED_NEW renvoie uniquement les attributs affectés tels qu'ils apparaissaient après leur mise à jour.

    • Si vous mettez à jour (upsert) un élément qui n'existe pas, UPDATED_NEW renvoie uniquement les attributs mis à jour tels qu'ils apparaissent après la mise à jour.

DeleteItem

  • ReturnValues: ALL_OLD

    • Si vous supprimez un élément existant, ALL_OLD renvoie l'élément entier tel qu'il apparaissait avant sa suppression.

    • Si vous supprimez un élément qui n'existe pas, ALL_OLD ne renvoie pas de données.

Opérations par lot

Pour les applications ayant besoin de lire ou d'écrire plusieurs éléments, DynamoDB fournit les opérations BatchGetItem et BatchWriteItem. L'utilisation de ces opérations peut réduire le nombre d'allers et retours réseau entre votre application et DynamoDB. En outre, DynamoDB effectue les opérations de lecture ou d'écriture individuelles en parallèle. Vos applications bénéficient de ce parallélisme sans devoir gérer la simultanéité ou les threads.

Les opérations par lot sont essentiellement des wrappers autour de plusieurs demandes de lecture ou d'écriture. Par exemple, si une demande BatchGetItem contient cinq éléments, DynamoDB exécute cinq opérations GetItem pour vous. De même, si une demande BatchWriteItem contient deux demandes d'insertion et quatre demandes de suppression, DynamoDB exécute deux demandes PutItem et quatre demandes DeleteItem.

En général, une opération de traitement par lots n'échoue pas, sauf si toutes les demandes du traitement par lots échouent. Supposons, par exemple, que vous effectuiez une opération BatchGetItem, mais que l'une des demandes GetItem du lot échoue. Dans ce cas, BatchGetItem renvoie les clés et les données provenant de la demande GetItem qui a échoué. Les autres demandes GetItem du lot ne sont pas affectées.

BatchGetItem

Une seule opération BatchGetItem peut contenir jusqu'à 100 demandes GetItem individuelles, et peuvent extraire jusqu'à 16 Mo de données. En outre, une opération BatchGetItem peut extraire les éléments de plusieurs tables.

Exemple

Extrayez deux éléments de la table Thread en utilisant une expression de projection pour renvoyer uniquement certains des attributs.

aws dynamodb batch-get-item \ --request-items file://request-items.json

Les arguments de la fonction --request-items sont stockés dans le fichier request-items.json.

{ "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } }

BatchWriteItem

L'opération BatchWriteItem peut contenir jusqu'à 25 demandes PutItem et DeleteItem individuelles, et peut écrire jusqu'à 16 Mo de données (la taille maximale d'un élément est de 400 Ko). En outre, une même opération BatchWriteItem peut insérer ou supprimer les éléments de plusieurs tables.

Note

BatchWriteItem ne prend pas en charge les demandes UpdateItem.

Exemple

Ajoute deux éléments à la table ProductCatalog.

aws dynamodb batch-write-item \ --request-items file://request-items.json

Les arguments de la fonction --request-items sont stockés dans le fichier request-items.json.

{ "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] }

Compteurs atomiques

Vous pouvez utiliser l'opération UpdateItem pour implémenter un compteur atomique, c'est-à-dire un attribut numérique incrémenté sans condition, sans interférer avec d'autres demandes d'écriture. (Toutes les demandes d'écriture sont appliquées dans l'ordre dans lequel elles ont été reçues.) Avec un compteur atomique, les mises à jour ne sont pas idempotentes. En d'autres termes, la valeur numérique augmente chaque fois que vous appelez UpdateItem.

Vous pouvez utiliser un compteur atomique pour suivre le nombre de visiteurs d'un site web. Dans ce cas, l'application doit incrémenter une valeur numérique, quelle que soit sa valeur actuelle. En cas d'échec d'une opération UpdateItem, l'application peut simplement retenter l'opération. Cela risquerait de mettre à jour le compteur deux fois, mais vous pourriez probablement tolérer de sur-comptabiliser ou sous-comptabiliser légèrement les visiteurs.

Dans le cas contraire, l'utilisation d'un compteur automatique n'est pas adaptée (par exemple, dans une application bancaire). Il est alors plus sûr d'utiliser une mise à jour conditionnelle plutôt qu'un compteur atomique.

Pour plus d'informations, consultez Incrémentation et décrémentation d'attributs numériques.

Exemple

L'exemple d'AWS CLI suivant augmente le Price d'un produit de 5 incréments. (Puisque l'opération UpdateItem n'est pas idempotente, le Price augmente à chaque exécution de cet exemple.)

aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW

Ecritures conditionnelles

Par défaut, les opérations d'écriture de DynamoDB (PutItem, UpdateItem, DeleteItem) sont sans condition : chacune remplace un élément existant doté de la clé primaire spécifiée.

DynamoDB prend en charge, en option, les écritures conditionnelles pour ces opérations. Une écriture conditionnelle réussit uniquement si les attributs de l'élément satisfont une ou plusieurs conditions prévues. Dans le cas contraire, elle renvoie une erreur. Les écritures conditionnelles sont utiles dans de nombreux cas. Par exemple, vous pouvez décider qu'une opération PutItem ne réussit que si aucun élément avec la même clé primaire n'existe déjà. Vous pouvez également empêcher une opération UpdateItem de modifier un élément si l'un de ses attributs possède une valeur donnée.

Les écritures conditionnelles sont utiles dans les cas où plusieurs utilisateurs tentent de modifier le même élément. Examinez le diagramme suivant, dans lequel deux utilisateurs (Alice et Bob) utilisent le même élément provenant d'une table DynamoDB.

Supposons qu'Alice utilise l'AWS CLI pour mettre à jour l'attribut Price avec la valeur 8.

aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments de la fonction --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json :

{ ":newval":{"N":"8"} }

Supposons maintenant que Bob émette une demande UpdateItem similaire ultérieurement, mais qu'il change la valeur de Price en 12. Pour Bob, le paramètre --expression-attribute-values prend la forme suivante.

{ ":newval":{"N":"12"} }

La demande de Bob aboutit, mais la mise à jour précédente d'Alice est perdue.

Pour demander une opération PutItem, DeleteItem ou UpdateItem conditionnelle, vous spécifiez une expression de condition. Une expression de condition est une chaîne contenant des noms d'attributs, des opérateurs conditionnels et des fonctions intégrées. L'expression entière doit avoir la valeur true. Sinon, l'opération échoue.

Examinez maintenant le diagramme suivant, qui présente les écritures conditionnelles qui empêcheraient le remplacement de la mise à jour d'Alice.

Alice tente dans un premier temps de mettre à jour Price avec la valeur 8, mais uniquement si la valeur actuelle de Price est 10.

aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments de la fonction --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":newval":{"N":"8"}, ":currval":{"N":"10"} }

La mise à jour d'Alice aboutit, car la condition a la valeur true.

Ensuite, Bob tente de mettre à jour la valeur de Price à 12, mais uniquement si le Price actuel est 10. Pour Bob, le paramètre --expression-attribute-values prend la forme suivante.

{ ":newval":{"N":"12"}, ":currval":{"N":"10"} }

Comme Alice a précédemment modifié la valeur de Price en 8, l'expression de condition prend la valeur false et la mise à jour de Bob échoue.

Pour plus d'informations, consultez Expressions de condition.

Ecriture conditionnelle idempotence

Les écritures conditionnelles peuvent être idempotentes si la vérification conditionnelle porte sur le même attribut que celui mis à jour. Cela signifie que DynamoDB effectue une demande d'écriture donnée uniquement si certaines valeurs d'attribut dans l'élément correspondent à ce que attendez au moment de la demande.

Par exemple, supposons que vous émettiez une demande UpdateItem pour augmenter le Price d'un article de 3, mais uniquement si le Price actuel est 20. Après l'envoi de la demande, mais avant que vous n'obteniez les résultats, une erreur réseau se produit et vous ne savez pas si votre demande a abouti ou non. Cette écriture conditionnelle étant idempotente, vous pouvez relancer la même demande UpdateItem, et DynamoDB met à jour l'élément uniquement si la valeur Price est actuellement 20.

Unités de capacité consommées par les écritures conditionnelles

Si une ConditionExpression prend la valeur false pendant une écriture conditionnelle, DynamoDB continue à utiliser la capacité d'écriture de la table :

  • Si l'élément n'existe pas dans la table, DynamoDB utilise une unité de capacité d'écriture.

  • Si l'élément existe, le nombre d'unités de capacité d'écriture utilisées dépend de la taille de l'élément. Par exemple, une écriture conditionnelle d'un élément de 1 Ko qui échoue consomme une unité de capacité d'écriture. Si l'élément faisait deux fois cette taille, l'échec d'écriture conditionnelle utiliserait deux unités de capacité d'écriture.

Note

Les opérations d'écriture consomment uniquement des unités de capacité d'écriture. Elles n'utilisent jamais d'unités de capacité de lecture.

Une écriture conditionnelle ayant échoué retourne un ConditionalCheckFailedException. Lorsque cela se produit, vous ne recevrez aucune information dans la réponse concernant la capacité d'écriture qui a été consommée. Cependant, vous pouvez afficher la métrique ConsumedWriteCapacityUnits pour la table dans Amazon CloudWatch. Pour plus d’informations, consultez Métriques DynamoDB dans Journalisation et surveillance dans DynamoDB.

Pour renvoyer le nombre d'unités de capacité d'écriture utilisées au cours d'une écriture conditionnelle, utilisez le paramètre ReturnConsumedCapacity :

  • TOTAL – Renvoie le nombre total d'unités de capacité d'écriture consommées.

  • INDEXES – Renvoie le nombre total d'unités de capacité de lecture consommées, avec les sous-totaux correspondant à la table et aux index secondaires concernés par l'opération.

  • NONE – Aucun détail concernant la capacité d'écriture n'est renvoyé. (Il s'agit de l'option par défaut.)

Note

Contrairement à un index secondaire global, un index secondaire local partage sa capacité de débit approvisionné avec sa table. L'activité de lecture et d'écriture sur un index secondaire local consomme la capacité de débit approvisionné de la table.