Utilisation d’éléments et d’attributs dans DynamoDB

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 scalaire, d’ensemble ou de document. Pour de plus amples informations, veuillez consulter 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.

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 :

Ces opérations par lots peuvent associer plusieurs opérations CRUD dans une même demande. En outre, les opérations par lots 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 utilisant le AWS SDKs.

Lecture d’un élément

L’opération GetItem vous permet de lire un élément à partir d’une table DynamoDB. Vous devez fournir le nom de la table, ainsi que la clé primaire de l’élément souhaité.

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

Une demande GetItem effectue une lecture cohérente à terme par défaut. Le paramètre ConsistentRead vous permet de demander une lecture fortement cohérente à la place. (Cela consomme des unités de capacité de lecture supplémentaires, mais renvoie la up-to-date version la plus complète de l'article.)

GetItem renvoie tous les attributs de l’élément. Vous pouvez renvoyer uniquement certains des attributs à l’aide d’une expression de projection. Pour de plus amples informations, veuillez consulter Utilisation d’expressions de projection dans DynamoDB.

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.

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

Écriture d’un élément

Créez, mettez à jour ou supprimez un élément dans une table DynamoDB à l’aide de l’une des opérations suivantes :

Pour chacune de ces opérations, vous devez spécifier la totalité de la clé primaire, et non uniquement 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 :

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.

aws dynamodb put-item \
    --table-name Thread \
    --item file://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 préciser les attributs à modifier, ainsi que leurs nouvelles valeurs, à l’aide d’une expression de mise à jour. Pour de plus amples informations, veuillez consulter Utilisation d’expressions de mise à jour dans DynamoDB.

Au sein de l’expression de mise à jour, vous utilisez des valeurs d’attributs d’expression comme espaces réservés pour les valeurs réelles. Pour de plus amples informations, veuillez consulter Utilisation de valeurs d’attributs d’expression dans DynamoDB.

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.

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 s’affichent avant ou après leur modification. Les opérations PutItem, UpdateItem et DeleteItem ont un paramètre ReturnValues vous permettant de renvoyer les valeurs d’attribut avant ou après leur modification.

La valeur par défaut de ReturnValues est NONE. Autrement dit, DynamoDB ne renvoie aucune information concernant les attributs modifiés.

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

PutItem

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. Autrement dit, il crée automatiquement l’élément si celui-ci n’existe pas.

DeleteItem

Opérations par lots

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 lots sont essentiellement des wrappers autour de plusieurs demandes de lecture ou d’écriture. Par exemple, si une demande BatchGetItem comporte cinq éléments, DynamoDB exécute cinq opérations GetItem pour vous. De même, si une demande BatchWriteItem comporte 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 par lots n’échoue pas, sauf si toutes les demandes du lot é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 des éléments de plusieurs tables.

aws dynamodb batch-get-item \
    --request-items file://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 des éléments de plusieurs tables.

aws dynamodb batch-write-item \
    --request-items file://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

L’opération UpdateItem vous permet d’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. Autrement dit, la valeur numérique augmente ou diminue chaque fois que vous appelez UpdateItem. Si la valeur d’incrément permettant de mettre à jour le compteur atomique est positive, cela peut provoquer un surcomptage. Si la valeur d’incrément est négative, cela peut entraîner une sous-estimation.

Un compteur atomique vous permet de 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 de plus amples informations, veuillez consulter Incrémentation et décrémentation d’attributs numériques.

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

Écritures 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 seulement si les attributs de l’élément remplissent une ou plusieurs conditions prévues. Dans le cas contraire, elle renvoie une erreur.

Les écritures conditionnelles vérifient leurs conditions par rapport à la dernière version mise à jour de l’élément. Notez que si l’élément n’existait pas auparavant ou si la dernière opération réussie sur cet élément était une suppression, l’écriture conditionnelle ne trouvera aucun élément précédent.

Les écritures conditionnelles sont utiles dans de nombreux cas. Par exemple, vous pouvez décider qu’une opération PutItem réussit seulement 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 le AWS CLI pour mettre à jour l'Priceattribut à 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 redéfinisse l’attribut Price sur la valeur 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 comportant 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 redéfinir l’attribut Price sur la valeur 8, mais seulement si la valeur actuelle de l’attribut 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 redéfinir l’attribut Price sur la valeur 12, mais seulement si la valeur actuelle de l’attribut Price 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 redéfinit l’attribut Price sur la valeur 8, l’expression de condition a la valeur false et la mise à jour de Bob échoue.

Pour de plus amples informations, veuillez consulter Exemple de commande CLI d’expression de condition DynamoDB.

Idempotence d’écriture conditionnelle

Les écritures conditionnelles peuvent être idempotentes si la vérification conditionnelle porte sur le même attribut que celui mis à jour. Autrement dit, DynamoDB effectue une demande d’écriture donnée seulement si certaines valeurs d’attribut dans l’élément correspondent à ce que vous attendez lors de la demande.

Par exemple, supposons que vous émettiez une demande UpdateItem pour augmenter l’attribut Price d’un élément de 3, mais seulement si la valeur actuelle de l’attribut Price 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 retenter la même demande UpdateItem, puis DynamoDB met à jour l’élément seulement si l’attribut Price est actuellement défini sur la valeur 20.

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

Si une ConditionExpression prend la valeur false pendant une écriture conditionnelle, DynamoDB continue à consommer la capacité d’écriture de la table. La quantité consommée dépend de la taille de l’élément existant (ou valeur minimale de 1). Par exemple, si un élément existant fait 300 Ko et que l’élément que vous essayez de créer ou mettre à jour fait 310 Ko, les unités de capacité d’écriture consommées seront de 300 Ko si la condition n’est pas remplie et de 310 si elle est remplie. S’il s’agit d’un nouvel élément (élément non existant), les unités de capacité d’écriture consommées seront de 1 si la condition n’est pas remplie et de 310 si elle est remplie.

Une écriture conditionnelle ayant échoué renvoie un ConditionalCheckFailedException. Lorsque cela se produit, vous ne recevez aucune information dans la réponse concernant la capacité d’écriture consommée.

Renvoyez le nombre d’unités de capacité d’écriture consommées au cours d’une écriture conditionnelle à l’aide du paramètre ReturnConsumedCapacity :