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 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](HowItWorks.md).
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 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.
**Topics**
+ [Tailles et formats d’élément DynamoDB](CapacityUnitCalculations.md)
+ [Lecture d’un élément](#WorkingWithItems.ReadingData)
+ [Écriture d’un élément](#WorkingWithItems.WritingData)
+ [Valeurs renvoyées](#WorkingWithItems.ReturnValues)
+ [Opérations par lots](#WorkingWithItems.BatchOperations)
+ [Compteurs atomiques](#WorkingWithItems.AtomicCounters)
+ [Écritures conditionnelles](#WorkingWithItems.ConditionalUpdate)
+ [Utilisation d’expressions dans DynamoDB](Expressions.md)
+ [Utilisation de la durée de vie (TTL) dans DynamoDB](TTL.md)
+ [Interrogation de tables dans DynamoDB](Query.md)
+ [Analyse de tables dans DynamoDB](Scan.md)
+ [PartiQL – Langage de requête compatible SQL pour Amazon DynamoDB](ql-reference.md)
+ [Utilisation des éléments : Java](JavaDocumentAPIItemCRUD.md)
+ [Utilisation des élements : .NET](LowLevelDotNetItemCRUD.md)
# Tailles et formats d’élément DynamoDB
Les tables DynamoDB étant sans schéma, sauf pour la clé primaire, les éléments d’une table peuvent avoir des attributs, tailles et types de données différents.
La taille totale d’un élément est la somme des longueurs de ses noms et valeurs d’attribut, plus toute surcharge applicable telle que décrite ci-dessous. Vous pouvez évaluer la taille des attributs à l’aide des consignes suivantes :
+ Les chaînes sont Unicode avec codage binaire UTF-8. La taille d’une chaîne est *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 (nombre d’octets codés en UTF-8)*.
+ Les nombres sont de longueur variable, avec 38 chiffres significatifs au plus. Les zéros de début et de fin sont tronqués. La taille d’un nombre est approximativement *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 (1 octet pour 2 chiffres significatifs) \$1 (1 octet)*.
+ Une valeur binaire doit être codée en base 64 avant d’être envoyée à DynamoDB, mais la longueur en octets bruts de la valeur est utilisée pour le calcul de la taille. La taille d’un binary attribute est *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 (nombre d’octets bruts).*
+ La taille d’un attribut nul ou booléen est *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 (1 octet)*.
+ Un attribut de type `List` ou `Map` a besoin de 3 octets de surcharge, quel que soit son contenu. La taille d’un attribut `List` ou `Map` est *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 somme de (taille des éléments imbriqués) \$1 (3 octets)*. La taille d’un attribut `List` ou `Map` vide est *(nombre d’octets codés en UTF-8 du nom d’attribut) \$1 (3 octets)*.
+ Chaque élément `List` ou `Map` nécessite également 1 octet de surcharge.
**Note**
Nous vous recommandons de choisir des noms d’attribut courts. Cela vous permet de réduire la quantité de stockage requise, mais peut également réduire la quantité RCU/WCUs que vous utilisez.
À des fins de facturation du stockage, chaque élément inclut une surcharge de stockage par élément qui dépend des fonctionnalités que vous avez activées.
+ Tous les éléments de DynamoDB nécessitent une surcharge de stockage de 100 octets pour l’indexation.
+ Certaines fonctionnalités DynamoDB (tables globales, transactions, récupération de données de modification pour Kinesis Data Streams avec DynamoDB) nécessitent une surcharge de stockage supplémentaire pour tenir compte des attributs créés par le système résultant de l’activation de ces fonctions. Par exemple, les tables globales nécessitent une surcharge de stockage de 48 octets supplémentaires.
## 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é.
**Example**
L' AWS CLI exemple suivant montre comment lire un élément du `ProductCatalog` tableau.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"1"}}'
```
**Note**
Avec `GetItem`, 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.
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](Expressions.ProjectionExpressions.md).
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`.
**Example**
L'exemple suivant AWS Command Line Interface (AWS CLI) montre certains des `GetItem` paramètres facultatifs.
```
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 :
+ `PutItem`
+ `UpdateItem`
+ `DeleteItem`
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 :
+ `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.
**Example**
É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 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](Expressions.UpdateExpressions.md).
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](Expressions.ExpressionAttributeValues.md).
**Example**
Modifiez plusieurs attributs dans l’élément `Thread`. Le paramètre `ReturnValues` facultatif présente l’élément tel qu’il s’affiche après la mise à jour. Pour de plus amples informations, veuillez consulter [Valeurs renvoyées](#WorkingWithItems.ReturnValues).
```
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.
**Example**
L' AWS CLI exemple suivant montre comment supprimer l'`Thread`élément.
```
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
+ `ReturnValues`: `ALL_OLD`
+ Si vous remplacez un élément existant, `ALL_OLD` renvoie l’élément entier tel qu’il s’affichait 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*. Autrement dit, 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 s’affichait 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 s’affiche après sa 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 s’affichaient 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 s’affichaient 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 s’affichent 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 s’affichait avant sa suppression.
+ Si vous supprimez un élément qui n’existe pas, `ALL_OLD` ne renvoie pas de données.
## 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.
**Example**
Extrayez deux éléments de la table `Thread` en renvoyant uniquement certains des attributs à l’aide d’une expression de projection.
```
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 des éléments de plusieurs tables.
**Note**
`BatchWriteItem` ne prend pas en charge les demandes `UpdateItem`.
**Example**
Ajoutez 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
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](Expressions.UpdateExpressions.md#Expressions.UpdateExpressions.SET.IncrementAndDecrement).
**Example**
L' AWS CLI exemple suivant augmente la valeur `Price` d'un produit de 5. Dans cet exemple, l’existence de l’élément était connue avant la mise à jour du compteur. Puisque l’opération `UpdateItem` n’est pas idempotente, le `Price` augmente à chaque exécution de ce code.
```
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 DynamoDB `PutItem` (`DeleteItem`,) *sont* inconditionnelles : chaque opération remplace un élément existant qui possè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.
![\[Les utilisateurs Alice et Bob tentent de modifier un élément ayant l’ID 1, démontrant ainsi la nécessité d’écritures conditionnelles.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/update-no-condition.png)
Supposons qu'Alice utilise le AWS CLI pour mettre à jour l'`Price`attribut à 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.
![\[Écriture conditionnelle empêchant la mise à jour de l’utilisateur Bob de remplacer la modification apportée par l’utilisatrice Alice au même élément.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/update-yes-condition.png)
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](Expressions.ConditionExpressions.md).
### 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.
**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é 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` :
+ `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 alloué avec sa table. L’activité de lecture et d’écriture sur un index secondaire local consomme la capacité de débit alloué de la table.
# Utilisation d’expressions dans DynamoDB
Dans Amazon DynamoDB, les *expressions* vous permettent de spécifier les attributs à lire dans un élément, d’écrire des données lorsqu’une condition est remplie, d’indiquer comment mettre à jour un élément, de définir des requêtes et de filtrer les résultats d’une requête.
Ce tableau décrit la grammaire d’expression basique et les types d’expressions disponibles.
| Type d’expression | Description |
| --- | --- |
| Expression de projection | Une expression de projection identifie les attributs que vous souhaitez récupérer d'un élément lorsque vous utilisez des opérations telles que GetItem Query ou Scan. |
| Expression de condition | Une expression de condition détermine quels éléments doivent être modifiés lorsque vous utilisez les DeleteItem opérations PutItem UpdateItem, et. |
| Expression de mise à jour | Une expression de mise à jour indique comment UpdateItem modifier les attributs d'un élément, par exemple en définissant une valeur scalaire ou en supprimant des éléments d'une liste ou d'une carte. |
| Expression de condition clé | Une expression de condition clé détermine les éléments qu’une requête doit lire dans une table ou un index. |
| Expression de filtre | Une expression de filtre détermine les éléments dans les résultats de la requête à vous renvoyer. Tous les autres résultats sont ignorés. |
Pour en savoir plus sur la syntaxe d’expression et chaque type d’expression, consultez les sections suivantes.
**Topics**
+ [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](Expressions.Attributes.md)
+ [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md)
+ [Utilisation de valeurs d’attributs d’expression dans DynamoDB](Expressions.ExpressionAttributeValues.md)
+ [Utilisation d’expressions de projection dans DynamoDB](Expressions.ProjectionExpressions.md)
+ [Utilisation d’expressions de mise à jour dans DynamoDB](Expressions.UpdateExpressions.md)
+ [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md)
+ [Exemple de commande CLI d’expression de condition DynamoDB](Expressions.ConditionExpressions.md)
**Note**
Pour la compatibilité descendante, DynamoDB prend également en charge des paramètres conditionnels qui n’utilisent pas d’expressions. Pour de plus amples informations, veuillez consulter [Paramètres conditionnels hérités de DynamoDB](LegacyConditionalParameters.md).
Les nouvelles applications doivent utiliser des expressions plutôt que des paramètres hérités.
# Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB
Cette section décrit comment référencer des attributs d’élément dans une expression dans Amazon DynamoDB. Vous pouvez utiliser tout attribut, même s’il est profondément imbriqué dans plusieurs listes et mappages.
**Topics**
+ [Attributs de niveau supérieur](#Expressions.Attributes.TopLevelAttributes)
+ [Attributs imbriqués](#Expressions.Attributes.NestedAttributes)
+ [Chemins d’accès à des documents](#Expressions.Attributes.NestedElements.DocumentPathExamples)
**Un exemple d'article : ProductCatalog**
Les exemples sur cette page utilisent l’exemple d’élément suivant dans la table `ProductCatalog`. (Cette table est décrite dans [Exemples de tables et de données à utiliser dans DynamoDB](AppendixSampleTables.md).)
```
{
"Id": 123,
"Title": "Bicycle 123",
"Description": "123 description",
"BicycleType": "Hybrid",
"Brand": "Brand-Company C",
"Price": 500,
"Color": ["Red", "Black"],
"ProductCategory": "Bicycle",
"InStock": true,
"QuantityOnHand": null,
"RelatedItems": [
341,
472,
649
],
"Pictures": {
"FrontView": "http://example.com/products/123_front.jpg",
"RearView": "http://example.com/products/123_rear.jpg",
"SideView": "http://example.com/products/123_left_side.jpg"
},
"ProductReviews": {
"FiveStar": [
"Excellent! Can't recommend it highly enough! Buy it!",
"Do yourself a favor and buy this."
],
"OneStar": [
"Terrible product! Do not buy this."
]
},
"Comment": "This product sells out quickly during the summer",
"Safety.Warning": "Always wear a helmet"
}
```
Notez ce qui suit :
+ La valeur de la clé de partition (`Id`) est `123`. Il n’y a aucune clé de tri.
+ La plupart des attributs ont des types de données scalaires, comme `String`, `Number`, `Boolean` et `Null`.
+ Un attribut (`Color`) est un `String Set`.
+ Les attributs suivants sont des types de données de documents :
+ Une liste de `RelatedItems`. Chaque élément est un `Id` pour un produit concerné.
+ Une carte de `Pictures`. Chaque élément est une brève description d’une image, accompagnée d’une URL pour le fichier image correspondant.
+ Une carte de `ProductReviews`. Chaque élément représente une évaluation et une liste de commentaires correspondant à cette évaluation. À l’origine, ce mappage est renseigné avec des commentaires cinq étoiles et une étoile.
## Attributs de niveau supérieur
Un attribut est dit *de niveau supérieur* lorsqu’il n’est pas imbriqué dans un autre. Dans le cas de l’élément `ProductCatalog`, voici les attributs de niveau supérieur :
+ `Id`
+ `Title`
+ `Description`
+ `BicycleType`
+ `Brand`
+ `Price`
+ `Color`
+ `ProductCategory`
+ `InStock`
+ `QuantityOnHand`
+ `RelatedItems`
+ `Pictures`
+ `ProductReviews`
+ `Comment`
+ `Safety.Warning`
Tous ces attributs de niveau supérieur sont scalaires, à l’exception de `Color` (liste), `RelatedItems` (liste), `Pictures` (mappage) et `ProductReviews` (mappage).
## Attributs imbriqués
Un attribut est dit *imbriqué* lorsqu’il est incorporé dans un autre. Accédez à un attribut imbriqué à l’aide d’*opérateurs de déréférençage* :
+ `[n]` – Pour des éléments de liste
+ `.` (point) – Pour des éléments de mappage
### Accès à des éléments de liste
L’opérateur de déréférençage pour un élément de liste est **[*n*]**, où *n* est le numéro d’élément. Des éléments de liste sont de base zéro, donc [0] représente le premier élément dans la liste, [1] représente le deuxième et ainsi de suite. Voici quelques exemples :
+ `MyList[0]`
+ `AnotherList[12]`
+ `ThisList[5][11]`
L’élément `ThisList[5]` est lui-même une liste imbriquée. Par conséquent, `ThisList[5][11]` fait référence au douzième élément dans cette liste.
Le nombre entre crochets doit être un nombre entier non négatif. Par conséquent, les expressions suivantes ne sont pas valides :
+ `MyList[-1]`
+ `MyList[0.4]`
### Accès à des éléments de mappage
L’opérateur de déréférençage pour un élément de mappage est **.** (un point). Utilisez un point comme séparateur entre des éléments d’un mappage :
+ `MyMap.nestedField`
+ `MyMap.nestedField.deeplyNestedField`
## Chemins d’accès à des documents
Dans une expression, vous indiquez à DynamoDB où trouver un attribut à l’aide d’un *chemin d’accès à un document*. Pour un attribut de niveau supérieur, le chemin d’accès au document est simplement le nom d’attribut. Pour un attribut imbriqué, vous construisez le chemin d’accès au document à l’aide d’opérateurs de déréférençage.
Voici quelques exemples d’expressions de chemins d’accès à des documents. (Consultez l’élément présenté dans [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](#Expressions.Attributes).)
+ Attribut scalaire de niveau supérieur.
`Description`
+ Attribut de liste de niveau supérieur. (Renvoie la liste entière, et non uniquement certains éléments.)
`RelatedItems`
+ Le troisième élément de la liste `RelatedItems`. (N’oubliez pas que les éléments de liste sont de base zéro.)
`RelatedItems[2]`
+ Photo de face du produit.
`Pictures.FrontView`
+ Tous les commentaires cinq étoiles.
`ProductReviews.FiveStar`
+ Le premier des commentaires cinq étoiles.
`ProductReviews.FiveStar[0]`
**Note**
La profondeur maximale pour un chemin d’accès à un document est de 32. Par conséquent, le nombre d’opérateurs de déréférençage dans un chemin d’accès ne peut pas dépasser cette limite.
Vous pouvez utiliser tout nom d’attribut dans le chemin d’accès à un document, à condition qu’il réponde aux exigences suivantes :
+ Le premier caractère est `a-z` ou `A-Z` et/ou `0-9`.
+ Le second caractère (le cas échéant) est `a-z`, `A-Z`.
**Note**
Si un nom d’attribut ne répond pas à cette exigence, vous devez définir un nom d’attribut d’expression comme espace réservé.
Pour de plus amples informations, veuillez consulter [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md).
# Noms d’attributs d’expression (alias) dans DynamoDB
Un *nom d’attribut d’expression* est un alias (ou espace réservé) utilisé dans une expression Amazon DynamoDB à la place d’un nom d’attribut réel. Un nom d’attribut d’expression doit commencer par un signe dièse (`#`) et être suivi d’un ou de plusieurs caractères alphanumériques. Le trait de soulignement (`_`) est également autorisé.
Cette section présente plusieurs cas dans lesquels vous devez utiliser des noms d’attributs d’expression.
**Note**
Les exemples de cette section utilisent le AWS Command Line Interface (AWS CLI).
**Topics**
+ [Mots réservés](#Expressions.ExpressionAttributeNames.ReservedWords)
+ [Noms d’attributs comportant des caractères spéciaux](#Expressions.ExpressionAttributeNames.AttributeNamesContainingSpecialCharacters)
+ [Attributs imbriqués](#Expressions.ExpressionAttributeNames.NestedAttributes)
+ [Référencement répété de noms d’attributs](#Expressions.ExpressionAttributeNames.RepeatingAttributeNames)
## Mots réservés
Dans certains cas, vous pouvez avoir besoin d’écrire une expression comportant un nom d’attribut qui entre en conflit avec un mot réservé DynamoDB. (Pour obtenir la liste complète des mots réservés, consultez [Mots réservés dans DynamoDB](ReservedWords.md).)
Par exemple, l' AWS CLI exemple suivant échouerait car il `COMMENT` s'agit d'un mot réservé.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Comment"
```
Pour contourner cela, vous pouvez remplacer `Comment` par un nom d’attribut d’expression tel que `#c`. Le `#` (signe dièse) est obligatoire et indique qu’il s’agit d’un espace réservé pour un nom d’attribut. L' AWS CLI exemple devrait maintenant ressembler à ce qui suit.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#c" \
--expression-attribute-names '{"#c":"Comment"}'
```
**Note**
Si un nom d’attribut commence par un nombre ou comporte un espace ou un mot réservé, vous *devez* remplacer ce nom d’attribut dans l’expression à l’aide d’un nom d’attribut d’expression.
## Noms d’attributs comportant des caractères spéciaux
Dans une expression, un point (« . ») est interprété comme un caractère de séparation dans un chemin d’accès à un document. Cependant, DynamoDB vous permet également d’utiliser un caractère point et d’autres caractères spéciaux tels qu’un trait d’union (« - ») dans le cadre d’un nom d’attribut. Cela peut être ambigu dans certains cas. À titre d’illustration, supposons que vous souhaitiez récupérer l’attribut `Safety.Warning` d’un élément `ProductCatalog`. (Consultez [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](Expressions.Attributes.md).)
Supposons que vous souhaitiez accéder à `Safety.Warning` à l’aide d’une expression de projection.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Safety.Warning"
```
DynamoDB renvoie un résultat vide au lieu de la chaîne attendue (« `Always wear a helmet` »). En effet, DynamoDB interprète un point dans une expression comme un caractère de séparation dans un chemin d’accès à un document. Dans ce cas, vous devez définir un nom d’attribut d’expression (tel que `#sw`) en remplacement de `Safety.Warning`. Vous pouvez ensuite utiliser l’expression de projection suivante.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#sw" \
--expression-attribute-names '{"#sw":"Safety.Warning"}'
```
DynamoDB renvoie alors le résultat correct.
**Note**
Si un nom d’attribut comporte un point (« . ») ou un trait d’union (« - »), vous*devez* remplacer le nom de cet attribut dans l’expression à l’aide d’un nom d’attribut d’expression.
## Attributs imbriqués
Supposons que vous souhaitiez accéder à l’attribut imbriqué `ProductReviews.OneStar`. Dans un nom d’attribut d’expression, DynamoDB traite un point (« . ») comme un caractère dans un nom d’attribut. Pour référencer l’attribut imbriqué, définissez un nom d’attribut d’expression pour chaque élément dans le chemin d’accès au document :
+ `#pr — ProductReviews`
+ `#1star — OneStar`
Vous pouvez ensuite utiliser `#pr.#1star` pour l’expression de projection.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.#1star" \
--expression-attribute-names '{"#pr":"ProductReviews", "#1star":"OneStar"}'
```
DynamoDB renvoie alors le résultat correct.
## Référencement répété de noms d’attributs
Les noms d’attributs d’expression sont utiles lorsque vous devez référencer le même nom d’attribut à plusieurs reprises. Par exemple, imaginons l’expression suivante pour récupérer certains des commentaires d’un élément `ProductCatalog`.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "ProductReviews.FiveStar, ProductReviews.ThreeStar, ProductReviews.OneStar"
```
Pour la rendre plus concise, vous pouvez remplacer `ProductReviews` par un nom d’attribut d’expression tel que `#pr`. L’expression révisée ressemblerait maintenant à ceci.
+ `#pr.FiveStar, #pr.ThreeStar, #pr.OneStar`
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.FiveStar, #pr.ThreeStar, #pr.OneStar" \
--expression-attribute-names '{"#pr":"ProductReviews"}'
```
Si vous définissez un nom d’attribut d’expression, vous devez l’utiliser systématiquement sur l’ensemble de l’expression. En outre, vous ne pouvez pas ignorer le symbole `#`.
# Utilisation de valeurs d’attributs d’expression dans DynamoDB
Les *valeurs d’attributs d’expression* dans Amazon DynamoDB font office de variables. Elles remplacent les valeurs réelles que vous souhaitez comparer, valeurs que vous ne connaissez peut-être pas avant l’exécution. Une valeur d’attribut d’expression doit commencer par un signe deux-points (`:`) et être suivie d’un ou de plusieurs caractères alphanumériques.
Par exemple, supposons que vous souhaitiez renvoyer tous les éléments de `ProductCatalog` disponibles en `Black` et coûtant au maximum `500`. Vous pouvez utiliser une opération `Scan` avec une expression de filtre, comme dans cet exemple AWS Command Line Interface (AWS CLI).
```
aws dynamodb scan \
--table-name ProductCatalog \
--filter-expression "contains(Color, :c) and Price <= :p" \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":c": { "S": "Black" },
":p": { "N": "500" }
}
```
Si vous définissez une valeur d’attribut d’expression, vous devez l’utiliser systématiquement sur l’ensemble de l’expression. En outre, vous ne pouvez pas ignorer le symbole `:`.
Les valeurs d’attributs d’expression sont utilisées avec des expressions de condition de clé, des expressions de condition, des expressions de mise à jour et des expressions de filtre.
# Utilisation d’expressions de projection dans DynamoDB
Vous lisez des données d’une table à l’aide d’opérations telles que `GetItem`, `Query` ou `Scan`. Par défaut, Amazon DynamoDB renvoie tous les attributs d’élément. Obtenez seulement certains des attributs et non leur totalité à l’aide d’une expression de projection.
Une *expression de projection* est une chaîne qui identifie les attributs souhaités. Pour récupérer un seul attribut, spécifiez son nom. Pour plusieurs attributs, les noms doivent être séparés par des virgules.
Voici des exemples d’expressions de projection basées sur l’élément `ProductCatalog` à partir de [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](Expressions.Attributes.md) :
+ Un seul attribut de niveau supérieur.
`Title `
+ Trois attributs de niveau supérieur. DynamoDB extrait l’ensemble `Color` tout entier.
`Title, Price, Color`
+ Quatre attributs de niveau supérieur. DynamoDB renvoie tout le contenu de `RelatedItems` et `ProductReviews`.
`Title, Description, RelatedItems, ProductReviews`
**Note**
L’expression de projection n’a aucun effet sur la consommation du débit alloué. DynamoDB détermine les unités de capacité consommées en fonction de la taille d’un élément, et non du volume de données renvoyées à une application.
**Mots réservés et caractères spéciaux**
DynamoDB comporte des mots réservés et des caractères spéciaux. DynamoDB vous permet d’utiliser ces mots réservés et ces caractères spéciaux pour les noms, mais nous vous recommandons d’éviter de le faire, car vous devez utiliser des alias pour eux chaque fois que vous utilisez ces noms dans une expression. Pour obtenir la liste complète, consultez [Mots réservés dans DynamoDB](ReservedWords.md).
Vous devez utiliser des noms d’attributs d’expression à la place du nom réel si :
+ le nom d’attribut figure dans la liste des mots réservés dans DynamoDB ;
+ le nom d’attribut ne répond pas à l’exigence que le premier caractère soit `a-z` ou `A-Z` et le second (le cas échéant) soit `a-Z`, `A-Z` ou `0-9` ;
+ le nom d’attribut comporte un signe **\$1** (dièse) ou **:** (deux-points).
L' AWS CLI exemple suivant montre comment utiliser une expression de projection avec une `GetItem` opération. Cette expression de projection récupère un attribut scalaire de niveau supérieur (`Description`), le premier élément d’une liste (`RelatedItems[0]`) et une liste imbriquée dans un mappage (`ProductReviews.FiveStar`).
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '"Id": { "N": "123" } \
--projection-expression "Description, RelatedItems[0], ProductReviews.FiveStar"
```
Le code JSON suivant serait renvoyé pour cet exemple.
```
{
"Item": {
"Description": {
"S": "123 description"
},
"ProductReviews": {
"M": {
"FiveStar": {
"L": [
{
"S": "Excellent! Can't recommend it highly enough! Buy it!"
},
{
"S": "Do yourself a favor and buy this."
}
]
}
}
},
"RelatedItems": {
"L": [
{
"N": "341"
}
]
}
}
}
```
# Utilisation d’expressions de mise à jour dans DynamoDB
L’opération `UpdateItem` met à jour un élément existant ou ajoute un nouvel élément à la table si celui-ci n’existe pas déjà. Vous devez fournir la clé de l’élément que vous souhaitez mettre à jour. Vous devez également fournir une expression de mise à jour, en indiquant les attributs que vous souhaitez modifier et les valeurs que vous souhaitez leur affecter.
Une *expression de mise à jour* spécifie comment l’opération `UpdateItem` doit modifier les attributs d’un élément, par exemple en définissant une valeur scalaire ou en supprimant des éléments d’une liste ou d’un mappage.
Voici un résumé de la syntaxe des expressions de mise à jour :
```
update-expression ::=
[ SET action [, action] ... ]
[ REMOVE action [, action] ...]
[ ADD action [, action] ... ]
[ DELETE action [, action] ...]
```
Une expression de mise à jour se compose d’une ou de plusieurs clauses. Chaque clause commence par un mot clé `SET`, `REMOVE`, `ADD` ou `DELETE`. Vous pouvez inclure l’une de ces clauses dans une expression de mise à jour, dans n’importe quel ordre. Toutefois, chaque mot clé d’action peut n’apparaître qu’une seule fois.
Chaque clause comporte une ou plusieurs actions, séparées par des virgules. Chaque action représente une modification de données.
Les exemples de cette section sont basés sur l’élément `ProductCatalog` présenté dans [Utilisation d’expressions de projection dans DynamoDB](Expressions.ProjectionExpressions.md).
Les rubriques ci-dessous couvrent différents cas d’utilisation de l’action `SET`.
**Topics**
+ [SET – Modification ou ajout d’attributs d’élément](#Expressions.UpdateExpressions.SET)
+ [REMOVE – Suppression d’attributs d’un élément](#Expressions.UpdateExpressions.REMOVE)
+ [ADD – Mise à jour de nombres et d’ensembles](#Expressions.UpdateExpressions.ADD)
+ [DELETE – Suppression d’éléments d’un ensemble](#Expressions.UpdateExpressions.DELETE)
+ [Utilisation de plusieurs expressions de mise à jour](#Expressions.UpdateExpressions.Multiple)
## SET – Modification ou ajout d’attributs d’élément
Ajoutez un ou plusieurs attributs à un élément à l’aide de l’action `SET` dans une expression de mise à jour. Si l’un de ces attributs existe déjà, il est remplacé par les nouvelles valeurs. Si vous souhaitez éviter de remplacer un attribut existant, vous pouvez utiliser l’action `SET` avec la fonction `if_not_exists`. La fonction `if_not_exists` est spécifique à l’action `SET` et utilisable uniquement dans une expression de mise à jour.
Lorsque vous utilisez `SET` pour mettre à jour un élément de la liste, le contenu de cet élément est remplacé par les nouvelles données que vous spécifiez. Si l’élément n’existe pas déjà, `SET` ajoute le nouvel élément à la fin de la liste.
Si vous ajoutez plusieurs éléments dans une seule opération `SET`, les éléments sont triés dans l’ordre par numéro d’élément.
Vous pouvez également effectuer un ajout ou une soustraction à un attribut de type `Number` à l’aide de `SET`. Afin d’effectuer plusieurs actions `SET`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers l'élément.
+ Un **operand**élément peut être un chemin de document vers un élément ou une fonction.
```
set-action ::=
path = value
value ::=
operand
| operand '+' operand
| operand '-' operand
operand ::=
path | function
function ::=
if_not_exists (path, value)
```
Si l’élément ne contient pas d’attribut au chemin d’accès spécifié, la fonction `if_not_exists` prend la valeur `value`. Dans le cas contraire, elle prend la valeur `path`.
L’opération `PutItem` suivante crée un exemple d’élément auquel nous ferons référence dans les exemples.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
Les arguments de la fonction `--item` sont stockés dans le fichier `item.json`. Dans un souci de simplicité, seuls quelques attributs sont utilisés.
```
{
"Id": {"N": "789"},
"ProductCategory": {"S": "Home Improvement"},
"Price": {"N": "52"},
"InStock": {"BOOL": true},
"Brand": {"S": "Acme"}
}
```
**Topics**
+ [Modification d’attributs](#Expressions.UpdateExpressions.SET.ModifyingAttributes)
+ [Ajout de listes et de mappages](#Expressions.UpdateExpressions.SET.AddingListsAndMaps)
+ [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.AddingListElements)
+ [Ajout d’attributs de mappage imbriqués](#Expressions.UpdateExpressions.SET.AddingNestedMapAttributes)
+ [Incrémentation et décrémentation d’attributs numériques](#Expressions.UpdateExpressions.SET.IncrementAndDecrement)
+ [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.UpdatingListElements)
+ [Empêcher le remplacement d’un attribut existant](#Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites)
### Modification d’attributs
**Example**
Mettez à jour les attributs `ProductCategory` et `Price`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET ProductCategory = :c, Price = :p" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":c": { "S": "Hardware" },
":p": { "N": "60" }
}
```
**Note**
Dans l’opération `UpdateItem`, `--return-values ALL_NEW` amène DynamoDB à renvoyer l’élément tel qu’il s’affiche après la mise à jour.
### Ajout de listes et de mappages
**Example**
Ajoutez une nouvelle liste et un nouveau mappage.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":ri": {
"L": [
{ "S": "Hammer" }
]
},
":pr": {
"M": {
"FiveStar": {
"L": [
{ "S": "Best product ever!" }
]
}
}
}
}
```
### Ajout d’éléments à une liste
**Example**
Ajoutez un nouvel attribut à la liste `RelatedItems`. (N’oubliez pas que les éléments de liste sont en base zéro, donc [0] représente le premier élément dans la liste, [1] représente le deuxième et ainsi de suite.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :ri" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":ri": { "S": "Nails" }
}
```
**Note**
Lorsque vous utilisez `SET` pour mettre à jour un élément de la liste, le contenu de cet élément est remplacé par les nouvelles données que vous spécifiez. Si l’élément n’existe pas déjà, `SET` ajoute le nouvel élément à la fin de la liste.
Si vous ajoutez plusieurs éléments dans une seule opération `SET`, les éléments sont triés dans l’ordre par numéro d’élément.
### Ajout d’attributs de mappage imbriqués
**Example**
Ajoutez certains attributs de mappage imbriqués.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
--expression-attribute-names file://names.json \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Les arguments de la fonction `--expression-attribute-names` sont stockés dans le fichier `names.json`.
```
{
"#pr": "ProductReviews",
"#5star": "FiveStar",
"#3star": "ThreeStar"
}
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":r5": { "S": "Very happy with my purchase" },
":r3": {
"L": [
{ "S": "Just OK - not that great" }
]
}
}
```
**Important**
Vous ne pouvez pas mettre à jour les attributs de carte imbriqués si la carte parent n'existe pas. Si vous tentez de mettre à jour un attribut imbriqué (par exemple,`ProductReviews.FiveStar`) alors que la carte parent (`ProductReviews`) n'existe pas, DynamoDB renvoie `ValidationException` un avec le *message « Le chemin du document fourni dans l'expression de mise à jour n'est pas valide pour la mise à jour* ».
Lorsque vous créez des éléments dont les attributs de carte imbriqués seront mis à jour ultérieurement, initialisez des cartes vides pour les attributs parents. Par exemple :
```
{
"Id": {"N": "789"},
"ProductReviews": {"M": {}},
"Metadata": {"M": {}}
}
```
Cela vous permet de mettre à jour les attributs imbriqués `ProductReviews.FiveStar` sans erreur.
### Incrémentation et décrémentation d’attributs numériques
Vous pouvez effectuer un ajout ou une soustraction à un attribut numérique existant. Pour ce faire, utilisez les opérateurs `+` (plus) et `-` (moins).
**Example**
Réduisez l’attribut `Price` d’un élément.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
Augmentez l’attribut `Price` à l’aide de l’opérateur `+` dans l’expression de mise à jour.
### Ajout d’éléments à une liste
Vous pouvez ajouter des éléments à la fin d’une liste. Pour ce faire, utilisez `SET` avec la fonction `list_append`. (Le nom de fonction respecte la casse.) La fonction `list_append` est spécifique à l’action `SET` et utilisable uniquement dans une expression de mise à jour. La syntaxe est la suivante.
+ `list_append (list1, list2)`
La fonction prend deux listes en entrée et ajoute tous les éléments de `list2` à ` list1`.
**Example**
Dans [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.AddingListElements), vous créez la liste `RelatedItems` et la renseignez avec deux éléments : `Hammer` et `Nails`. Vous allez maintenant ajouter deux autres éléments à la fin de `RelatedItems`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(#ri, :vals)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":vals": {
"L": [
{ "S": "Screwdriver" },
{"S": "Hacksaw" }
]
}
}
```
Enfin, vous allez ajouter un autre élément au *début* de `RelatedItems`. Pour ce faire, permutez l’ordre des éléments `list_append`. (N’oubliez pas que la fonction `list_append` prend deux listes en entrée, puis ajoute la seconde liste à la première.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(:vals, #ri)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
--return-values ALL_NEW
```
L’attribut `RelatedItems` résultant comporte maintenant cinq éléments, dans l’ordre suivant : `Chisel`, `Hammer`, `Nails`, `Screwdriver`, `Hacksaw`.
### Empêcher le remplacement d’un attribut existant
**Example**
Définissez l’attribut `Price` d’un élément, mais seulement si l’élément ne possède pas déjà un attribut `Price`. (Si `Price` existe déjà, il ne se passe rien.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = if_not_exists(Price, :p)" \
--expression-attribute-values '{":p": {"N": "100"}}' \
--return-values ALL_NEW
```
## REMOVE – Suppression d’attributs d’un élément
Supprimez un ou plusieurs attributs d’un élément dans Amazon DynamoDB à l’aide de l’action `REMOVE` dans une expression de mise à jour. Afin d’effectuer plusieurs actions `REMOVE`, séparez-les par des virgules.
Voici un résumé de la syntaxe pour `REMOVE` dans une expression de mise à jour. Le seul opérande est le chemin d’accès au document pour l’attribut que vous souhaitez supprimer.
```
remove-action ::=
path
```
**Example**
Supprimez des attributs d’un élément. (Si les attributs n’existent pas, il ne se passe rien.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE Brand, InStock, QuantityOnHand" \
--return-values ALL_NEW
```
### Suppression d’éléments d’une liste
Vous pouvez supprimer des éléments d’une liste à l’aide de `REMOVE`.
**Example**
Dans [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.UpdatingListElements), vous avez modifié un attribut de liste (`RelatedItems`) de sorte qu’il comporte les cinq éléments suivants :
+ `[0]`—`Chisel`
+ `[1]`—`Hammer`
+ `[2]`—`Nails`
+ `[3]`—`Screwdriver`
+ `[4]`—`Hacksaw`
L'exemple suivant AWS Command Line Interface (AWS CLI) supprime `Hammer` et `Nails` de la liste.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
--return-values ALL_NEW
```
Après la suppression de `Hammer` et `Nails`, les éléments restants sont déplacés. La liste comporte désormais les éléments suivants :
+ `[0]`—`Chisel`
+ `[1]`—`Screwdriver`
+ `[2]`—`Hacksaw`
## ADD – Mise à jour de nombres et d’ensembles
**Note**
En général, nous recommandons d'utiliser `SET` plutôt que de `ADD` garantir des opérations idempotentes.
Ajoutez un nouvel attribut et ses valeurs à un élément à l’aide de l’action `ADD` dans une expression de mise à jour.
Si l’attribut existe déjà, le comportement d’`ADD` dépend du type de données de l’attribut :
+ Si l’attribut est un nombre et que la valeur que vous ajoutez est également un nombre, la valeur est ajoutée mathématiquement à l’attribut existant. (Si la valeur est un nombre négatif, elle est soustraite de l’attribut existant.)
+ Si l’attribut est un ensemble et que la valeur que vous ajoutez est également un ensemble, la valeur est ajoutée à l’ensemble existant.
**Note**
L’action `ADD` prend uniquement en charge les données de type nombre et ensemble.
Afin d’effectuer plusieurs actions `ADD`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers un attribut. L’attribut doit être un `Number` ou un type de données ensemble.
+ L'*value*élément est un nombre que vous souhaitez ajouter à l'attribut (pour les types de `Number` données) ou un ensemble à ajouter à l'attribut (pour les types d'ensembles).
```
add-action ::=
path value
```
Les rubriques ci-dessous couvrent différents cas d’utilisation de l’action `ADD`.
**Topics**
+ [Ajout d’un nombre](#Expressions.UpdateExpressions.ADD.Number)
+ [Ajout d’éléments à un ensemble](#Expressions.UpdateExpressions.ADD.Set)
### Ajout d’un nombre
Supposons que l’attribut `QuantityOnHand` n’existe pas. L' AWS CLI exemple suivant définit `QuantityOnHand` la valeur 5.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD QuantityOnHand :q" \
--expression-attribute-values '{":q": {"N": "5"}}' \
--return-values ALL_NEW
```
Maintenant que `QuantityOnHand` existe, vous pouvez réexécuter l’exemple pour incrémenter `QuantityOnHand` de 5 chaque fois.
### Ajout d’éléments à un ensemble
Supposons que l’attribut `Color` n’existe pas. L’exemple AWS CLI suivant définit `Color` sur un ensemble de chaîne avec deux éléments.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
--return-values ALL_NEW
```
Maintenant que `Color` existe, vous pouvez lui ajouter de nouveaux éléments.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
--return-values ALL_NEW
```
## DELETE – Suppression d’éléments d’un ensemble
**Important**
L’action `DELETE` prend uniquement en charge les types de données `Set`.
Supprimez un ou plusieurs éléments d’un ensemble à l’aide de l’action `DELETE` dans une expression de mise à jour. Afin d’effectuer plusieurs actions `DELETE`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers un attribut. L’attribut doit être un type de données ensemble.
+ *subset*Il s'agit d'un ou de plusieurs éléments que vous souhaitez supprimer*path*. Vous devez le spécifier *subset* en tant que type d'ensemble.
```
delete-action ::=
path subset
```
**Example**
Dans [Ajout d’éléments à un ensemble](#Expressions.UpdateExpressions.ADD.Set), vous créez l’ensemble de chaînes `Color`. Cet exemple supprime certains des éléments de cet ensemble.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "DELETE Color :p" \
--expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
--return-values ALL_NEW
```
## Utilisation de plusieurs expressions de mise à jour
Vous pouvez utiliser plusieurs actions dans une seule expression de mise à jour. Toutes les références d'attributs sont résolues en fonction de l'état de l'élément avant que l'une des actions ne soit appliquée.
**Example**
Étant donné un élément`{"id": "1", "a": 1, "b": 2, "c": 3}`, l'expression suivante supprime `a` et déplace les valeurs de `b` et `c` :
```
aws dynamodb update-item \
--table-name test \
--key '{"id":{"S":"1"}}' \
--update-expression "REMOVE a SET b = a, c = b" \
--return-values ALL_NEW
```
Le résultat est`{"id": "1", "b": 1, "c": 2}`. Même si elle `a` est supprimée et `b` réaffectée dans la même expression, les deux références retrouvent leurs valeurs d'origine.
**Example**
Vous pouvez modifier la valeur d’un attribut et supprimer complètement un autre attribut à l’aide d’une action SET et d’une action REMOVE dans une seule instruction. Cette opération réduirait la valeur de l’attribut `Price` à 15 tout en supprimant l’attribut `InStock` de l’élément.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p REMOVE InStock" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
**Example**
Vous pouvez ajouter des éléments à une liste tout en modifiant la valeur d’un autre attribut à l’aide de deux actions SET dans une seule instruction. Cette opération ajouterait « Nails » à l’attribut de liste `RelatedItems` et définirait également la valeur de l’attribut `Price` sur 21.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
--expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}' \
--return-values ALL_NEW
```
# Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB
Manipulez les données d’une table DynamoDB à l’aide des opérations `PutItem`, `UpdateItem` et `DeleteItem`. Pour ces opérations de manipulation de données, vous pouvez préciser une expression de condition afin de déterminer les éléments à modifier. Si l’expression de condition a la valeur true, l’opération aboutit. Sinon, l’opération échoue.
Cette section traite des fonctions et mots clés intégrés pour l’écriture des expressions de filtre et de condition dans Amazon DynamoDB. Pour en savoir plus sur les fonctions et la programmation avec DynamoDB, consultez [Programmation avec DynamoDB et le AWS SDKs](Programming.md) et le [guide de référence de l’API DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
**Topics**
+ [Syntaxe des expressions de filtre et de condition](#Expressions.OperatorsAndFunctions.Syntax)
+ [Comparaisons](#Expressions.OperatorsAndFunctions.Comparators)
+ [Fonctions](#Expressions.OperatorsAndFunctions.Functions)
+ [Évaluations logiques](#Expressions.OperatorsAndFunctions.LogicalEvaluations)
+ [Parenthèses](#Expressions.OperatorsAndFunctions.Parentheses)
+ [Priorité des conditions](#Expressions.OperatorsAndFunctions.Precedence)
## Syntaxe des expressions de filtre et de condition
Dans le résumé de syntaxe suivant, un *operand* peut être le suivant :
+ Nom d’attribut de niveau supérieur, par exemple `Id`, `Title`, `Description` ou `ProductCategory`
+ Chemin d’accès au document référençant un attribut imbriqué
```
condition-expression ::=
operand comparator operand
| operand BETWEEN operand AND operand
| operand IN ( operand (',' operand (, ...) ))
| function
| condition AND condition
| condition OR condition
| NOT condition
| ( condition )
comparator ::=
=
| <>
| <
| <=
| >
| >=
function ::=
attribute_exists (path)
| attribute_not_exists (path)
| attribute_type (path, type)
| begins_with (path, substr)
| contains (path, operand)
| size (path)
```
## Comparaisons
Comparez un opérande à une valeur unique à l’aide de ces comparateurs :
+ `a = b`— Vrai s'*a*il est égal à*b*.
+ `a <> b`— Vrai s'il n'*a*est pas égal à*b*.
+ `a < b`— C'est vrai si *a* c'est inférieur à*b*.
+ `a <= b`— Vrai s'*a*il est inférieur ou égal à*b*.
+ `a > b`— Vrai si la valeur *a* est supérieure à*b*.
+ `a >= b`— Vrai s'*a*il est supérieur ou égal à*b*.
Comparez un opérande à une plage de valeurs ou une liste énumérée de valeurs à l’aide des mots clés `BETWEEN` et `IN` :
+ `a BETWEEN b AND c`— Vrai s'*a*il est supérieur ou égal à*b*, et inférieur ou égal à*c*.
+ `a IN (b, c, d) `— Vrai s'il *a* est égal à n'importe quelle valeur de la liste, par exemple, n'importe laquelle de *b**c*, ou. *d* La liste peut comporter jusqu’à 100 valeurs séparées par des virgules.
## Fonctions
Déterminez si un attribut existe dans un élément ou évaluez la valeur d’un attribut à l’aide des fonctions suivantes. Ces noms de fonction respectent la casse. Pour un attribut imbriqué, vous devez fournir le chemin d’accès au document complet.
****
| Fonction | Description |
| --- | --- |
| `attribute_exists (path)` | True si l’élément comporte l’attribut spécifié par `path`. Exemple : Vérifier si un élément de la table `Product` a une image de vue de côté. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_not_exists (path)` | True si l’attribut spécifié par `path` n’existe pas dans l’élément. Exemple : Vérifier si un élément possède un attribut `Manufacturer`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_type (path, type)` | True si l’attribut à l’emplacement spécifié est d’un type de données particulier. Le paramètre `type` doit avoir l’une des valeurs suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Vous devez utiliser une valeur d’attribut d’expression pour le paramètre `type`. Exemple : Vérifier si l’attribut `QuantityOnHand` est de type List (liste). Dans cet exemple, `:v_sub` est un espace réservé pour la chaîne `L`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Vous devez utiliser une valeur d’attribut d’expression pour le paramètre `type`. |
| `begins_with (path, substr)` | True si l’attribut spécifié par `path` commence par une sous-chaîne particulière. Exemple : Vérifier si les tout premiers caractères de l’URL de l’image de vue avant sont `http://`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `http://`. |
| `contains (path, operand)` | True si l’attribut spécifié par `path` est l’un des attributs suivants : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si l’attribut spécifié par `path` est de type `String`, `operand` doit être de type `String`. Si l’attribut spécifié par `path` est de type `Set`, l’`operand` doit être le type d’élément de l’ensemble. Le chemin d’accès et l’opérande doivent être distincts. Autrement dit, `contains (a, a)` renvoie une erreur. Exemple : Vérifier si l’attribut `Brand` comporte la sous-chaîne `Company`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `Company`. Exemple : Vérifier si le produit est disponible en rouge. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `Red`. |
| `size (path)` | Renvoie un nombre qui représente la taille d’un attribut. Voici les types de données valides à utiliser avec `size`. Si l’attribut est de type `String`, `size` renvoie la longueur de la chaîne. Exemple : Vérifier si la longueur de la chaîne `Brand` est inférieure ou égale à 20 caractères. La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `20`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si l’attribut est de type `Binary`, `size` renvoie le nombre d’octets de la valeur d’attribut. Exemple : supposez que l’élément `ProductCatalog` comporte un binary attribute nommé `VideoClip` qui comporte une courte vidéo du produit utilisé. L’expression suivante vérifie si `VideoClip` dépasse 64 000 octets. La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `64000`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si l’attribut est un type de données `Set`, `size` renvoie le nombre d’éléments dans l’ensemble. Exemple : Vérifier si le produit est disponible dans plusieurs couleurs. La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `1`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si l’attribut est de type `List` ou `Map`, `size` renvoie le nombre d’éléments enfants. Exemple : Vérifier si le nombre de révisions `OneStar` a dépassé un certain seuil. La valeur d’attribut d’expression `:v_sub` est un espace réservé pour `3`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
## Évaluations logiques
Effectuez les évaluations logiques à l’aide des mots clés `AND`, `OR` et `NOT`. Dans la liste suivante, *a* et *b* représentez les conditions à évaluer.
+ `a AND b`— C'est vrai si *a* les deux *b* sont vrais.
+ `a OR b`— Vrai si l'un *a* ou l'autre *b* (ou les deux) sont vrais.
+ `NOT a`— Vrai si *a* c'est faux. Faux si *a* c'est vrai.
Voici un exemple de code avec AND dans une opération.
`dynamodb-local (*)> select * from exprtest where a > 3 and a < 5;`
## Parenthèses
Modifiez la priorité d’une évaluation logique à l’aide de parenthèses. Supposons, par exemple, que les conditions *b* 1 *a* et 2 soient vraies et que cette condition *c* soit fausse. L’expression suivante a la valeur true :
+ `a OR b AND c`
Toutefois, si vous placez une condition entre parenthèses, elle est évaluée en premier. Par exemple, l’expression suivante a la valeur false :
+ `(a OR b) AND c`
**Note**
Vous pouvez imbriquer des parenthèses dans une expression. Les parenthèses les plus intérieures sont évaluées en premier.
Voici un exemple de code avec des parenthèses dans une évaluation logique.
`dynamodb-local (*)> select * from exprtest where attribute_type(b, string) or ( a = 5 and c = “coffee”);`
## Priorité des conditions
DynamoDB évalue les conditions de gauche à droite à l’aide des règles de priorité suivantes :
+ `= <> < <= > >=`
+ `IN`
+ `BETWEEN`
+ `attribute_exists attribute_not_exists begins_with contains`
+ Parenthèses
+ `NOT`
+ `AND`
+ `OR`
# Exemple de commande CLI d’expression de condition DynamoDB
Voici quelques AWS Command Line Interface (AWS CLI) exemples d'utilisation d'expressions de condition. Ces exemples sont basés sur la table `ProductCatalog`, qui a été présentée dans [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](Expressions.Attributes.md). La clé de partition de cette table est `Id` ; il n’y a aucune clé de tri. L’opération `PutItem` suivante crée un exemple d’élément `ProductCatalog` auquel nous ferons référence dans les exemples.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
Les arguments de la fonction `--item` sont stockés dans le fichier `item.json`. Dans un souci de simplicité, seuls quelques attributs sont utilisés.
```
{
"Id": {"N": "456" },
"ProductCategory": {"S": "Sporting Goods" },
"Price": {"N": "650" }
}
```
**Topics**
+ [Insertion conditionnelle](#Expressions.ConditionExpressions.PreventingOverwrites)
+ [Suppressions conditionnelles](#Expressions.ConditionExpressions.AdvancedComparisons)
+ [Mises à jour conditionnelles](#Expressions.ConditionExpressions.SimpleComparisons)
+ [Exemples d’expressions conditionnelles](#Expressions.ConditionExpressions.ConditionalExamples)
## Insertion conditionnelle
L’opération `PutItem` remplace un élément avec la même clé primaire (le cas échéant). Vous pouvez éviter cela à l’aide d’une expression de condition. Elle permet la poursuite de l’écriture seulement si l’élément en question ne possède pas déjà la même clé primaire.
L’exemple suivant vérifie si la clé primaire existe dans la table à l’aide de la fonction `attribute_not_exists()` avant de tenter l’opération d’écriture.
**Note**
Si votre clé primaire comprend à la fois une clé de partition (pk) et une clé de tri (sk), le paramètre vérifie si `attribute_not_exists(pk)` ET `attribute_not_exists(sk)` prennent la valeur true ou false avant de tenter l’opération d’écriture.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json \
--condition-expression "attribute_not_exists(Id)"
```
Si l’expression de condition prend la valeur false, DynamoDB renvoie le message d’erreur suivant : The conditional request failed (Échec de la demande conditionnelle).
**Note**
Pour en savoir plus sur `attribute_not_exists` et d’autres fonctions, consultez [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md).
## Suppressions conditionnelles
Effectuez une suppression conditionnelle à l’aide d’une opération `DeleteItem` avec une expression de condition. L’expression de condition doit avoir la valeur true afin que l’opération aboutisse. Dans le cas contraire, l’opération échoue.
Tenez compte de l’élément défini ci-dessus.
Supposons maintenant que vous souhaitiez supprimer l’élément, mais uniquement dans les conditions suivantes :
+ L’attribut `ProductCategory` est soit « Sporting Goods » (Matériels de sport), soit « Gardening Supplies » (Articles de jardinerie).
+ La valeur de l’attribut `Price` est comprise entre 500 et 600.
L’exemple suivant tente de supprimer l’élément.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"456"}}' \
--condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":cat1": {"S": "Sporting Goods"},
":cat2": {"S": "Gardening Supplies"},
":lo": {"N": "500"},
":hi": {"N": "600"}
}
```
**Note**
Dans l’expression de condition, le signe `:` (deux points) indique une *valeur d’attribut d’expression*, c’est-à-dire un espace réservé pour une valeur réelle. Pour de plus amples informations, veuillez consulter [Utilisation de valeurs d’attributs d’expression dans DynamoDB](Expressions.ExpressionAttributeValues.md).
Pour en savoir plus sur `IN`, `AND` et d’autres mots clés, consultez [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md).
Dans cet exemple, la comparaison `ProductCategory` a la valeur true, mais la comparaison `Price` a la valeur false. Par conséquent, l’expression de condition prend la valeur false et l’opération `DeleteItem` échoue.
## Mises à jour conditionnelles
Effectuez une mise à jour conditionnelle à l’aide d’une opération `UpdateItem` avec une expression de condition. L’expression de condition doit avoir la valeur true afin que l’opération aboutisse. Dans le cas contraire, l’opération échoue.
**Note**
`UpdateItem` prend également en charge les *expressions de mise à jour*, dans lesquelles vous spécifiez les modifications à apporter à un élément. Pour de plus amples informations, veuillez consulter [Utilisation d’expressions de mise à jour dans DynamoDB](Expressions.UpdateExpressions.md).
Supposons que vous commenciez avec l’élément défini ci-dessus.
L’exemple suivant effectue une opération `UpdateItem`. Elle tente de réduire la valeur de l’attribut `Price` d’un produit de 75, mais l’expression de condition empêche la mise à jour si la valeur actuelle de l’attribut `Price` est inférieure à 500.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--update-expression "SET Price = Price - :discount" \
--condition-expression "Price > :limit" \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":discount": { "N": "75"},
":limit": {"N": "500"}
}
```
Si la valeur de départ de l’attribut `Price` est 650, l’opération `UpdateItem` réduit la valeur de l’attribut `Price` à 575. Si vous réexécutez l’opération `UpdateItem`, la valeur de l’attribut `Price` est réduite à 500. Si vous l’exécutez une troisième fois, l’expression de condition prend la valeur false et l’opération de mise à jour échoue.
**Note**
Dans l’expression de condition, le signe `:` (deux points) indique une *valeur d’attribut d’expression*, c’est-à-dire un espace réservé pour une valeur réelle. Pour de plus amples informations, veuillez consulter [Utilisation de valeurs d’attributs d’expression dans DynamoDB](Expressions.ExpressionAttributeValues.md).
Pour en savoir plus sur « *>* » et d’autres opérateurs, consultez [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md).
## Exemples d’expressions conditionnelles
Pour en savoir plus sur les fonctions utilisées dans les exemples suivants, consultez [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md). Pour en savoir plus sur la spécification de différents types d’attributs dans une expression, consultez [Référencement d’attributs d’élément lors de l’utilisation d’expressions dans DynamoDB](Expressions.Attributes.md).
### Vérification des attributs d’un élément
Vous pouvez vérifier l’existence (ou la non-existence) d’un attribut. Si l’expression de condition a la valeur true, l’opération aboutit. Dans le cas contraire, l’opération échoue.
L’exemple suivant supprime un produit seulement s’il ne possède pas d’attribut `Price` à l’aide de `attribute_not_exists`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_not_exists(Price)"
```
DynamoDB fournit également une fonction `attribute_exists`. L’exemple suivant supprime un produit seulement si les commentaires le concernant sont négatifs.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_exists(ProductReviews.OneStar)"
```
### Vérification du type d’attribut
Vous pouvez vérifier le type de données d’une valeur d’attribut à l’aide de la fonction `attribute_type`. Si l’expression de condition a la valeur true, l’opération aboutit. Dans le cas contraire, l’opération échoue.
L’exemple suivant supprime un produit seulement s’il possède un attribut `Color` de type String Set à l’aide de `attribute_type`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_type(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Les arguments pour `--expression-attribute-values` sont stockés dans le fichier expression-attribute-values .json.
```
{
":v_sub":{"S":"SS"}
}
```
### Vérification de la valeur de début de la chaîne
Vous pouvez vérifier si une valeur d’attribut String commence par une sous-chaîne spécifique à l’aide de la fonction `begins_with`. Si l’expression de condition a la valeur true, l’opération aboutit. Dans le cas contraire, l’opération échoue.
L’exemple suivant supprime un produit seulement si l’élément `FrontView` de la carte `Pictures` commence par une valeur spécifique à l’aide de `begins_with`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "begins_with(Pictures.FrontView, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Les arguments pour `--expression-attribute-values` sont stockés dans le fichier expression-attribute-values .json.
```
{
":v_sub":{"S":"http://"}
}
```
### Recherche d’un élément dans un ensemble
Vous pouvez rechercher un élément dans un ensemble ou rechercher une sous-chaîne dans une chaîne à l’aide de la fonction `contains`. Si l’expression de condition a la valeur true, l’opération aboutit. Dans le cas contraire, l’opération échoue.
L’exemple suivant supprime un produit seulement si l’attribut de type String Set `Color` comporte un élément avec une valeur spécifique à l’aide de `contains`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "contains(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Les arguments pour `--expression-attribute-values` sont stockés dans le fichier expression-attribute-values .json.
```
{
":v_sub":{"S":"Red"}
}
```
### Vérification de la taille d’une valeur d’attribut
Vous pouvez vérifier la taille d’une valeur d’attribut à l’aide de la fonction `size`. Si l’expression de condition a la valeur true, l’opération aboutit. Dans le cas contraire, l’opération échoue.
L’exemple suivant supprime un produit seulement si la taille du binary attribute `VideoClip` est supérieure à `64000` octets à l’aide de `size`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "size(VideoClip) > :v_sub" \
--expression-attribute-values file://expression-attribute-values.json
```
Les arguments pour `--expression-attribute-values` sont stockés dans le fichier expression-attribute-values .json.
```
{
":v_sub":{"N":"64000"}
}
```
# Utilisation de la durée de vie (TTL) dans DynamoDB
La durée de vie (TTL) de DynamoDB est une méthode économique pour supprimer les éléments qui ne sont plus pertinents. Elle vous permet de définir un horodatage d’expiration par élément pour indiquer quand cet élément n’est plus nécessaire. DynamoDB supprime automatiquement les éléments ayant expiré quelques jours après leur date d’expiration, sans consommer de débit d’écriture.
Pour utiliser la TTL, activez-la d’abord sur une table, puis définissez un attribut spécifique pour stocker l’horodatage d’expiration de la TTL. L'horodatage doit être stocké sous la forme d'un type de données [numérique](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes) au [format Epoch Time Unix](https://en.wikipedia.org/wiki/Unix_time) avec une granularité en secondes. Les éléments dont l'attribut TTL n'est pas de type numérique sont ignorés par le processus TTL. Chaque fois qu’un élément est créé ou mis à jour, vous pouvez calculer le délai d’expiration et l’enregistrer dans l’attribut TTL.
Les éléments dont les attributs TTL sont valides et ayant expiré peuvent être supprimés par le système à tout moment, généralement quelques jours après leur expiration. Vous pouvez à tout moment mettre à jour les éléments ayant expiré qui sont en attente de suppression, notamment en modifiant ou en supprimant leurs attributs TTL. Lors de la mise à jour d’un élément ayant expiré, nous vous recommandons d’utiliser une expression conditionnelle pour vous assurer que l’élément n’a pas été supprimé ultérieurement. Utilisez des expressions de filtre pour supprimer les éléments ayant expiré des résultats [Scan](Scan.md#Scan.FilterExpression) et [Query](Query.FilterExpression.md).
Les éléments supprimés fonctionnent de la même manière que ceux supprimés par le biais d’opérations de suppression classiques. Une fois supprimés, les éléments sont placés dans DynamoDB Streams sous forme de suppression de service au lieu d’être supprimés par l’utilisateur, et sont supprimés des index secondaires locaux et globaux comme avec les autres opérations de suppression.
Si vous utilisez des [tables globales version 2019.11.21 (actuelle)](GlobalTables.md) et que vous utilisez également la fonctionnalité TTL, DynamoDB réplique les suppressions par TTL sur toutes les tables de réplica. La suppression par TTL initiale ne consomme pas d’unités de capacité d’écriture (WCU) dans la région dans laquelle l’expiration de la TTL a lieu. Toutefois, la suppression par TTL répliquée dans les tables de réplica consomme une unité de capacité d’écriture répliquée lorsque vous utilisez la capacité provisionnée ou une unité d’écriture répliquée lorsque vous utilisez le mode de capacité à la demande, dans chacune des régions de réplica, et des frais s’appliquent.
Pour plus d’informations sur TTL, veuillez consulter les rubriques suivantes :
**Topics**
+ [Activation de la durée de vie (TTL) dans DynamoDB](time-to-live-ttl-how-to.md)
+ [Calcul de la durée de vie (TTL) dans DynamoDB](time-to-live-ttl-before-you-start.md)
+ [Utilisation des éléments ayant expiré et de la durée de vie (TTL)](ttl-expired-items.md)
# Activation de la durée de vie (TTL) dans DynamoDB
**Note**
Pour faciliter le débogage et la vérification de la fonctionnalité TTL, les valeurs fournies pour la TTL de l’élément sont journalisées en texte brut dans les journaux de diagnostic DynamoDB.
Vous pouvez activer le TTL dans la console Amazon DynamoDB, le () AWS Command Line Interface , ou en utilisant AWS CLI le [Amazon DynamoDB API Reference avec n'importe lequel des supposés](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/). AWS SDKs L’activation de la durée de vie (TTL) sur toutes les partitions prend environ une heure.
## Activer DynamoDB TTL à l'aide de la console AWS
1. Connectez-vous à la console DynamoDB AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Choisissez **Tables**, puis choisissez la table à modifier.
1. Dans l’onglet **Paramètres supplémentaires**, dans la section **Durée de vie (TTL)**, choisissez **Activer**.
1. Lorsque vous activez TTL sur une table, vous devez identifier un nom d’attribut spécifique que le service DynamoDB recherchera pour déterminer si un élément peut faire l’objet d’une expiration. Le nom de l’attribut TTL, illustré ci-dessous, distingue les majuscules et minuscules et doit correspondre à l’attribut défini dans vos opérations de lecture et d’écriture. En cas de non-concordance, les éléments ayant expiré ne seront pas supprimés. Pour renommer l’attribut TTL, vous devez le désactiver, puis le réactiver avec le nouveau nom. La TTL continue à traiter les suppressions pendant environ 30 minutes après sa désactivation. Elle doit être reconfigurée sur les tables restaurées.
![\[Nom d’attribut TTL (distinguant majuscules et minuscules) utilisé par DynamoDB pour déterminer si un élément doit expirer.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/EnableTTL-Settings.png)
1. (Facultatif) Vous pouvez effectuer un test en simulant la date et l’heure de l’expiration et en faisant correspondre quelques éléments. Cela vous fournit un exemple de liste d’éléments et confirme qu’il existe des éléments contenant le nom d’attribut TTL fourni avec la date d’expiration.
Une fois que la TTL est activée, l’attribut TTL est marqué **TTL** lorsque vous affichez les éléments dans la console DynamoDB. Vous pouvez afficher la date et l’heure d’expiration d’un élément en faisant passer votre souris au-dessus de l’attribut.
## Activation de la TTL DynamoDB à l’aide de l’API
------
#### [ Python ]
Vous pouvez activer le TTL avec du code à l'aide de l'[UpdateTimeToLive](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/update_time_to_live.html)opération.
```
import boto3
def enable_ttl(table_name, ttl_attribute_name):
"""
Enables TTL on DynamoDB table for a given attribute name
on success, returns a status code of 200
on error, throws an exception
:param table_name: Name of the DynamoDB table
:param ttl_attribute_name: The name of the TTL attribute being provided to the table.
"""
try:
dynamodb = boto3.client('dynamodb')
# Enable TTL on an existing DynamoDB table
response = dynamodb.update_time_to_live(
TableName=table_name,
TimeToLiveSpecification={
'Enabled': True,
'AttributeName': ttl_attribute_name
}
)
# In the returned response, check for a successful status code.
if response['ResponseMetadata']['HTTPStatusCode'] == 200:
print("TTL has been enabled successfully.")
else:
print(f"Failed to enable TTL, status code {response['ResponseMetadata']['HTTPStatusCode']}")
except Exception as ex:
print("Couldn't enable TTL in table %s. Here's why: %s" % (table_name, ex))
raise
# your values
enable_ttl('your-table-name', 'expirationDate')
```
Vous pouvez confirmer que le TTL est activé à l'aide de l'[DescribeTimeToLive](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/describe_time_to_live.html)opération, qui décrit l'état du TTL sur une table. L’état `TimeToLive` est `ENABLED` ou `DISABLED`.
```
# create a DynamoDB client
dynamodb = boto3.client('dynamodb')
# set the table name
table_name = 'YourTable'
# describe TTL
response = dynamodb.describe_time_to_live(TableName=table_name)
```
------
#### [ JavaScript ]
Vous pouvez activer le TTL avec du code à l'aide de l'[UpdateTimeToLiveCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/Class/UpdateTimeToLiveCommand/)opération.
```
import { DynamoDBClient, UpdateTimeToLiveCommand } from "@aws-sdk/client-dynamodb";
const enableTTL = async (tableName, ttlAttribute) => {
const client = new DynamoDBClient({});
const params = {
TableName: tableName,
TimeToLiveSpecification: {
Enabled: true,
AttributeName: ttlAttribute
}
};
try {
const response = await client.send(new UpdateTimeToLiveCommand(params));
if (response.$metadata.httpStatusCode === 200) {
console.log(`TTL enabled successfully for table ${tableName}, using attribute name ${ttlAttribute}.`);
} else {
console.log(`Failed to enable TTL for table ${tableName}, response object: ${response}`);
}
return response;
} catch (e) {
console.error(`Error enabling TTL: ${e}`);
throw e;
}
};
// call with your own values
enableTTL('ExampleTable', 'exampleTtlAttribute');
```
------
## Activez Time to Live à l'aide du AWS CLI
1. Active TTL sur la table `TTLExample`.
```
aws dynamodb update-time-to-live --table-name TTLExample --time-to-live-specification "Enabled=true, AttributeName=ttl"
```
1. Décrit TTL sur la table `TTLExample`.
```
aws dynamodb describe-time-to-live --table-name TTLExample
{
"TimeToLiveDescription": {
"AttributeName": "ttl",
"TimeToLiveStatus": "ENABLED"
}
}
```
1. Ajoutez un élément à la table `TTLExample` avec l’attribut de TTL défini à l’aide du shell BASH et de l’ AWS CLI.
```
EXP=`date -d '+5 days' +%s`
aws dynamodb put-item --table-name "TTLExample" --item '{"id": {"N": "1"}, "ttl": {"N": "'$EXP'"}}'
```
Cet exemple démarre par la date actuelle à laquelle cinq jours sont ajoutés pour créer une date d’expiration. Il a ensuite converti l’heure d’expiration en heure au format epoch pour ajouter en dernier lieu un élément à la table « `TTLExample` ».
**Note**
Pour définir des valeurs d’expiration pour TTL, l’une des méthodes à votre disposition consiste à calculer le nombre de secondes à ajouter à l’heure d’expiration. Par exemple, 5 jours équivalent à 432 000 secondes. Toutefois, il est souvent préférable de commencer par une date et de définir le reste en fonction de celle-ci.
Il est relativement simple d’obtenir l’heure actuelle au format epoch, comme dans l’exemple suivant.
+ Terminal Linux : `date +%s`
+ Python: `import time; int(time.time())`
+ Java: `System.currentTimeMillis() / 1000L`
+ JavaScript: `Math.floor(Date.now() / 1000)`
## Activez DynamoDB TTL à l'aide de CloudFormation
```
AWSTemplateFormatVersion: "2010-09-09"
Resources:
TTLExampleTable:
Type: AWS::DynamoDB::Table
Description: "A DynamoDB table with TTL Specification enabled"
Properties:
AttributeDefinitions:
- AttributeName: "Album"
AttributeType: "S"
- AttributeName: "Artist"
AttributeType: "S"
KeySchema:
- AttributeName: "Album"
KeyType: "HASH"
- AttributeName: "Artist"
KeyType: "RANGE"
ProvisionedThroughput:
ReadCapacityUnits: "5"
WriteCapacityUnits: "5"
TimeToLiveSpecification:
AttributeName: "TTLExampleAttribute"
Enabled: true
```
Vous trouverez des informations supplémentaires sur l'utilisation du TTL dans vos CloudFormation modèles [ici](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-timetolivespecification.html).
# Calcul de la durée de vie (TTL) dans DynamoDB
Une méthode courante pour implémenter la durée de vie, ou TTL, consiste à définir un délai d’expiration pour les éléments en fonction de leur date de création ou de dernière mise à jour. Cela peut être fait en ajoutant l’heure aux horodatages `createdAt` et `updatedAt`. Par exemple, la TTL des éléments qui viennent d’être créés peut être défini sur `createdAt` \$1 90 jours. Lorsque l’élément est mis à jour, la TTL peut être recalculée sur `updatedAt` \$1 90 jours.
Le délai d’expiration calculé doit être au format epoch, en secondes. Pour que l’expiration et la suppression soient prises en compte, la TTL ne doit pas dater de plus de cinq ans. Si vous utilisez un autre format, les processus TTL ignorent l’élément. Si vous définissez le délai d'expiration à un moment futur où vous souhaitez que l'article expire, l'article expirera après cette date. Supposons, par exemple, que vous définissiez l'heure d'expiration sur 1724241326 (c'est-à-dire le lundi 21 août 2024 11:55:26 (UTC)). L'article expire après le délai spécifié. Il n'y a pas de durée TTL minimale. Vous pouvez définir l'heure d'expiration à n'importe quelle date future, par exemple 5 minutes à compter de l'heure actuelle. Toutefois, DynamoDB supprime généralement les éléments expirés dans les 48 heures suivant leur date d'expiration, et non immédiatement après leur expiration.
**Topics**
+ [Création d’un élément et définition de la durée de vie (TTL)](#time-to-live-ttl-before-you-start-create)
+ [Mise à jour d’un élément et actualisation de la durée de vie (TTL)](#time-to-live-ttl-before-you-start-update)
## Création d’un élément et définition de la durée de vie (TTL)
L’exemple suivant montre comment calculer le délai d’expiration lors de la création d’un élément, en utilisant `expireAt` comme nom d’attribut TTL. Une instruction d’affectation obtient l’heure actuelle sous forme de variable. Dans l’exemple, le délai d’expiration est calculé comme étant de 90 jours à compter de l’heure actuelle. L’heure est ensuite convertie au format epoch et enregistrée sous forme de type de données « entier » dans l’attribut TTL.
Les exemples de code suivants montrent comment créer un élément avec une TTL.
------
#### [ Java ]
**SDK pour Java 2.x**
```
package com.amazon.samplelib.ttl;
import com.amazon.samplelib.CodeSampleUtils;
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;
import java.util.Map;
import java.util.Optional;
/**
* Creates an item in a DynamoDB table with TTL attributes.
* This class demonstrates how to add TTL expiration timestamps to DynamoDB items.
*/
public class CreateTTL {
private static final String USAGE =
"""
Usage:
Where:
tableName - The Amazon DynamoDB table being queried.
primaryKey - The name of the primary key. Also known as the hash or partition key.
sortKey - The name of the sort key. Also known as the range attribute.
region (optional) - The AWS region that the Amazon DynamoDB table is located in. (Default: us-east-1)
""";
private static final int DAYS_TO_EXPIRE = 90;
private static final int SECONDS_PER_DAY = 24 * 60 * 60;
private static final String PRIMARY_KEY_ATTR = "primaryKey";
private static final String SORT_KEY_ATTR = "sortKey";
private static final String CREATION_DATE_ATTR = "creationDate";
private static final String EXPIRE_AT_ATTR = "expireAt";
private static final String SUCCESS_MESSAGE = "%s PutItem operation with TTL successful.";
private static final String TABLE_NOT_FOUND_ERROR = "Error: The Amazon DynamoDB table \"%s\" can't be found.";
private final DynamoDbClient dynamoDbClient;
/**
* Constructs a CreateTTL instance with the specified DynamoDB client.
*
* @param dynamoDbClient The DynamoDB client to use
*/
public CreateTTL(final DynamoDbClient dynamoDbClient) {
this.dynamoDbClient = dynamoDbClient;
}
/**
* Constructs a CreateTTL with a default DynamoDB client.
*/
public CreateTTL() {
this.dynamoDbClient = null;
}
/**
* Main method to demonstrate creating an item with TTL.
*
* @param args Command line arguments
*/
public static void main(final String[] args) {
try {
int result = new CreateTTL().processArgs(args);
System.exit(result);
} catch (Exception e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
/**
* Process command line arguments and create an item with TTL.
*
* @param args Command line arguments
* @return 0 if successful, non-zero otherwise
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
* @throws IllegalArgumentException If arguments are invalid
*/
public int processArgs(final String[] args) {
// Argument validation (remove or replace this line when reusing this code)
CodeSampleUtils.validateArgs(args, new int[] {3, 4}, USAGE);
final String tableName = args[0];
final String primaryKey = args[1];
final String sortKey = args[2];
final Region region = Optional.ofNullable(args.length > 3 ? args[3] : null)
.map(Region::of)
.orElse(Region.US_EAST_1);
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final CreateTTL createTTL = new CreateTTL(ddb);
createTTL.createItemWithTTL(tableName, primaryKey, sortKey);
return 0;
} catch (Exception e) {
throw e;
}
}
/**
* Creates an item in the specified table with TTL attributes.
*
* @param tableName The name of the table
* @param primaryKeyValue The value for the primary key
* @param sortKeyValue The value for the sort key
* @return The response from the PutItem operation
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
*/
public PutItemResponse createItemWithTTL(
final String tableName, final String primaryKeyValue, final String sortKeyValue) {
// Get current time in epoch second format
final long createDate = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = createDate + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
final Map itemMap = new HashMap<>();
itemMap.put(
PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKeyValue).build());
itemMap.put(SORT_KEY_ATTR, AttributeValue.builder().s(sortKeyValue).build());
itemMap.put(
CREATION_DATE_ATTR,
AttributeValue.builder().n(String.valueOf(createDate)).build());
itemMap.put(
EXPIRE_AT_ATTR,
AttributeValue.builder().n(String.valueOf(expireDate)).build());
final PutItemRequest request =
PutItemRequest.builder().tableName(tableName).item(itemMap).build();
try {
final PutItemResponse response = dynamoDbClient.putItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return response;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
}
```
+ Pour plus de détails sur l'API, reportez-vous [PutItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/PutItem)à la section *Référence des AWS SDK for Java 2.x API*.
------
#### [ JavaScript ]
**SDK pour JavaScript (v3)**
```
import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
export function createDynamoDBItem(table_name, region, partition_key, sort_key) {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
// Get the current time in epoch second format
const current_time = Math.floor(new Date().getTime() / 1000);
// Calculate the expireAt time (90 days from now) in epoch second format
const expire_at = Math.floor((new Date().getTime() + 90 * 24 * 60 * 60 * 1000) / 1000);
// Create DynamoDB item
const item = {
'partitionKey': {'S': partition_key},
'sortKey': {'S': sort_key},
'createdAt': {'N': current_time.toString()},
'expireAt': {'N': expire_at.toString()}
};
const putItemCommand = new PutItemCommand({
TableName: table_name,
Item: item,
ProvisionedThroughput: {
ReadCapacityUnits: 1,
WriteCapacityUnits: 1,
},
});
client.send(putItemCommand, function(err, data) {
if (err) {
console.log("Exception encountered when creating item %s, here's what happened: ", data, err);
throw err;
} else {
console.log("Item created successfully: %s.", data);
return data;
}
});
}
// Example usage (commented out for testing)
// createDynamoDBItem('your-table-name', 'us-east-1', 'your-partition-key-value', 'your-sort-key-value');
```
+ Pour plus de détails sur l'API, reportez-vous [PutItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/PutItemCommand)à la section *Référence des AWS SDK pour JavaScript API*.
------
#### [ Python ]
**Kit SDK for Python (Boto3)**
```
from datetime import datetime, timedelta
import boto3
def create_dynamodb_item(table_name, region, primary_key, sort_key):
"""
Creates a DynamoDB item with an attached expiry attribute.
:param table_name: Table name for the boto3 resource to target when creating an item
:param region: string representing the AWS region. Example: `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:return: Void (nothing)
"""
try:
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Get the current time in epoch second format
current_time = int(datetime.now().timestamp())
# Calculate the expiration time (90 days from now) in epoch second format
expiration_time = int((datetime.now() + timedelta(days=90)).timestamp())
item = {
"primaryKey": primary_key,
"sortKey": sort_key,
"creationDate": current_time,
"expireAt": expiration_time,
}
response = table.put_item(Item=item)
print("Item created successfully.")
return response
except Exception as e:
print(f"Error creating item: {e}")
raise e
# Use your own values
create_dynamodb_item(
"your-table-name", "us-west-2", "your-partition-key-value", "your-sort-key-value"
)
```
+ Pour plus de détails sur l'API, consultez [PutItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/PutItem)le *AWS manuel de référence de l'API SDK for Python (Boto3*).
------
## Mise à jour d’un élément et actualisation de la durée de vie (TTL)
Cet exemple est la suite de la [section précédente](#time-to-live-ttl-before-you-start-create). Le délai d’expiration peut être recalculé si l’élément est mis à jour. L’exemple suivant recalcule l’horodatage `expireAt` pour qu’il corresponde à 90 jours à partir de l’heure actuelle.
Les exemples de code suivants montrent comment mettre à jour la TTL d’un élément.
------
#### [ Java ]
**SDK pour Java 2.x**
Mise à jour de la TTL sur un élément DynamoDB existant dans une table.
```
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.ResourceNotFoundException;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemResponse;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
public UpdateItemResponse updateItemWithTTL(
final String tableName, final String primaryKeyValue, final String sortKeyValue) {
// Get current time in epoch second format
final long currentTime = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = currentTime + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
// Create the key map for the item to update
final Map keyMap = new HashMap<>();
keyMap.put(PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKeyValue).build());
keyMap.put(SORT_KEY_ATTR, AttributeValue.builder().s(sortKeyValue).build());
// Create the expression attribute values
final Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(
":c", AttributeValue.builder().n(String.valueOf(currentTime)).build());
expressionAttributeValues.put(
":e", AttributeValue.builder().n(String.valueOf(expireDate)).build());
final UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(keyMap)
.updateExpression(UPDATE_EXPRESSION)
.expressionAttributeValues(expressionAttributeValues)
.build();
try {
final UpdateItemResponse response = dynamoDbClient.updateItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return response;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
```
+ Pour plus de détails sur l'API, reportez-vous [UpdateItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem)à la section *Référence des AWS SDK for Java 2.x API*.
------
#### [ JavaScript ]
**SDK pour JavaScript (v3)**
```
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const updateItem = async (tableName, partitionKey, sortKey, region = 'us-east-1') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const expireAt = Math.floor((Date.now() + 90 * 24 * 60 * 60 * 1000) / 1000);
const params = {
TableName: tableName,
Key: marshall({
partitionKey: partitionKey,
sortKey: sortKey
}),
UpdateExpression: "SET updatedAt = :c, expireAt = :e",
ExpressionAttributeValues: marshall({
":c": currentTime,
":e": expireAt
}),
};
try {
const data = await client.send(new UpdateItemCommand(params));
const responseData = unmarshall(data.Attributes);
console.log("Item updated successfully: %s", responseData);
return responseData;
} catch (err) {
console.error("Error updating item:", err);
throw err;
}
}
// Example usage (commented out for testing)
// updateItem('your-table-name', 'your-partition-key-value', 'your-sort-key-value');
```
+ Pour plus de détails sur l'API, reportez-vous [UpdateItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand)à la section *Référence des AWS SDK pour JavaScript API*.
------
#### [ Python ]
**Kit SDK for Python (Boto3)**
```
from datetime import datetime, timedelta
import boto3
def update_dynamodb_item(table_name, region, primary_key, sort_key):
"""
Update an existing DynamoDB item with a TTL.
:param table_name: Name of the DynamoDB table
:param region: AWS Region of the table - example `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:return: Void (nothing)
"""
try:
# Create the DynamoDB resource.
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Get the current time in epoch second format
current_time = int(datetime.now().timestamp())
# Calculate the expireAt time (90 days from now) in epoch second format
expire_at = int((datetime.now() + timedelta(days=90)).timestamp())
table.update_item(
Key={"partitionKey": primary_key, "sortKey": sort_key},
UpdateExpression="set updatedAt=:c, expireAt=:e",
ExpressionAttributeValues={":c": current_time, ":e": expire_at},
)
print("Item updated successfully.")
except Exception as e:
print(f"Error updating item: {e}")
# Replace with your own values
update_dynamodb_item(
"your-table-name", "us-west-2", "your-partition-key-value", "your-sort-key-value"
)
```
+ Pour plus de détails sur l'API, consultez [UpdateItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/UpdateItem)le *AWS manuel de référence de l'API SDK for Python (Boto3*).
------
Les exemples de TTL présentés dans cette introduction illustrent une méthode permettant de garantir que seuls les éléments récemment mis à jour sont conservés dans une table. Les éléments mis à jour voient leur durée de vie prolongée, tandis que les éléments non mis à jour après leur création expirent et sont supprimés gratuitement, ce qui réduit le stockage utilisé et permet de maintenir les tables propres.
# Utilisation des éléments ayant expiré et de la durée de vie (TTL)
Les éléments ayant expiré qui sont en attente de suppression peuvent être exclus des opérations de lecture et d’écriture. Cela est utile dans les scénarios où les données ayant expiré ne sont plus valides et ne doivent pas être utilisées. S’ils ne sont pas exclus, ils continueront à s’afficher dans les opérations de lecture et d’écriture jusqu’à ce qu’ils soient supprimés par le processus en arrière-plan.
**Note**
Ces éléments sont toujours pris en compte dans les coûts de stockage et de lecture jusqu’à ce qu’ils soient supprimés.
Les suppressions par TTL peuvent être identifiées dans DynamoDB Streams, mais uniquement dans la région où la suppression a eu lieu. Les suppressions par TTL qui sont répliquées dans les régions de tables globales ne sont pas identifiables dans les flux DynamoDB des régions vers lesquelles la suppression est répliquée.
## Exclusion des éléments ayant expiré des opérations de lecture
Pour les opérations de lecture telles que [Scan](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html) et [Query](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html), une expression de filtre peut exclure les éléments ayant expiré qui sont en attente de suppression. Comme indiqué dans l’extrait de code suivant, l’expression de filtre peut exclure les éléments dont la durée de vie, ou TTL, est inférieure ou égale à l’heure actuelle. Par exemple, le code du kit SDK Python inclut une instruction d’affectation qui obtient l’heure actuelle sous forme de variable (`now`) et la convertit en `int` au format d’heure epoch.
Les exemples de code suivants montrent l’interrogation d’éléments TTL.
------
#### [ Java ]
**SDK pour Java 2.x**
Expression filtrée par requête pour rassembler des éléments TTL dans une table DynamoDB à l'aide de. AWS SDK for Java 2.x
```
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.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import java.util.Map;
import java.util.Optional;
final QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression(KEY_CONDITION_EXPRESSION)
.filterExpression(FILTER_EXPRESSION)
.expressionAttributeNames(expressionAttributeNames)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final QueryResponse response = ddb.query(request);
System.out.println("Query successful. Found " + response.count() + " items that have not expired yet.");
// Print each item
response.items().forEach(item -> {
System.out.println("Item: " + item);
});
return 0;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
```
+ Pour plus d’informations sur l’API, consultez [Requête](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/Query) dans la *référence d’API AWS SDK for Java 2.x *.
------
#### [ JavaScript ]
**SDK pour JavaScript (v3)**
Expression filtrée par requête pour rassembler des éléments TTL dans une table DynamoDB à l'aide de. AWS SDK pour JavaScript
```
import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const queryFiltered = async (tableName, primaryKey, region = 'us-east-1') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
KeyConditionExpression: "#pk = :pk",
FilterExpression: "#ea > :ea",
ExpressionAttributeNames: {
"#pk": "primaryKey",
"#ea": "expireAt"
},
ExpressionAttributeValues: marshall({
":pk": primaryKey,
":ea": currentTime
})
};
try {
const { Items } = await client.send(new QueryCommand(params));
Items.forEach(item => {
console.log(unmarshall(item))
});
return Items;
} catch (err) {
console.error(`Error querying items: ${err}`);
throw err;
}
}
// Example usage (commented out for testing)
// queryFiltered('your-table-name', 'your-partition-key-value');
```
+ Pour plus d’informations sur l’API, consultez [Requête](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/QueryCommand) dans la *référence d’API AWS SDK pour JavaScript *.
------
#### [ Python ]
**Kit SDK for Python (Boto3)**
Expression filtrée par requête pour rassembler des éléments TTL dans une table DynamoDB à l'aide de. AWS SDK pour Python (Boto3)
```
from datetime import datetime
import boto3
def query_dynamodb_items(table_name, partition_key):
"""
:param table_name: Name of the DynamoDB table
:param partition_key:
:return:
"""
try:
# Initialize a DynamoDB resource
dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
# Specify your table
table = dynamodb.Table(table_name)
# Get the current time in epoch format
current_time = int(datetime.now().timestamp())
# Perform the query operation with a filter expression to exclude expired items
# response = table.query(
# KeyConditionExpression=boto3.dynamodb.conditions.Key('partitionKey').eq(partition_key),
# FilterExpression=boto3.dynamodb.conditions.Attr('expireAt').gt(current_time)
# )
response = table.query(
KeyConditionExpression=dynamodb.conditions.Key("partitionKey").eq(partition_key),
FilterExpression=dynamodb.conditions.Attr("expireAt").gt(current_time),
)
# Print the items that are not expired
for item in response["Items"]:
print(item)
except Exception as e:
print(f"Error querying items: {e}")
# Call the function with your values
query_dynamodb_items("Music", "your-partition-key-value")
```
+ Pour de plus amples informations sur l’API, consultez [Requête](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/Query) dans la *référence d’API AWS du kit SDK pour Python (Boto3)*.
------
## Écriture conditionnelle sur les éléments ayant expiré
Une expression conditionnelle peut être utilisée pour éviter les écritures sur les éléments ayant expiré. L’extrait de code ci-dessous est une mise à jour conditionnelle qui vérifie si le délai d’expiration est supérieur à l’heure actuelle. Si tel est le cas, l’opération d’écriture se poursuit.
Les exemples de code suivants montrent comment mettre à jour la TTL d’un élément de manière conditionnelle.
------
#### [ Java ]
**SDK pour Java 2.x**
Mettez à jour de la TTL sur un élément DynamoDB existant dans une table, avec une condition.
```
package com.amazon.samplelib.ttl;
import com.amazon.samplelib.CodeSampleUtils;
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.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemResponse;
import java.util.Map;
import java.util.Optional;
/**
* Updates an item in a DynamoDB table with TTL attributes using a conditional expression.
* This class demonstrates how to conditionally update TTL expiration timestamps.
*/
public class UpdateTTLConditional {
private static final String USAGE =
"""
Usage:
Where:
tableName - The Amazon DynamoDB table being queried.
primaryKey - The name of the primary key. Also known as the hash or partition key.
sortKey - The name of the sort key. Also known as the range attribute.
region (optional) - The AWS region that the Amazon DynamoDB table is located in. (Default: us-east-1)
""";
private static final int DAYS_TO_EXPIRE = 90;
private static final int SECONDS_PER_DAY = 24 * 60 * 60;
private static final String PRIMARY_KEY_ATTR = "primaryKey";
private static final String SORT_KEY_ATTR = "sortKey";
private static final String UPDATED_AT_ATTR = "updatedAt";
private static final String EXPIRE_AT_ATTR = "expireAt";
private static final String UPDATE_EXPRESSION = "SET " + UPDATED_AT_ATTR + "=:c, " + EXPIRE_AT_ATTR + "=:e";
private static final String CONDITION_EXPRESSION = "attribute_exists(" + PRIMARY_KEY_ATTR + ")";
private static final String SUCCESS_MESSAGE = "%s UpdateItem operation with TTL successful.";
private static final String CONDITION_FAILED_MESSAGE = "Condition check failed. Item does not exist.";
private static final String TABLE_NOT_FOUND_ERROR = "Error: The Amazon DynamoDB table \"%s\" can't be found.";
private final DynamoDbClient dynamoDbClient;
/**
* Constructs an UpdateTTLConditional with a default DynamoDB client.
*/
public UpdateTTLConditional() {
this.dynamoDbClient = null;
}
/**
* Constructs an UpdateTTLConditional with the specified DynamoDB client.
*
* @param dynamoDbClient The DynamoDB client to use
*/
public UpdateTTLConditional(final DynamoDbClient dynamoDbClient) {
this.dynamoDbClient = dynamoDbClient;
}
/**
* Main method to demonstrate conditionally updating an item with TTL.
*
* @param args Command line arguments
*/
public static void main(final String[] args) {
try {
int result = new UpdateTTLConditional().processArgs(args);
System.exit(result);
} catch (Exception e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
/**
* Process command line arguments and conditionally update an item with TTL.
*
* @param args Command line arguments
* @return 0 if successful, non-zero otherwise
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
* @throws IllegalArgumentException If arguments are invalid
*/
public int processArgs(final String[] args) {
// Argument validation (remove or replace this line when reusing this code)
CodeSampleUtils.validateArgs(args, new int[] {3, 4}, USAGE);
final String tableName = args[0];
final String primaryKey = args[1];
final String sortKey = args[2];
final Region region = Optional.ofNullable(args.length > 3 ? args[3] : null)
.map(Region::of)
.orElse(Region.US_EAST_1);
// Get current time in epoch second format
final long currentTime = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = currentTime + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
// Create the key map for the item to update
final Map keyMap = Map.of(
PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKey).build(),
SORT_KEY_ATTR, AttributeValue.builder().s(sortKey).build());
// Create the expression attribute values
final Map expressionAttributeValues = Map.of(
":c", AttributeValue.builder().n(String.valueOf(currentTime)).build(),
":e", AttributeValue.builder().n(String.valueOf(expireDate)).build());
final UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(keyMap)
.updateExpression(UPDATE_EXPRESSION)
.conditionExpression(CONDITION_EXPRESSION)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final UpdateItemResponse response = ddb.updateItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return 0;
} catch (ConditionalCheckFailedException e) {
System.err.println(CONDITION_FAILED_MESSAGE);
throw e;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
}
```
+ Pour plus de détails sur l'API, reportez-vous [UpdateItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem)à la section *Référence des AWS SDK for Java 2.x API*.
------
#### [ JavaScript ]
**SDK pour JavaScript (v3)**
Mettez à jour de la TTL sur un élément DynamoDB existant dans une table, avec une condition.
```
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const updateItemConditional = async (tableName, partitionKey, sortKey, region = 'us-east-1', newAttribute = 'default-value') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
Key: marshall({
artist: partitionKey,
album: sortKey
}),
UpdateExpression: "SET newAttribute = :newAttribute",
ConditionExpression: "expireAt > :expiration",
ExpressionAttributeValues: marshall({
':newAttribute': newAttribute,
':expiration': currentTime
}),
ReturnValues: "ALL_NEW"
};
try {
const response = await client.send(new UpdateItemCommand(params));
const responseData = unmarshall(response.Attributes);
console.log("Item updated successfully: ", responseData);
return responseData;
} catch (error) {
if (error.name === "ConditionalCheckFailedException") {
console.log("Condition check failed: Item's 'expireAt' is expired.");
} else {
console.error("Error updating item: ", error);
}
throw error;
}
};
// Example usage (commented out for testing)
// updateItemConditional('your-table-name', 'your-partition-key-value', 'your-sort-key-value');
```
+ Pour plus de détails sur l'API, reportez-vous [UpdateItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand)à la section *Référence des AWS SDK pour JavaScript API*.
------
#### [ Python ]
**Kit SDK for Python (Boto3)**
Mettez à jour de la TTL sur un élément DynamoDB existant dans une table, avec une condition.
```
from datetime import datetime, timedelta
import boto3
from botocore.exceptions import ClientError
def update_dynamodb_item_ttl(table_name, region, primary_key, sort_key, ttl_attribute):
"""
Updates an existing record in a DynamoDB table with a new or updated TTL attribute.
:param table_name: Name of the DynamoDB table
:param region: AWS Region of the table - example `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:param ttl_attribute: name of the TTL attribute in the target DynamoDB table
:return:
"""
try:
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Generate updated TTL in epoch second format
updated_expiration_time = int((datetime.now() + timedelta(days=90)).timestamp())
# Define the update expression for adding/updating a new attribute
update_expression = "SET newAttribute = :val1"
# Define the condition expression for checking if 'expireAt' is not expired
condition_expression = "expireAt > :val2"
# Define the expression attribute values
expression_attribute_values = {":val1": ttl_attribute, ":val2": updated_expiration_time}
response = table.update_item(
Key={"primaryKey": primary_key, "sortKey": sort_key},
UpdateExpression=update_expression,
ConditionExpression=condition_expression,
ExpressionAttributeValues=expression_attribute_values,
)
print("Item updated successfully.")
return response["ResponseMetadata"]["HTTPStatusCode"] # Ideally a 200 OK
except ClientError as e:
if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
print("Condition check failed: Item's 'expireAt' is expired.")
else:
print(f"Error updating item: {e}")
except Exception as e:
print(f"Error updating item: {e}")
# replace with your values
update_dynamodb_item_ttl(
"your-table-name",
"us-east-1",
"your-partition-key-value",
"your-sort-key-value",
"your-ttl-attribute-value",
)
```
+ Pour plus de détails sur l'API, consultez [UpdateItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/UpdateItem)le *AWS manuel de référence de l'API SDK for Python (Boto3*).
------
## Identification des éléments supprimés dans DynamoDB Streams
L’enregistrement de flux contient un champ d’identité utilisateur `Records[].userIdentity`. Les éléments qui sont supprimés par le processus TTL ont les champs suivants :
```
Records[].userIdentity.type
"Service"
Records[].userIdentity.principalId
"dynamodb.amazonaws.com"
```
L’extrait JSON suivant montre la partie pertinente d’un seul enregistrement de flux :
```
"Records": [
{
...
"userIdentity": {
"type": "Service",
"principalId": "dynamodb.amazonaws.com"
}
...
}
]
```
# Interrogation de tables dans DynamoDB
Vous pouvez utiliser l’opération d’API `Query` dans Amazon DynamoDB pour rechercher des éléments en fonction de valeurs de clé primaire.
Vous devez fournir le nom de l’attribut de clé de partition et une valeur unique pour cet attribut. `Query` retourne tous les éléments avec cette valeur de clé de partition. Vous pouvez le cas échéant fournir un attribut de clé de tri et utiliser un opérateur de comparaison pour affiner les résultats de recherche.
Pour plus d’informations sur l’utilisation`Query`, tels que la syntaxe de requête, les paramètres de réponse et d’autres exemples, voir[Interrogation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)dans le*Amazon DynamoDB API Reference*.
**Topics**
+ [Expressions de condition clé pour l’opération Query dans DynamoDB](Query.KeyConditionExpressions.md)
+ [Expressions de filtre pour l’opération Query dans DynamoDB](Query.FilterExpression.md)
+ [Pagination des résultats de requête de table dans DynamoDB](Query.Pagination.md)
+ [Autres aspects de l’utilisation de l’opération Query dans DynamoDB](Query.Other.md)
# Expressions de condition clé pour l’opération Query dans DynamoDB
Vous pouvez utiliser n’importe quel nom dans une expression de condition de clé, sous réserve que le premier caractère soit `a-z` ou `A-Z` et que les autres caractères (à compter du deuxième caractère s’il y en a un) soit `a-z`, `A-Z` ou `0-9`. En outre, le nom d’attribut ne doit pas être un mot réservé DynamoDB. (Pour en obtenir la liste complète, consultez [Mots réservés dans DynamoDB](ReservedWords.md).) Si un nom d’attribut ne répond pas à ces exigences, vous devez définir un nom d’attribut d’expression comme espace réservé. Pour de plus amples informations, veuillez consulter [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md).
Pour les éléments avec une valeur de clé de partition donnée, DynamoDB stocke ces éléments proches les uns des autres, triés par valeur de clé de tri. Dans une opération `Query`, DynamoDB récupère les éléments en ordre trié, puis traite les éléments à l’aide d’une `KeyConditionExpression` et d’une `FilterExpression` éventuellement présente. Alors seulement les résultats de `Query` sont renvoyés au client.
Une opération `Query` retourne toujours un ensemble de résultats. Si aucun élément correspondant n’est trouvé, le jeu de résultats est vide.
Les résultats de `Query` sont toujours triés sur la valeur de la clé de tri. Si le type de données de la clé de tri est `Number`, les résultats sont retournés par ordre numérique. Sinon, les résultats sont retournés dans l’ordre des octets UTF-8. Par défaut, l’ordre de tri est croissant. Pour inverser l’ordre, définissez le paramètre `ScanIndexForward` sur `false`.
Une seule opération `Query` peut extraire au maximum 1 Mo de données. Cette limite s’applique avant qu’une `FilterExpression` ou `ProjectionExpression` ne soit appliquée aux résultats. Si `LastEvaluatedKey` est présent dans la réponse et n’a pas la valeur null, vous devez paginer le jeu de résultats (voir [Pagination des résultats de requête de table dans DynamoDB](Query.Pagination.md)).
## Exemples d’expression de condition clé
Pour spécifier les critères de recherche, vous utilisez une *expression de condition de clé*, c’est-à-dire une chaîne qui détermine les éléments à lire dans la table ou l’index.
Vous devez spécifier le nom de la clé de partition et la valeur comme condition d’égalité. Vous ne pouvez pas utiliser d’attribut non-clé dans une expression de condition clé.
Le cas échéant, vous pouvez fournir une deuxième condition pour la clé de tri (si elle est présente). La condition de la clé de tri doit être l’un des opérateurs de comparaison suivants :
+ `a = b`— vrai si l'attribut *a* est égal à la valeur *b*
+ `a < b`— vrai s'il *a* est inférieur à *b*
+ `a <= b`— vrai s'*a*il est inférieur ou égal à *b*
+ `a > b`— vrai s'il *a* est supérieur à *b*
+ `a >= b`— vrai s'*a*il est supérieur ou égal à *b*
+ `a BETWEEN b AND c`— vrai s'*a*il est supérieur ou égal à*b*, et inférieur ou égal à*c*.
La fonction suivante est également prise en charge :
+ `begins_with (a, substr)` – True si la valeur de l’attribut `a` commence par une sous-chaîne particulière.
Les exemples suivants AWS Command Line Interface (AWS CLI) illustrent l'utilisation d'expressions de conditions clés. Ces expressions utilisent des espaces réservés (tels que `:name` et `:sub`) au lieu de valeurs réelles. Pour plus d’informations, consultez [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md) et [Utilisation de valeurs d’attributs d’expression dans DynamoDB](Expressions.ExpressionAttributeValues.md).
**Example**
Interrogez la table `Thread` pour un `ForumName` (clé de partition) particulier. Tous les éléments ayant cette valeur `ForumName` sont lus par la requête, car la clé de tri (`Subject`) n’est pas incluse dans `KeyConditionExpression`.
```
aws dynamodb query \
--table-name Thread \
--key-condition-expression "ForumName = :name" \
--expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}'
```
**Example**
Interrogez la table `Thread` en quête d’un `ForumName` (clé de partition) particulier, mais cette fois ne retournez que les éléments avec un `Subject` (clé de tri) donné.
```
aws dynamodb query \
--table-name Thread \
--key-condition-expression "ForumName = :name and Subject = :sub" \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":name":{"S":"Amazon DynamoDB"},
":sub":{"S":"DynamoDB Thread 1"}
}
```
**Example**
Interrogez la table `Reply` en quête d’un `Id` (clé de partition) particulier, mais retournez uniquement les éléments dont `ReplyDateTime` (clé de tri) commence par certains caractères.
```
aws dynamodb query \
--table-name Reply \
--key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"},
":dt":{"S":"2015-09"}
}
```
# Expressions de filtre pour l’opération Query dans DynamoDB
Si vous avez besoin d’affiner davantage les résultats de l’opération `Query`, vous pouvez fournir une expression de filtre facultative. Une *expression de filtre* détermine les éléments dans les résultats de l’opération `Query` qui doivent vous être renvoyés. Tous les autres résultats sont ignorés.
Une expression de filtre est appliquée après la fin de l’opération `Query`, mais avant que les résultats soient renvoyés. Par conséquent, une opération `Query` utilise la même capacité de lecture, qu’une expression de filtre soit présente ou non.
Une opération `Query` permet d’extraire au maximum 1 Mo de données. Cette limite s’applique avant que l’expression de filtre soit évaluée.
Une expression de filtre ne peut pas contenir d’attributs de clé de partition ou de clé de tri. Vous devez préciser ces attributs dans l’expression de condition de clé, pas dans l’expression de filtre.
La syntaxe d’un expression de filtre est similaire à celle d’une expression de condition de clé. Les expressions de filtre peuvent utiliser les mêmes comparateurs, fonctions et opérateurs logiques qu’une expression de condition de clé. En outre, les expressions de filtre peuvent utiliser l’opérateur non égal (`<>`), l’opérateur `OR`, l’opérateur `CONTAINS`, l’opérateur `IN`, l’opérateur `BEGINS_WITH`, l’opérateur `BETWEEN`, l’opérateur `EXISTS` et l’opérateur `SIZE`. Pour plus d’informations, consultez [Expressions de condition clé pour l’opération Query dans DynamoDB](Query.KeyConditionExpressions.md) et [Syntaxe des expressions de filtre et de condition](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax).
**Example**
L' AWS CLI exemple suivant interroge la `Thread` table pour une `ForumName` (clé de partition) et une `Subject` (clé de tri) particulières. Parmi les éléments trouvés, seules les unités d’exécution de discussion les plus populaires sont renvoyés, c’est-à-dire les threads ayant plus qu’un certain nombre de `Views`.
```
aws dynamodb query \
--table-name Thread \
--key-condition-expression "ForumName = :fn and Subject begins_with :sub" \
--filter-expression "#v >= :num" \
--expression-attribute-names '{"#v": "Views"}' \
--expression-attribute-values file://values.json
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":fn":{"S":"Amazon DynamoDB"},
":sub":{"S":"DynamoDB Thread 1"},
":num":{"N":"3"}
}
```
Notez que `Views` étant un mot réservé dans DynamoDB (consultez [Mots réservés dans DynamoDB](ReservedWords.md)), cet exemple utilise `#v` comme espace réservé. Pour de plus amples informations, veuillez consulter [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md).
**Note**
Une expression de filtre supprime des éléments du jeu de résultats de `Query`. Dans la mesure du possible, évitez d’utiliser `Query` lorsque vous pensez extraire un grand nombre d’éléments mais que vous devrez en supprimer une grande partie.
# Pagination des résultats de requête de table dans DynamoDB
DynamoDB *pagine* les résultats des opérations `Query`. Avec la pagination, les résultats de l’opération `Query` sont répartis en « pages » de données d’une taille maximum de 1 Mo. Une application peut traiter la première page des résultats, puis la deuxième, et ainsi de suite.
Une opération `Query` retourne uniquement un ensemble de résultats correspondant à la limite de taille de 1 Mo. Pour déterminer si le nombre de résultats est plus important et pour récupérer une page à la fois, les applications doivent procéder de la manière suivante :
1. Examinez le résultat de l’opération `Query` de niveau inférieur :
+ Si le résultat contient un élément `LastEvaluatedKey` dont la valeur n’est pas null, passez à l’étape 2.
+ S’il n’y a *pas* de `LastEvaluatedKey` dans le résultat, il n’y a plus aucun élément à récupérer.
1. Construisez une `Query` avec la même `KeyConditionExpression`. Cependant, cette fois, acceptez la valeur `LastEvaluatedKey` de l’étape 1 et utilisez-la comme paramètre `ExclusiveStartKey` dans la nouvelle demande `Query`.
1. Exécutez la nouvelle demande `Query`.
1. Passez à l’étape 1.
En d’autres termes, l’élément `LastEvaluatedKey` provenant d’une réponse `Query` doit être utilisé comme `ExclusiveStartKey` pour la demande `Query` suivante. Si aucun élément `LastEvaluatedKey` n’est présent dans la réponse `Query`, vous avez extrait la dernière page de résultats. Si `LastEvaluatedKey` n’est pas vide, cela ne signifie pas nécessairement qu’il y a plus de données dans le jeu de résultats. Le seul moyen de savoir que vous avez atteint la fin du jeu de résultats est lorsque `LastEvaluatedKey` est vide.
Vous pouvez utiliser le AWS CLI pour visualiser ce comportement. AWS CLI envoie des `Query` requêtes de bas niveau à DynamoDB à plusieurs reprises, `LastEvaluatedKey` jusqu'à ce qu'elles ne soient plus présentes dans les résultats. Prenons l' AWS CLI exemple suivant qui récupère les titres de films d'une année donnée.
```
aws dynamodb query --table-name Movies \
--projection-expression "title" \
--key-condition-expression "#y = :yyyy" \
--expression-attribute-names '{"#y":"year"}' \
--expression-attribute-values '{":yyyy":{"N":"1993"}}' \
--page-size 5 \
--debug
```
Normalement, il AWS CLI gère automatiquement la pagination. Toutefois, dans cet exemple, le AWS CLI `--page-size` paramètre limite le nombre d'éléments par page. La paramètre `--debug` imprime les informations de bas niveau relatives aux demandes et aux réponses.
Si vous exécutez l’exemple, la première réponse de DynamoDB est à similaire à ce qui suit.
```
2017-07-07 11:13:15,603 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"Count":5,"Items":[{"title":{"S":"A Bronx Tale"}},
{"title":{"S":"A Perfect World"}},{"title":{"S":"Addams Family Values"}},
{"title":{"S":"Alive"}},{"title":{"S":"Benny & Joon"}}],
"LastEvaluatedKey":{"year":{"N":"1993"},"title":{"S":"Benny & Joon"}},
"ScannedCount":5}'
```
Le `LastEvaluatedKey` de la réponse indique que certains éléments n’ont pas été récupérés. Il envoie AWS CLI ensuite une autre `Query` demande à DynamoDB. Ce modèle de requête et de réponse se poursuit jusqu’à l’obtention d’une réponse finale.
```
2017-07-07 11:13:16,291 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"Count":1,"Items":[{"title":{"S":"What\'s Eating Gilbert Grape"}}],"ScannedCount":1}'
```
L’absence de `LastEvaluatedKey` indique qu’il n’y a pas plus de d’élément à récupérer.
**Note**
Ils AWS SDKs gèrent les réponses DynamoDB de bas niveau (y compris la présence ou l'absence de) et fournissent diverses abstractions pour `LastEvaluatedKey` la pagination des résultats. `Query` Par exemple, l’interface de document du kit SDK pour Java fournit le support `java.util.Iterator` pour vous permettre de parcourir les résultats un par un.
Pour des exemples de code dans divers langages de programmation, consultez le [Guide de prise en main d’Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) et la documentation du kit SDK AWS pour votre langage.
Vous pouvez également réduire la taille de la page en limitant le nombre d’éléments dans l’ensemble de résultats, avec le paramètre `Limit` de l’opération `Query`.
Pour plus d’informations sur l’interrogation avec DynamoDB, consultez [Interrogation de tables dans DynamoDB](Query.md).
# Autres aspects de l’utilisation de l’opération Query dans DynamoDB
Cette section couvre d’autres aspects de l’opération Query DynamoDB, notamment la limitation de la taille des résultats, le comptage des éléments analysés par rapport aux éléments renvoyés, la surveillance de la consommation de capacité de lecture et le contrôle de la cohérence en lecture.
## Limiter le nombre d’éléments dans le jeu de résultats
Avec l’opération `Query`, vous pouvez limiter le nombre d’éléments qu’elle lit. Pour ce faire, définissez le paramètre `Limit` sur le nombre maximal d’éléments souhaité.
Par exemple, supposons que vous effectuiez une opération `Query` sur une table, avec une valeur `Limit` de `6` et sans expression de filtre. Le résultat `Query` contient les six premiers éléments de la table qui correspondent à l’expression de condition de clé de la demande.
Supposons maintenant que vous ajoutiez une expression de filtre à l’opération `Query`. Dans ce cas, DynamoDB lit jusqu’à six éléments, puis renvoie uniquement ceux qui correspondent à l’expression de filtre. Le résultat `Query` final contient au maximum six éléments, même si davantage d’éléments auraient correspondu à l’expression de filtre si DynamoDB avait continué à lire plus d’éléments.
## Comptabilisation des éléments dans les résultats
Outre les éléments qui correspondent à vos critères, la réponse d’une opération `Query` contient les éléments suivants :
+ `ScannedCount` – Nombre d’éléments qui correspondaient à l’expression de condition de clé *avant* qu’une expression de filtre (le cas échéant) soit appliquée.
+ `Count` – Nombre d’éléments qui restent *après* l’application d’une expression de filtre (le cas échéant).
**Note**
Si vous n’utilisez pas d’expression de filtre, alors `ScannedCount` et `Count` ont la même valeur.
Si la taille de l’ensemble de résultats `Query` est supérieure à 1 Mo, les opérations `ScannedCount` et `Count` représentent seulement un compte partiel du total des éléments. Vous devez effectuer plusieurs opérations `Query` pour extraire tous les résultats. (Consultez [Pagination des résultats de requête de table dans DynamoDB](Query.Pagination.md).)
Chaque réponse `Query` comporte les `ScannedCount` et `Count` des éléments traités par cette demande `Query` particulière. Pour obtenir les totaux de toutes les demandes `Query`, vous pouvez garder un compte actif de `ScannedCount` et de `Count`.
## Unités de capacité consommées par la requête
Vous pouvez interroger n’importe quelle table ou n’importe quel index secondaire avec `Query`, à condition de fournir le nom de l’attribut de clé de partition et une valeur unique pour cet attribut. `Query` renvoie tous les éléments contenant cette valeur de clé de partition. Vous pouvez éventuellement fournir un attribut de clé de tri et utiliser un opérateur de comparaison pour affiner les résultats de recherche. Les opérations d’API `Query` consomment des unités de capacité de lecture, comme suit.
****
| Si vous effectuez une opération `Query` sur… | DynamoDB consomme des unités de capacité de lecture de… |
| --- | --- |
| Table | Capacité de lecture allouée de la table. |
| GSI | Capacité de lecture allouée à l’index. |
| Index secondaire local | Capacité de lecture allouée de la table de base. |
Par défaut, l’opération `Query` ne renvoie pas de données concernant la consommation de capacité de lecture. Vous pouvez toutefois spécifier le paramètre `ReturnConsumedCapacity` dans une demande `Query` pour obtenir ces informations. Voici les paramètres valides pour `ReturnConsumedCapacity` :
+ `NONE` – Aucune donnée de capacité consommée n’est renvoyée. (Il s’agit de l’option par défaut.)
+ `TOTAL` – La réponse inclut le nombre agrégé d’unités de capacité de lecture consommées.
+ `INDEXES` – La réponse indique le nombre agrégé d’unités de capacité de lecture consommées, ainsi que la capacité consommée pour chaque table et index consultés.
DynamoDB calcule le nombre d’unités de capacité de lecture consommées en fonction du nombre d’éléments et de la taille de ces éléments, et non du volume de données renvoyées à une application. Pour cette raison, le nombre d’unités de capacité consommées sera le même que vous demandiez tous les attributs (comportement par défaut) ou seulement certains d’entre eux (avec une expression de projection). Le nombre est également le même, que vous utilisiez ou non une expression de filtre. `Query` consomme une unité de capacité de lecture minimale pour effectuer une lecture fortement cohérente par seconde ou deux lectures cohérentes à terme par seconde pour un élément d’une taille maximale de 4 Ko. Si vous devez lire un élément d’une taille supérieure à 4 Ko, DynamoDB a besoin d’unités de demande de lecture supplémentaires. Les tables vides et les très grandes tables contenant peu de clés de partition peuvent entraîner des RCUs frais supplémentaires au-delà de la quantité de données demandées. Cela couvre les frais de traitement de la demande `Query`, même en l’absence de données.
## Cohérence en lecture de la requête
Par défaut, une opération `Query` effectue des lectures cohérentes à terme. Autrement dit, les résultats de l’opération `Query` peuvent ne pas refléter des modifications apportées par des opérations `PutItem` ou `UpdateItem` récentes. Pour de plus amples informations, veuillez consulter [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md).
Si vous avez besoin de lectures fortement cohérentes, définissez le paramètre `ConsistentRead` sur `true` dans la demande `Query`.
# Analyse de tables dans DynamoDB
Une opération `Scan` dans Amazon DynamoDB lit tous les éléments d’une table ou d’un index secondaire. Par défaut, une opération `Scan` renvoie tous les attributs de données pour chaque élément de la table ou de l’index. Vous pouvez utiliser le paramètre `ProjectionExpression` de sorte que `Scan` renvoie uniquement certains des attributs, plutôt que leur totalité.
`Scan` renvoie toujours un ensemble de résultats. Si aucun élément correspondant n’est trouvé, l’ensemble de résultats est vide.
Une seule demande `Scan` permet d’extraire un maximum de 1 Mo de données. Le cas échéant, DynamoDB peut appliquer une expression de filtre à ces données, en affinant les résultats avant qu’ils soient renvoyés à l’utilisateur.
**Topics**
+ [Filtrer les expressions à des fins d’analyse](#Scan.FilterExpression)
+ [Limiter le nombre d’éléments dans l’ensemble de résultats](#Scan.Limit)
+ [Pagination des résultats](#Scan.Pagination)
+ [Comptabilisation des éléments dans les résultats](#Scan.Count)
+ [Unités de capacité consommées par l’opération d’analyse](#Scan.CapacityUnits)
+ [Cohérence en lecture de l’opération d’analyse](#Scan.ReadConsistency)
+ [Analyse parallèle](#Scan.ParallelScan)
## Filtrer les expressions à des fins d’analyse
Si vous devez affiner davantage les résultats de l’opération `Scan`, vous pouvez également fournir une expression de filtre. Une *expression de filtre* détermine les éléments dans les résultats de l’opération `Scan` qui doivent vous être renvoyés. Tous les autres résultats sont ignorés.
Une expression de filtre est appliquée après la fin de l’opération `Scan`, mais avant que les résultats soient renvoyés. Par conséquent, une opération `Scan` consomme la même capacité de lecture, qu’une expression de filtre soit présente ou non.
Une opération `Scan` permet d’extraire au maximum 1 Mo de données. Cette limite s’applique avant que l’expression de filtre soit évaluée.
Avec `Scan`, vous pouvez spécifier tous les attributs dans une expression de filtre, y compris les attributs de clé de partition et de clé de tri.
La syntaxe d’un expression de filtre est identique à celle d’une expression de condition. Les expressions de filtre peuvent utiliser les mêmes comparateurs, fonctions et opérateurs logiques qu’une expression de condition. Pour en savoir plus sur les opérateurs, consultez [Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB](Expressions.OperatorsAndFunctions.md).
**Example**
L'exemple suivant AWS Command Line Interface (AWS CLI) analyse le `Thread` tableau et renvoie uniquement les derniers éléments publiés par un utilisateur en particulier.
```
aws dynamodb scan \
--table-name Thread \
--filter-expression "LastPostedBy = :name" \
--expression-attribute-values '{":name":{"S":"User A"}}'
```
## Limiter le nombre d’éléments dans l’ensemble de résultats
L’opération `Scan` permet de limiter le nombre d’éléments renvoyés dans le résultat. Pour ce faire, définissez le paramètre `Limit` sur le nombre maximal d’éléments que vous souhaitez que l’opération `Scan` renvoie, avant l’évaluation de l’expression de filtre.
Par exemple, supposons que vous effectuiez une opération `Scan` sur une table, avec une valeur `Limit` de `6` et sans expression de filtre. Le résultat de l’opération `Scan` comporte les six premiers éléments de la table.
Supposons maintenant que vous ajoutiez une expression de filtre à l’opération `Scan`. Dans ce cas, DynamoDB applique l’expression de filtre aux six éléments renvoyés et supprime ceux qui ne correspondent pas. Le résultat final de l’opération `Scan` comporte six éléments au plus, selon le nombre d’éléments filtrés.
## Pagination des résultats
DynamoDB *pagine* les résultats des opérations `Scan`. Avec la pagination, les résultats de l’opération `Scan` sont répartis en « pages » de données d’une taille maximum de 1 Mo. Une application peut traiter la première page des résultats, puis la deuxième, et ainsi de suite.
Une opération `Scan` renvoie uniquement un ensemble de résultats correspondant à la limite de taille de 1 Mo.
Pour déterminer si le nombre de résultats est plus important et récupérer une page à la fois, les applications doivent procéder comme suit :
1. Examinez le résultat de l’opération `Scan` de niveau inférieur :
+ Si le résultat comporte un élément `LastEvaluatedKey`, passez à l’étape 2.
+ S’il n’y a *pas* de `LastEvaluatedKey` dans le résultat, il n’y a plus aucun élément à récupérer.
1. Construisez une nouvelle demande `Scan`, avec les mêmes paramètres que la précédente. Cependant, cette fois-ci, acceptez la valeur `LastEvaluatedKey` de l’étape 1 et utilisez-la comme paramètre `ExclusiveStartKey` dans la nouvelle demande `Scan`.
1. Exécutez la nouvelle demande `Scan`.
1. Passez à l’étape 1.
Autrement dit, l’élément `LastEvaluatedKey` provenant d’une réponse de l’opération `Scan` doit être utilisé comme `ExclusiveStartKey` pour la demande `Scan` suivante. Si aucun élément `LastEvaluatedKey` n’est présent dans la réponse de l’opération `Scan`, vous avez extrait la dernière page de résultats. (L’absence de `LastEvaluatedKey` est le seul moyen de savoir que vous avez atteint la fin de l’ensemble de résultats.)
Vous pouvez utiliser le AWS CLI pour visualiser ce comportement. AWS CLI envoie des `Scan` requêtes de bas niveau à DynamoDB, à plusieurs reprises, `LastEvaluatedKey` jusqu'à ce qu'elles ne soient plus présentes dans les résultats. Prenons l' AWS CLI exemple suivant qui scanne l'intégralité du `Movies` tableau mais ne renvoie que les films d'un genre particulier.
```
aws dynamodb scan \
--table-name Movies \
--projection-expression "title" \
--filter-expression 'contains(info.genres,:gen)' \
--expression-attribute-values '{":gen":{"S":"Sci-Fi"}}' \
--page-size 100 \
--debug
```
Normalement, il AWS CLI gère automatiquement la pagination. Toutefois, dans cet exemple, le AWS CLI `--page-size` paramètre limite le nombre d'éléments par page. La paramètre `--debug` imprime les informations de bas niveau relatives aux demandes et aux réponses.
**Note**
Vos résultats de pagination diffèrent également en fonction des paramètres d’entrée que vous transmettez.
L’utilisation de `aws dynamodb scan --table-name Prices --max-items 1` renvoie un `NextToken`
L’utilisation de `aws dynamodb scan --table-name Prices --limit 1` renvoie un `LastEvaluatedKey`.
Sachez également que l’utilisation de `--starting-token` en particulier requiert la valeur `NextToken`.
Si vous exécutez l’exemple, la première réponse de DynamoDB est similaire à ce qui suit.
```
2017-07-07 12:19:14,389 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"Count":7,"Items":[{"title":{"S":"Monster on the Campus"}},{"title":{"S":"+1"}},
{"title":{"S":"100 Degrees Below Zero"}},{"title":{"S":"About Time"}},{"title":{"S":"After Earth"}},
{"title":{"S":"Age of Dinosaurs"}},{"title":{"S":"Cloudy with a Chance of Meatballs 2"}}],
"LastEvaluatedKey":{"year":{"N":"2013"},"title":{"S":"Curse of Chucky"}},"ScannedCount":100}'
```
Le `LastEvaluatedKey` de la réponse indique que certains éléments n’ont pas été récupérés. Il envoie AWS CLI ensuite une autre `Scan` demande à DynamoDB. Ce modèle de requête et de réponse se poursuit jusqu’à l’obtention d’une réponse finale.
```
2017-07-07 12:19:17,830 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"Count":1,"Items":[{"title":{"S":"WarGames"}}],"ScannedCount":6}'
```
L’absence de `LastEvaluatedKey` indique qu’il n’y a pas plus de d’élément à récupérer.
**Note**
Ils AWS SDKs gèrent les réponses DynamoDB de bas niveau (y compris la présence ou l'absence de) et fournissent diverses abstractions pour `LastEvaluatedKey` la pagination des résultats. `Scan` Par exemple, l’interface de document du kit SDK pour Java fournit le support `java.util.Iterator` pour vous permettre de parcourir les résultats un par un.
Pour des exemples de code dans divers langages de programmation, consultez le [Guide de prise en main d’Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) et la documentation du kit SDK AWS pour votre langage.
## Comptabilisation des éléments dans les résultats
Outre les éléments qui correspondent à vos critères, la réponse d’une opération `Scan` comporte les éléments suivants :
+ `ScannedCount` – Nombre d’éléments évalués avant l’application de `ScanFilter`. Une valeur `ScannedCount` élevée avec un nombre faible ou nul de résultats `Count` indique une opération `Scan` inefficace. Si vous n’avez pas utilisé de filtre dans la demande, `ScannedCount` et `Count` ont la même valeur.
+ `Count` – Nombre d’éléments qui restent *après* l’application d’une expression de filtre (le cas échéant).
**Note**
Si vous n’utilisez pas d’expression de filtre, `ScannedCount` et `Count` ont la même valeur.
Si la taille de l’ensemble de résultats `Scan` est supérieure à 1 Mo, les opérations `ScannedCount` et `Count` représentent seulement un décompte partiel du nombre total d’éléments. Vous devez effectuer plusieurs opérations `Scan` pour extraire tous les résultats. (Consultez [Pagination des résultats](#Scan.Pagination).)
Chaque réponse `Scan` comporte les `ScannedCount` et `Count` des éléments traités par cette demande `Scan` particulière. Pour obtenir les totaux de toutes les demandes `Scan`, vous pouvez garder un compte actif de `ScannedCount` et `Count`.
## Unités de capacité consommées par l’opération d’analyse
Vous pouvez effectuer une opération `Scan` sur toute table ou tout index secondaire. Les opérations `Scan` consomment des unités de capacité de lecture, comme suit.
****
| Si vous effectuez une opération `Scan` sur… | DynamoDB consomme des unités de capacité de lecture de… |
| --- | --- |
| Table | Capacité de lecture allouée de la table. |
| GSI | Capacité de lecture allouée à l’index. |
| Index secondaire local | Capacité de lecture allouée de la table de base. |
**Note**
L’accès intercompte pour les opérations d’analyse d’index secondaires n’est actuellement pas pris en charge par les [politiques basées sur les ressources](access-control-resource-based.md).
Par défaut, une opération `Scan` ne renvoie pas de données concernant la consommation de capacité de lecture. Vous pouvez toutefois spécifier le paramètre `ReturnConsumedCapacity` dans une demande `Scan` pour obtenir ces informations. Voici les paramètres valides pour `ReturnConsumedCapacity` :
+ `NONE` – Aucune donnée de capacité consommée n’est renvoyée. (Il s’agit de l’option par défaut.)
+ `TOTAL` – La réponse inclut le nombre agrégé d’unités de capacité de lecture consommées.
+ `INDEXES` – La réponse indique le nombre agrégé d’unités de capacité de lecture consommées, ainsi que la capacité consommée pour chaque table et index consultés.
DynamoDB calcule le nombre d’unités de capacité de lecture consommées en fonction du nombre d’éléments et de la taille de ces éléments, et non du volume de données renvoyées à une application. Pour cette raison, le nombre d’unités de capacité consommées sera le même que vous demandiez tous les attributs (comportement par défaut) ou seulement certains d’entre eux (avec une expression de projection). Le nombre est également le même, que vous utilisiez ou non une expression de filtre. `Scan` consomme une unité de capacité de lecture minimale pour effectuer une lecture fortement cohérente par seconde ou deux lectures cohérentes à terme par seconde pour un élément d’une taille maximale de 4 Ko. Si vous devez lire un élément d’une taille supérieure à 4 Ko, DynamoDB a besoin d’unités de demande de lecture supplémentaires. Les tables vides et les très grandes tables contenant peu de clés de partition peuvent entraîner des RCUs frais supplémentaires au-delà de la quantité de données numérisées. Cela couvre les frais de traitement de la demande `Scan`, même en l’absence de données.
## Cohérence en lecture de l’opération d’analyse
Par défaut, une opération `Scan` effectue des lectures cohérentes à terme. Autrement dit, les résultats de l’opération `Scan` peuvent ne pas refléter des modifications apportées par des opérations `PutItem` ou `UpdateItem` récentes. Pour de plus amples informations, veuillez consulter [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md).
Si vous avez besoin de lectures fortement cohérentes au moment où l’opération `Scan` commence, définissez le paramètre `ConsistentRead` sur la valeur `true` dans la demande `Scan`. Ainsi, toutes les opérations d’écriture terminées avant le début de l’opération `Scan` sont incluses dans la réponse `Scan`.
La définition de `ConsistentRead` sur `true` peut être utile dans la sauvegarde des tables ou les scénarios de réplication, conjointement avec [DynamoDB Streams](./Streams.html). Vous utilisez d’abord `Scan` avec le paramètre `ConsistentRead` défini sur la valeur true pour obtenir une copie cohérente des données de la table. Pendant l’opération `Scan`, DynamoDB Streams enregistre toute activité d’écriture supplémentaire qui se produit sur la table. Une fois l’opération `Scan` terminée, vous pouvez appliquer l’activité d’écriture du flux vers la table.
**Note**
Notez qu’une opération `Scan` avec le paramètre `ConsistentRead` défini sur la valeur `true` consomme deux fois plus d’unités de capacité de lecture, par rapport au fait de laisser la paramètre `ConsistentRead` défini sur sa valeur par défaut (`false`).
## Analyse parallèle
Par défaut, l’opération `Scan` traite les données de manière séquentielle. Amazon DynamoDB renvoie des données à l’application par incréments de 1 Mo, et une application effectue des opérations `Scan` supplémentaires pour extraire le Mo de données suivant.
Plus la table ou l’index en cours d’analyse est grand(e), plus l’opération `Scan` prend du temps. En outre, il arrive qu’une opération `Scan` séquentielle ne puisse pas utiliser pleinement la capacité de débit de lecture alloué. Même si DynamoDB répartit les données d’une grande table sur plusieurs partitions physiques, une opération `Scan` ne peut lire qu’une seule partition à la fois. C’est pourquoi le débit d’une opération `Scan` est limité par le débit maximum d’une partition.
Pour résoudre ce problème, l’opération `Scan` peut diviser logiquement une table ou un index secondaire en plusieurs *segments*, avec plusieurs workers d’application qui analysent les segments en parallèle. Chaque worker peut être un thread (lorsque le langage de programmation prend en charge le multithreading) ou un processus de système d’exploitation. Pour effectuer une analyse en parallèle, chaque worker émet sa propre demande `Scan` avec les paramètres suivants :
+ `Segment` – Segment à analyser par un worker particulier. Chaque worker doit utiliser une valeur différente pour `Segment`.
+ `TotalSegments` – Nombre total de segments pour l’analyse en parallèle. Cette valeur doit être identique au nombre de workers que votre application va utiliser.
Le diagramme suivant illustre la manière dont une application multithread exécute une opération `Scan` en parallèle avec trois degrés de parallélisme.
![\[Application multithread qui effectue une analyse en parallèle en divisant une table en trois segments.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/ParallelScan.png)
Dans ce diagramme, l’application produit trois threads auxquels elle affecte un numéro. (Les segments étant de base zéro, le premier numéro est toujours 0.) Chaque thread émet une demande `Scan`, définissant le paramètre `Segment` sur son numéro désigné, et le paramètre `TotalSegments` sur 3. Chaque thread analyse son segment désigné en extrayant 1 Mo de données à la fois, puis renvoie les données au thread principal de l’application.
DynamoDB affecte des éléments *à des segments en appliquant une fonction de hachage à* la clé de partition de chaque élément. Pour une `TotalSegments` valeur donnée, tous les éléments ayant la même clé de partition sont toujours assignés à la même valeur`Segment`. Cela signifie que dans un tableau où les *éléments 1*, *2* et *3* se partagent tous `pk="account#123"` (mais ont des clés de tri différentes), ces éléments seront traités par le même opérateur, quelles que soient les valeurs des clés de tri ou la taille de la *collection d'articles*.
L'attribution des *segments* étant basée uniquement sur le hachage de la clé de partition, les segments peuvent être répartis de manière inégale. Certains segments peuvent ne contenir aucun élément, tandis que d'autres peuvent contenir de nombreuses clés de partition avec de grandes collections d'éléments. Par conséquent, l'augmentation du nombre total de segments ne garantit pas des performances d'analyse plus rapides, en particulier lorsque les clés de partition ne sont pas réparties uniformément dans l'espace de touches.
Les valeurs des paramètres `Segment` et `TotalSegments` s’appliquent à des demandes `Scan` individuelles et vous pouvez utiliser différentes valeurs à tout moment. Il se peut que vous deviez tester ces valeurs et le nombre de workers que vous utilisez, jusqu’à ce que votre application atteigne des performances optimales.
**Note**
Une analyse en parallèle avec de nombreux threads peut facilement consommer tout le débit alloué pour la table ou l’index analysé(e). Il est préférable d’éviter de telles analyses si d’autres applications soumettent également la table ou l’index à une intense activité de lecture ou d’écriture.
Ccontrôlez le volume de données renvoyées par demande à l’aide du paramètre `Limit`. Cela vous permet d’éviter des situations où un worker consomme tout le débit alloué, au détriment des autres.
# PartiQL – Langage de requête compatible SQL pour Amazon DynamoDB
Amazon DynamoDB prend en charge [PartiQL](https://partiql.org/), un langage de requête compatible SQL, pour sélectionner, insérer, mettre à jour et supprimer des données dans Amazon DynamoDB. Grâce à PartiQL, vous pouvez facilement interagir avec les tables DynamoDB et exécuter des requêtes ad hoc à l'aide de AWS Management Console NoSQL Workbench et de DynamoDB pour PartiQL. AWS Command Line Interface APIs
Les opérations PartiQL offrent une disponibilité, une latence et des performances identiques aux autres opérations de plan de données DynamoDB.
Les sections suivantes décrivent l’implémentation DynamoDB de PartiQL.
**Topics**
+ [Qu’est-ce que PartiQL ?](#ql-reference.what-is)
+ [PartiQL dans Amazon DynamoDB](#ql-reference.what-is)
+ [Prise en main](ql-gettingstarted.md)
+ [Types de données](ql-reference.data-types.md)
+ [Instructions](ql-reference.statements.md)
+ [Fonctions](ql-functions.md)
+ [Opérateurs](ql-operators.md)
+ [Transactions](ql-reference.multiplestatements.transactions.md)
+ [Opérations par lots](ql-reference.multiplestatements.batching.md)
+ [politiques IAM](ql-iam.md)
## Qu’est-ce que PartiQL ?
Le langage *PartiQL* fournit un accès aux requêtes compatible SQL sur plusieurs magasins de données contenant des données structurées, des données semi-structurées et des données imbriquées. Il est largement utilisé au sein d'Amazon et est désormais disponible dans le cadre de nombreux AWS services, dont DynamoDB.
Pour la spécification de PartiQL et un didacticiel sur le langage de requête de base, consultez la [Documentation PartiQL](https://partiql.org/docs.html).
**Note**
Amazon DynamoDB prend en charge un *sous-ensemble* du langage de requête [PartiQL](https://partiql.org/).
Amazon DynamoDB ne prend pas en charge le format de données [Amazon Ion](http://amzn.github.io/ion-docs/) ou les littéraux Amazon Ion.
## PartiQL dans Amazon DynamoDB
Pour exécuter des requêtes PartiQL dans DynamoDB, vous pouvez utiliser les ressources suivantes :
+ La console DynamoDB
+ Le NoSQL Workbench
+ Le AWS Command Line Interface (AWS CLI)
+ Le DynamoDB APIs
Pour plus d’informations sur l’utilisation de ces méthodes pour accéder à DynamoDB, consultez [Accès à DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html).
# Mise en route avec PartiQL pour DynamoDB
Cette section décrit comment utiliser PartiQL pour DynamoDB à partir de la console Amazon DynamoDB, du () et de DynamoDB. AWS Command Line Interface AWS CLI APIs
Dans les exemples suivants, la table DynamoDB définie dans le didacticiel [Mise en route avec DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) est un prérequis.
[Pour plus d'informations sur l'utilisation de la console DynamoDB ou de DynamoDB pour accéder à DynamoDB AWS Command Line Interface, consultez la section Accès à APIs DynamoDB.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html)
Pour [télécharger](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html) et utiliser le [NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html) afin de créer des instructions [PartiQL pour DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.html), choisissez **PartiQL operations** (Opérations PartiQL) dans l’angle supérieur droit du NoSQL Workbench pour DynamoDB [Operation Builder](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.operationbuilder.html) (Créateur d’opérations).
------
#### [ Console ]
![\[Interface d’éditeur PartiQL qui affiche le résultat de l’exécution de l’opération Query sur la table Music.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/partiqlgettingstarted.png)
1. Connectez-vous à la console DynamoDB AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Dans le panneau de navigation sur le côté gauche de la console, choisissez **PartiQL editor (Editeur PartiQL)**.
1. Choisissez la table **Music**.
1. Choisissez **Query table (Table de requête)**. Cette action génère une requête qui n’entraîne pas d’analyse de table complète.
1. Remplacez `partitionKeyValue` par la valeur de chaîne `Acme Band`. Remplacez `sortKeyValue` par la valeur de chaîne `Happy Day`.
1. Choisissez le bouton **Run (Exécuter)**.
1. Vous pouvez afficher les résultats de la requête en choisissant les boutons **Table view (Vue tableau)** ou **JSON view (Vue JSON)**.
------
#### [ NoSQL workbench ]
![\[Interface NoSQL Workbench. Il affiche une instruction PartiQL SELECT que vous pouvez exécuter sur la table Music.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/workbench/partiql.single.png)
1. Choisissez **PartiQL statement (Instruction PartiQL)**.
1. Entrez l’instruction PartiQL [SELECT](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html) suivante
```
SELECT *
FROM Music
WHERE Artist=? and SongTitle=?
```
1. Pour spécifier une valeur pour les paramètres `Artist` et `SongTitle` :
1. Choisissez **Optional request parameters (Paramètres de demande facultatifs)**.
1. Choisissez **Add new parameters (Ajouter de nouveaux paramètres)**.
1. Choisissez le type d’attribut **string (chaîne)** et la valeur `Acme Band`.
1. Répétez les étapes b et c, puis choisissez le type **string (chaîne)** et la valeur `PartiQL Rocks`.
1. Si vous souhaitez générer un code, choisissez **Generate code (Générer un code)**.
Sélectionnez votre langage souhaité dans les onglets affichés. Vous pouvez désormais copier ce code et l’utiliser dans votre application.
1. Si vous souhaitez que l’opération soit exécutée immédiatement, choisissez **Run (Exécuter)**.
------
#### [ AWS CLI ]
1. Créez un élément dans la table `Music` à l’aide de l’instruction INSERT PartiQL.
```
aws dynamodb execute-statement --statement "INSERT INTO Music \
VALUE \
{'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}"
```
1. Extrayez un élément de la table Music à l’aide de l’instruction SELECT PartiQL.
```
aws dynamodb execute-statement --statement "SELECT * FROM Music \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
1. Créez un élément dans la table `Music` à l’aide de l’instruction UPDATE PartiQL.
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET AwardsWon=1 \
SET AwardDetail={'Grammys':[2020, 2018]} \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
Ajoutez une valeur de liste pour un élément dans la table `Music`.
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
Supprimez une valeur de liste pour un élément dans la table `Music`.
```
aws dynamodb execute-statement --statement "UPDATE Music \
REMOVE AwardDetail.Grammys[2] \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
Ajoutez un nouveau membre de mappage pour un élément dans la table `Music`.
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET AwardDetail.BillBoard=[2020] \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
Ajoutez un nouvel attribut d’ensemble de chaînes pour un élément dans la table `Music`.
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET BandMembers =<<'member1', 'member2'>> \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
Mettez à jour un attribut d’ensemble de chaînes pour un élément dans la table `Music`.
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET BandMembers =set_add(BandMembers, <<'newmember'>>) \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
1. Supprimez un élément de la table `Music` à l’aide de l’instruction PartiQL DELETE.
```
aws dynamodb execute-statement --statement "DELETE FROM Music \
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
```
------
#### [ Java ]
```
import java.util.ArrayList;
import java.util.List;
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import software.amazon.dynamodb.AmazonDynamoDB;
import software.amazon.dynamodb.AmazonDynamoDBClientBuilder;
import software.amazon.dynamodb.model.AttributeValue;
import software.amazon.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.dynamodb.model.ExecuteStatementRequest;
import software.amazon.dynamodb.model.ExecuteStatementResult;
import software.amazon.dynamodb.model.InternalServerErrorException;
import software.amazon.dynamodb.model.ItemCollectionSizeLimitExceededException;
import software.amazon.dynamodb.model.ProvisionedThroughputExceededException;
import software.amazon.dynamodb.model.RequestLimitExceededException;
import software.amazon.dynamodb.model.ResourceNotFoundException;
import software.amazon.dynamodb.model.TransactionConflictException;
public class DynamoDBPartiQGettingStarted {
public static void main(String[] args) {
// Create the DynamoDB Client with the region you want
AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-1");
try {
// Create ExecuteStatementRequest
ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest();
List parameters= getPartiQLParameters();
//Create an item in the Music table using the INSERT PartiQL statement
processResults(executeStatementRequest(dynamoDB, "INSERT INTO Music value {'Artist':?,'SongTitle':?}", parameters));
//Retrieve an item from the Music table using the SELECT PartiQL statement.
processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters));
//Update an item in the Music table using the UPDATE PartiQL statement.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist=? and SongTitle=?", parameters));
//Add a list value for an item in the Music table.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) where Artist=? and SongTitle=?", parameters));
//Remove a list value for an item in the Music table.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music REMOVE AwardDetail.Grammys[2] where Artist=? and SongTitle=?", parameters));
//Add a new map member for an item in the Music table.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music set AwardDetail.BillBoard=[2020] where Artist=? and SongTitle=?", parameters));
//Add a new string set attribute for an item in the Music table.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =<<'member1', 'member2'>> where Artist=? and SongTitle=?", parameters));
//update a string set attribute for an item in the Music table.
processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =set_add(BandMembers, <<'newmember'>>) where Artist=? and SongTitle=?", parameters));
//Retrieve an item from the Music table using the SELECT PartiQL statement.
processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters));
//delete an item from the Music Table
processResults(executeStatementRequest(dynamoDB, "DELETE FROM Music where Artist=? and SongTitle=?", parameters));
} catch (Exception e) {
handleExecuteStatementErrors(e);
}
}
private static AmazonDynamoDB createDynamoDbClient(String region) {
return AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
}
private static List getPartiQLParameters() {
List parameters = new ArrayList();
parameters.add(new AttributeValue("Acme Band"));
parameters.add(new AttributeValue("PartiQL Rocks"));
return parameters;
}
private static ExecuteStatementResult executeStatementRequest(AmazonDynamoDB client, String statement, List parameters ) {
ExecuteStatementRequest request = new ExecuteStatementRequest();
request.setStatement(statement);
request.setParameters(parameters);
return client.executeStatement(request);
}
private static void processResults(ExecuteStatementResult executeStatementResult) {
System.out.println("ExecuteStatement successful: "+ executeStatementResult.toString());
}
// Handles errors during ExecuteStatement execution. Use recommendations in error messages below to add error handling specific to
// your application use-case.
private static void handleExecuteStatementErrors(Exception exception) {
try {
throw exception;
} catch (ConditionalCheckFailedException ccfe) {
System.out.println("Condition check specified in the operation failed, review and update the condition " +
"check before retrying. Error: " + ccfe.getErrorMessage());
} catch (TransactionConflictException tce) {
System.out.println("Operation was rejected because there is an ongoing transaction for the item, generally " +
"safe to retry with exponential back-off. Error: " + tce.getErrorMessage());
} catch (ItemCollectionSizeLimitExceededException icslee) {
System.out.println("An item collection is too large, you\'re using Local Secondary Index and exceeded " +
"size limit of items per partition key. Consider using Global Secondary Index instead. Error: " + icslee.getErrorMessage());
} catch (Exception e) {
handleCommonErrors(e);
}
}
private static void handleCommonErrors(Exception exception) {
try {
throw exception;
} catch (InternalServerErrorException isee) {
System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage());
} catch (RequestLimitExceededException rlee) {
System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " +
"retrying. Error: " + rlee.getErrorMessage());
} catch (ProvisionedThroughputExceededException ptee) {
System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " +
"Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " +
ptee.getErrorMessage());
} catch (ResourceNotFoundException rnfe) {
System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage());
} catch (AmazonServiceException ase) {
System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " +
"service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " +
"configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage());
} catch (AmazonClientException ace) {
System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " +
"service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+
"Error: " + ace.getMessage());
} catch (Exception e) {
System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage());
}
}
}
```
------
## Utilisation d'instructions paramétrées
Au lieu d'intégrer des valeurs directement dans une chaîne d'instruction PartiQL, vous pouvez utiliser des espaces réservés en forme de point d'interrogation `?` () et fournir les valeurs séparément dans le champ. `Parameters` Chacun `?` est remplacé par la valeur de paramètre correspondante, dans l'ordre dans lequel ils sont fournis.
L'utilisation d'instructions paramétrées est une bonne pratique car elle sépare la structure des instructions des valeurs des données, ce qui facilite la lecture et la réutilisation des instructions. Cela évite également d'avoir à formater et à ignorer manuellement les valeurs d'attribut dans la chaîne de déclaration.
Les instructions paramétrées sont prises en charge dans les `ExecuteStatement` opérations`BatchExecuteStatement`, et`ExecuteTransaction`.
Les exemples suivants extraient un élément de la `Music` table à l'aide de valeurs paramétrées pour la clé de partition et la clé de tri.
------
#### [ AWS CLI parameterized ]
```
aws dynamodb execute-statement \
--statement "SELECT * FROM \"Music\" WHERE Artist=? AND SongTitle=?" \
--parameters '[{"S": "Acme Band"}, {"S": "PartiQL Rocks"}]'
```
------
#### [ Java parameterized ]
```
List parameters = new ArrayList<>();
parameters.add(new AttributeValue("Acme Band"));
parameters.add(new AttributeValue("PartiQL Rocks"));
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withStatement("SELECT * FROM Music WHERE Artist=? AND SongTitle=?")
.withParameters(parameters);
ExecuteStatementResult result = dynamoDB.executeStatement(request);
```
------
#### [ Python parameterized ]
```
response = dynamodb_client.execute_statement(
Statement="SELECT * FROM Music WHERE Artist=? AND SongTitle=?",
Parameters=[
{'S': 'Acme Band'},
{'S': 'PartiQL Rocks'}
]
)
```
------
**Note**
L'exemple Java présenté dans la section de démarrage précédente utilise des instructions paramétrées dans l'ensemble. La `getPartiQLParameters()` méthode crée la liste des paramètres, et chaque instruction utilise des `?` espaces réservés au lieu de valeurs intégrées.
# Types de données PartiQL pour DynamoDB
Le tableau suivant répertorie les types de données que vous pouvez utiliser avec PartiQL pour DynamoDB.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/ql-reference.data-types.html)
## Exemples
L’instruction suivante montre comment insérer les types de données suivants : `String`, `Number`, `Map`, `List`, `Number Set` et `String Set`.
```
INSERT INTO TypesTable value {'primarykey':'1',
'NumberType':1,
'MapType' : {'entryname1': 'value', 'entryname2': 4},
'ListType': [1,'stringval'],
'NumberSetType':<<1,34,32,4.5>>,
'StringSetType':<<'stringval','stringval2'>>
}
```
L’instruction suivante montre comment insérer de nouveaux éléments dans les types `Map`, `List`, `Number Set` et `String Set`, et modifier la valeur d’un type `Number`.
```
UPDATE TypesTable
SET NumberType=NumberType + 100
SET MapType.NewMapEntry=[2020, 'stringvalue', 2.4]
SET ListType = LIST_APPEND(ListType, [4, <<'string1', 'string2'>>])
SET NumberSetType= SET_ADD(NumberSetType, <<345, 48.4>>)
SET StringSetType = SET_ADD(StringSetType, <<'stringsetvalue1', 'stringsetvalue2'>>)
WHERE primarykey='1'
```
L’instruction suivante montre comment supprimer des éléments des types `Map`, `List`, `Number Set` et `String Set`, et modifier la valeur d’un type `Number`.
```
UPDATE TypesTable
SET NumberType=NumberType - 1
REMOVE ListType[1]
REMOVE MapType.NewMapEntry
SET NumberSetType = SET_DELETE( NumberSetType, <<345>>)
SET StringSetType = SET_DELETE( StringSetType, <<'stringsetvalue1'>>)
WHERE primarykey='1'
```
Pour plus d’informations, consultez [Types de données DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes).
# Instructions PartiQL pour DynamoDB
Amazon DynamoDB prend en charge les instructions PartiQL suivantes.
**Note**
DynamoDB ne prend pas en charge toutes les instructions PartiQL.
Cette référence fournit des exemples de syntaxe de base et d'utilisation des instructions partiQL que vous exécutez manuellement à l'aide de la AWS CLI commande or. APIs
Le *langage de manipulation des données* (Data manipulation language, DML) est l’ensemble d’instructions PartiQL que vous utilisez pour gérer les données dans des tables DynamoDB. Vous utilisez des instructions DML pour ajouter, modifier ou supprimer des données dans une table.
Les instructions DML et de langage de requête prises en charge sont les suivantes :
+ [Instructions PartiQL de sélection pour DynamoDB](ql-reference.select.md)
+ [Instructions de mise à jour de PartiQL pour DynamoDB](ql-reference.update.md)
+ [Instructions d’insertion de PartiQL pour DynamoDB](ql-reference.insert.md)
+ [Instructions de suppression de PartiQL pour DynamoDB](ql-reference.delete.md)
Les instructions [Exécution de transactions avec PartiQL pour DynamoDB](ql-reference.multiplestatements.transactions.md) et [Exécution d’opérations par lot avec PartiQL pour DynamoDB](ql-reference.multiplestatements.batching.md) sont également prises en charge par PartiQL pour DynamoDB.
# Instructions PartiQL de sélection pour DynamoDB
Utilisez l’instruction `SELECT` pour extraire des données d’une table dans Amazon DynamoDB.
L’utilisation de l’instruction `SELECT` peut entraîner une analyse de table complète si une condition IN avec une clé de partition n’est pas fournie dans la clause WHERE. Une opération d’analyse examine chaque élément en lien avec les valeurs demandées, et peut utiliser tout le débit approvisionné pour une table ou un index volumineux en une seule opération.
Si vous voulez éviter une analyse de table complète dans PartiQL, vous pouvez :
+ Créer vos instructions `SELECT` de façon à ce qu’elle n’entraînent pas d’analyse de table complète en vous assurant que votre [condition de clause WHERE](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html#ql-reference.select.parameters) est configurée en conséquence.
+ Désactiver l’analyse de table complète à l’aide de la politique IAM spécifiée dans [Exemple : autoriser les instructions de sélection et rejeter les instructions d’analyse de table complète dans PartiQL pour DynamoDB](ql-iam.md#access-policy-ql-iam-example6), dans le Manuel du développeur DynamoDB.
Pour plus d’informations, consultez [Bonnes pratiques pour l’interrogation et l’analyse des données](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html) dans le Guide du développeur DynamoDB.
**Topics**
+ [Syntaxe](#ql-reference.select.syntax)
+ [Parameters](#ql-reference.select.parameters)
+ [Exemples](#ql-reference.select.examples)
## Syntaxe
```
SELECT expression [, ...]
FROM table[.index]
[ WHERE condition ] [ [ORDER BY key [DESC|ASC] , ...]
```
## Parameters
***expression***
(Obligatoire) Projection formée à partir du caractère générique `*` ou d’une liste de projection d’un ou de plusieurs noms d’attributs ou chemins d’accès de documents de l’ensemble de résultats. Une expression peut être constituée d’appels à [Utilisation de fonctions PartiQL avec DynamoDB](ql-functions.md) ou de champs modifiés par [Opérateurs arithmétiques, de comparaison et logiques PartiQL pour DynamoDB](ql-operators.md).
***table***
(Obligatoire) Nom de la table à interroger.
***index***
(Facultatif) Nom de l’index à interroger.
Vous devez ajouter des guillemets doubles au nom de la table et au nom de l’index lorsque vous interrogez un index.
```
SELECT *
FROM "TableName"."IndexName"
```
***condition***
(Facultatif) Critères de sélection pour la requête.
Pour s’assurer qu’une instruction `SELECT` n’entraîne pas une analyse de table complète, la condition de clause `WHERE` doit spécifier une clé de partition. Utilisez l’opérateur d’égalité ou IN (DANS).
Par exemple, si vous avez une table `Orders` avec une clé de partition `OrderID` et des attributs autres que de clé, dont une `Address`, les instructions suivantes n’entraînent pas d’analyse de table complète :
```
SELECT *
FROM "Orders"
WHERE OrderID = 100
SELECT *
FROM "Orders"
WHERE OrderID = 100 and Address='some address'
SELECT *
FROM "Orders"
WHERE OrderID = 100 or OrderID = 200
SELECT *
FROM "Orders"
WHERE OrderID IN [100, 300, 234]
```
En revanche, les instructions `SELECT` suivantes entraînent une analyse de table complète :
```
SELECT *
FROM "Orders"
WHERE OrderID > 1
SELECT *
FROM "Orders"
WHERE Address='some address'
SELECT *
FROM "Orders"
WHERE OrderID = 100 OR Address='some address'
```
***key***
(Facultatif) Clé de hachage ou clé de tri à utiliser pour ordonner les résultats renvoyés. L’ordre par défaut est croissant (`ASC`). Spécifiez `DESC` si vous voulez que les résultats soient réordonnés dans l’ordre décroissant.
**Note**
Si vous omettez la clause `WHERE`, tous les éléments de la table sont extraits.
## Exemples
La requête suivante renvoie un élément existant de la table `Orders` en spécifiant la clé de partition, `OrderID`, et en utilisant l’opérateur d’égalité.
```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1
```
La requête suivante renvoie tous les éléments de la table `Orders` ayant une clé de partition spécifique, `OrderID`, et leurs valeurs en utilisant l’opérateur OR (OU).
```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1 OR OrderID = 2
```
La requête suivante renvoie tous les éléments de la table `Orders` ayant une clé de partition spécifique, `OrderID`, et leurs valeurs en utilisant l’opérateur IN (DANS). Les résultats renvoyés sont dans l’ordre décroissant de la valeur de leur attribut de clé `OrderID`.
```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID IN [1, 2, 3] ORDER BY OrderID DESC
```
La requête suivante affiche une analyse de table complète qui renvoie tous les éléments de la table `Orders` dont la valeur `Total` est supérieure à 500, où `Total` est un attribut autre que de clé.
```
SELECT OrderID, Total
FROM "Orders"
WHERE Total > 500
```
La requête suivante affiche une analyse de table complète qui renvoie tous les éléments de la table `Orders`dans une plage `Total` spécifique, en utilisant l’opérateur IN (DANS) et un attribut autre que de clé `Total`.
```
SELECT OrderID, Total
FROM "Orders"
WHERE Total IN [500, 600]
```
La requête suivante affiche une analyse de table complète qui renvoie tous les éléments de la table `Orders`dans une plage `Total` spécifique, en utilisant l’opérateur BETWEEN (ENTRE) et un attribut autre que de clé `Total`.
```
SELECT OrderID, Total
FROM "Orders"
WHERE Total BETWEEN 500 AND 600
```
La requête suivante renvoie la première date à laquelle un Firestick a été utilisé, en spécifiant la clé de partition `CustomerID` et une clé de tri `MovieID` dans la condition de clause WHERE, et en utilisant des chemins d’accès de document dans la clause SELECT.
```
SELECT Devices.FireStick.DateWatched[0]
FROM WatchList
WHERE CustomerID= 'C1' AND MovieID= 'M1'
```
La requête suivante affiche une analyse de table complète qui renvoie la liste des éléments pour lesquels un Firestick a été utilisé pour la première fois après le 24/12/19, en utilisant des chemins de document dans la condition de la clause WHERE.
```
SELECT Devices
FROM WatchList
WHERE Devices.FireStick.DateWatched[0] >= '12/24/19'
```
# Instructions de mise à jour de PartiQL pour DynamoDB
Utilisez l’instruction `UPDATE` pour modifier la valeur d’un ou de plusieurs attributs dans un élément d’une table Amazon DynamoDB.
**Note**
Vous ne pouvez mettre à jour qu’un seul élément à la fois et ne pouvez pas émettre une instruction PartiQL pour DynamoDB qui met à jour plusieurs éléments. Pour plus d’informations sur la mise à jour de plusieurs éléments, consultez [Exécution de transactions avec PartiQL pour DynamoDB](ql-reference.multiplestatements.transactions.md) ou [Exécution d’opérations par lot avec PartiQL pour DynamoDB](ql-reference.multiplestatements.batching.md).
**Topics**
+ [Syntaxe](#ql-reference.update.syntax)
+ [Parameters](#ql-reference.update.parameters)
+ [Valeur renvoyée](#ql-reference.update.return)
+ [Exemples](#ql-reference.update.examples)
## Syntaxe
```
UPDATE table
[SET | REMOVE] path [= data] […]
WHERE condition [RETURNING returnvalues]
::= [ALL OLD | MODIFIED OLD | ALL NEW | MODIFIED NEW] *
```
## Parameters
***table***
(Obligatoire) Table contenant les données à modifier.
***path***
(Obligatoire) Nom d’attribut ou chemin d’accès de document à créer ou à modifier.
***data***
(Obligatoire) Valeur d’attribut ou résultat d’une opération.
Opérations prises en charge à utiliser avec SET :
+ LIST\$1APPEND : ajoute une valeur à un type de liste.
+ SET\$1ADD : ajoute une valeur à un ensemble de nombres ou de chaînes.
+ SET\$1DELETE : supprime une valeur d’un ensemble de nombres ou de chaînes.
***condition***
(Obligatoire) Critères de sélection de l’élément à modifier. Le résultat de cette condition doit être une seule valeur de clé primaire.
***returnvalues***
(Facultatif) Utilisez `returnvalues` si vous souhaitez obtenir les attributs de l’élément avant ou après sa mise à jour. Les valeurs valides sont :
+ `ALL OLD *` – Renvoie tous les attributs de l’élément avant l’opération de mise à jour.
+ `MODIFIED OLD *` – Renvoie uniquement les attributs mis à jour avant l’opération de mise à jour.
+ `ALL NEW *` – Renvoie tous les attributs de l’élément après l’opération de mise à jour.
+ `MODIFIED NEW *` – Renvoie uniquement les attributs mis à jour après l’opération `UpdateItem`.
## Valeur renvoyée
Cette instruction ne renvoie de valeur que si le paramètre `returnvalues` est spécifié.
**Note**
Si la clause WHERE de l’instruction UPDATE ne produit le résultat true pour aucun élément de la table DynamoDB, `ConditionalCheckFailedException` est renvoyé.
## Exemples
Mettez à jour une valeur d’attribut d’un élément existant. Si l’attribut n’existe pas, il est créé.
La requête suivante met à jour un élément dans la table `"Music"` en ajoutant un attribut de type Number (`AwardsWon`) et un attribut de type Map (`AwardDetail`).
```
UPDATE "Music"
SET AwardsWon=1
SET AwardDetail={'Grammys':[2020, 2018]}
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
Vous pouvez ajouter `RETURNING ALL OLD *` pour renvoyer les attributs tels qu’ils apparaissaient avant l’opération `Update`.
```
UPDATE "Music"
SET AwardsWon=1
SET AwardDetail={'Grammys':[2020, 2018]}
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL OLD *
```
Ceci renvoie les informations suivantes :
```
{
"Items": [
{
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "PartiQL Rocks"
}
}
]
}
```
Vous pouvez ajouter `RETURNING ALL NEW *` pour renvoyer les attributs tels qu’ils sont apparus après l’opération `Update`.
```
UPDATE "Music"
SET AwardsWon=1
SET AwardDetail={'Grammys':[2020, 2018]}
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL NEW *
```
Ceci renvoie les informations suivantes :
```
{
"Items": [
{
"AwardDetail": {
"M": {
"Grammys": {
"L": [
{
"N": "2020"
},
{
"N": "2018"
}
]
}
}
},
"AwardsWon": {
"N": "1"
}
}
]
}
```
La requête suivante met à jour un élément dans la table `"Music"` en effectuant un ajout à une liste `AwardDetail.Grammys`.
```
UPDATE "Music"
SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016])
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
La requête suivante met à jour un élément dans la table `"Music"` en effectuant une suppression d’une liste `AwardDetail.Grammys`.
```
UPDATE "Music"
REMOVE AwardDetail.Grammys[2]
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
La requête suivante met à jour un élément dans la table `"Music"` en ajoutant `BillBoard` au mappage `AwardDetail`.
```
UPDATE "Music"
SET AwardDetail.BillBoard=[2020]
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
La requête suivante met à jour un élément dans la table `"Music"` en ajoutant l’attribut d’ensemble de chaînes `BandMembers`.
```
UPDATE "Music"
SET BandMembers =<<'member1', 'member2'>>
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
La requête suivante met à jour un élément dans la table `"Music"` en ajoutant `newbandmember` à l’ensemble de chaînes `BandMembers`.
```
UPDATE "Music"
SET BandMembers =set_add(BandMembers, <<'newbandmember'>>)
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```
# Instructions de suppression de PartiQL pour DynamoDB
Utilisez l’instruction `DELETE` pour supprimer un élément existant de votre table Amazon DynamoDB.
**Note**
Vous ne pouvez supprimer qu’un seul élément à la fois. Vous ne pouvez pas émettre une seule instruction PartiQL pour DynamoDB qui supprime plusieurs éléments. Pour plus d’informations sur la suppression de plusieurs éléments, consultez [Exécution de transactions avec PartiQL pour DynamoDB](ql-reference.multiplestatements.transactions.md) ou [Exécution d’opérations par lot avec PartiQL pour DynamoDB](ql-reference.multiplestatements.batching.md).
**Topics**
+ [Syntaxe](#ql-reference.delete.syntax)
+ [Parameters](#ql-reference.delete.parameters)
+ [Valeur renvoyée](#ql-reference.delete.return)
+ [Exemples](#ql-reference.delete.examples)
## Syntaxe
```
DELETE FROM table
WHERE condition [RETURNING returnvalues]
::= ALL OLD *
```
## Parameters
***table***
(Obligatoire) Table DynamoDB contenant l’élément à supprimer.
***condition***
(Obligatoire) Critères de sélection de l’élément à supprimer. Le résultat de cette condition doit être une seule valeur de clé primaire.
***returnvalues***
(Facultatif) Utilisez `returnvalues` si vous souhaitez obtenir les attributs de l’élément avant sa suppression. Les valeurs valides sont :
+ `ALL OLD *` – Le contenu de l’ancien élément est renvoyé.
## Valeur renvoyée
Cette instruction ne renvoie de valeur que si le paramètre `returnvalues` est spécifié.
**Note**
Si la table DynamoDB ne contient aucun élément dont la même clé primaire est la même que celle de l’élément pour lequel l’instruction DELETE est émise, le résultat SUCCESS est renvoyé avec 0 élément supprimé. Si la table contient un élément avec la même clé primaire, mais que le résultat de la condition dans la clause WHERE de l’instruction DELETE est false (faux), l’erreur `ConditionalCheckFailedException` est renvoyée.
## Exemples
La requête suivante interroge un élément dans la table `"Music"`.
```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks'
```
Vous pouvez ajouter le paramètre `RETURNING ALL OLD *` pour renvoyer les données supprimées.
```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks' RETURNING ALL OLD *
```
L’instruction `Delete` renvoie désormais ce qui suit :
```
{
"Items": [
{
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "PartiQL Rocks"
}
}
]
}
```
# Instructions d’insertion de PartiQL pour DynamoDB
Utilisez l’instruction `INSERT` pour ajouter un élément à une table dans Amazon DynamoDB.
**Note**
Vous ne pouvez insérer qu’un seul élément à la fois et ne pouvez pas émettre une instruction PartiQL pour DynamoDB qui insère plusieurs éléments. Pour plus d’informations sur l’insertion de plusieurs éléments, consultez [Exécution de transactions avec PartiQL pour DynamoDB](ql-reference.multiplestatements.transactions.md) ou [Exécution d’opérations par lot avec PartiQL pour DynamoDB](ql-reference.multiplestatements.batching.md).
**Topics**
+ [Syntaxe](#ql-reference.insert.syntax)
+ [Parameters](#ql-reference.insert.parameters)
+ [Valeur renvoyée](#ql-reference.insert.return)
+ [Exemples](#ql-reference.insert.examples)
## Syntaxe
Insérez un seul élément.
```
INSERT INTO table VALUE item
```
## Parameters
***table***
(Obligatoire) Table dans laquelle vous souhaitez insérer les données. La table doit déjà exister.
***item***
(Obligatoire) Elément DynamoDB valide représenté sous la forme d’un [Tuple PartiqL](https://partiql.org/docs.html). Vous devez spécifier *un seul* élément. Chaque nom d’attribut dans l’élément est sensible à la casse et peut être indiqué par des *apostrophes* (`'...'`) dans PartiQL.
Les valeurs de chaîne sont également indiquées par des *apostrophes* (`'...'`) dans PartiQL.
## Valeur renvoyée
Cette instruction ne renvoie aucune valeur.
**Note**
Si la table DynamoDB contient déjà un élément avec la même clé primaire que la clé primaire de l’élément inséré, l’erreur `DuplicateItemException` est renvoyée.
## Exemples
```
INSERT INTO "Music" value {'Artist' : 'Acme Band','SongTitle' : 'PartiQL Rocks'}
```
# Utilisation de fonctions PartiQL avec DynamoDB
PartiQL dans Amazon DynamoDB prend en charge les variantes intégrées suivantes des fonctions standard SQL.
**Note**
Les fonctions SQL qui ne figurent pas dans cette liste ne sont actuellement pas prises en charge dans DynamoDB.
## Fonctions d’agrégation
+ [Utilisation de la fonction SIZE avec PartiQL pour Amazon DynamoDB](ql-functions.size.md)
## Fonctions conditionnelles
+ [Utilisation de la fonction EXISTS avec PartiQL pour DynamoDB](ql-functions.exists.md)
+ [Utilisation de la fonction ATTRIBUTE\$1TYPE avec PartiQL pour DynamoDB](ql-functions.attribute_type.md)
+ [Utilisation de la fonction BEGINS\$1WITH avec PartiQL pour DynamoDB](ql-functions.beginswith.md)
+ [Utilisation de la fonction CONTAINS avec PartiQL pour DynamoDB](ql-functions.contains.md)
+ [Utilisation de la fonction MISSING avec PartiQL pour DynamoDB](ql-functions.missing.md)
# Utilisation de la fonction EXISTS avec PartiQL pour DynamoDB
Vous pouvez utiliser la fonction EXISTS pour effectuer la même opération que la fonction `ConditionCheck` dans l’API [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems). Vous ne pouvez utiliser la fonction EXISTS que dans les transactions.
Pour une valeur donnée, la fonction renvoie `TRUE` si la valeur est une collection non vide. Sinon, la valeur renvoyée est `FALSE`.
**Note**
Vous ne pouvez utiliser cette fonction que dans les opérations transactionnelles.
## Syntaxe
```
EXISTS ( statement )
```
## Arguments
*statement*
(Obligatoire) Instruction SELECT que la fonction évalue.
L’instruction SELECT doit spécifier une clé primaire complète et une autre condition.
## Type de retour
`bool`
## Exemples
```
EXISTS(
SELECT * FROM "Music"
WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks')
```
# Utilisation de la fonction BEGINS\$1WITH avec PartiQL pour DynamoDB
La fonction renvoie `TRUE` si l’attribut spécifié commence par une sous-chaîne particulière.
## Syntaxe
```
begins_with(path, value )
```
## Arguments
*path*
(Obligatoire) Chemin d’accès du nom d’attribut ou du document à utiliser.
*valeur*
(Obligatoire) Chaîne à rechercher.
## Type de retour
`bool`
## Exemples
```
SELECT * FROM "Orders" WHERE "OrderID"=1 AND begins_with("Address", '7834 24th')
```
# Utilisation de la fonction MISSING avec PartiQL pour DynamoDB
La fonction renvoie `TRUE` si l’élément ne contient pas l’attribut spécifié. Seuls des opérateurs d’égalité et d’inégalité peuvent être utilisés avec cette fonction.
## Syntaxe
```
attributename IS | IS NOT MISSING
```
## Arguments
*attributename*
(Obligatoire) Nom d’attribut à rechercher.
## Type de retour
`bool`
## Exemples
```
SELECT * FROM Music WHERE "Awards" is MISSING
```
# Utilisation de la fonction ATTRIBUTE\$1TYPE avec PartiQL pour DynamoDB
La fonction renvoie `TRUE` si l’attribut dans le chemin d’accès spécifié est d’un type de données particulier.
## Syntaxe
```
attribute_type( attributename, type )
```
## Arguments
*attributename*
(Obligatoire) Nom d’attribut à utiliser.
*type*
(Obligatoire) Type d’attribut à vérifier. Pour obtenir la liste des valeurs valides, consultez [attribute\$1type](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) DynamoDB.
## Type de retour
`bool`
## Exemples
```
SELECT * FROM "Music" WHERE attribute_type("Artist", 'S')
```
# Utilisation de la fonction CONTAINS avec PartiQL pour DynamoDB
La fonction renvoie `TRUE` si l’attribut spécifié par le chemin d’accès est l’un des attributs suivants :
+ Une chaîne contenant une sous-chaîne particulière.
+ Un ensemble contenant un élément particulier.
Pour plus d’informations, consultez la fonction DynamoDB [contains](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
## Syntaxe
```
contains( path, substring )
```
## Arguments
*path*
(Obligatoire) Chemin d’accès du nom d’attribut ou du document à utiliser.
*substring*
(Obligatoire) Sous-chaîne d’attribut ou membre d’ensemble à vérifier. Pour plus d’informations, consultez la fonction DynamoDB [contains](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
## Type de retour
`bool`
## Exemples
```
SELECT * FROM "Orders" WHERE "OrderID"=1 AND contains("Address", 'Kirkland')
```
# Utilisation de la fonction SIZE avec PartiQL pour Amazon DynamoDB
Renvoie un nombre représentant la taille en octets d’un attribut. Les types de données valides à utiliser avec la fonction Size sont les suivants. Pour plus d’informations, consultez la fonction DynamoDB [size](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
## Syntaxe
```
size( path)
```
## Arguments
*path*
(Obligatoire) Chemin d’accès du nom d’attribut ou du document à utiliser.
Pour les types pris en charge, consultez la fonction DynamoDB [size](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
## Type de retour
`int`
## Exemples
```
SELECT * FROM "Orders" WHERE "OrderID"=1 AND size("Image") >300
```
# Opérateurs arithmétiques, de comparaison et logiques PartiQL pour DynamoDB
PartiQL dans Amazon DynamoDB prend en charge les [opérateurs standard SQL](https://www.w3schools.com/sql/sql_operators.asp) suivants.
**Note**
Les opérateurs SQL qui ne figurent pas dans cette liste ne sont actuellement pas pris en charge dans DynamoDB.
## Opérateurs arithmétiques
****
| Opérateur | Description |
| --- | --- |
| \$1 | Addition |
| - | Soustraction |
## Opérateurs de comparaison
****
| Opérateur | Description |
| --- | --- |
| = | Egal à |
| <> | Non égal à |
| \$1= | Non égal à |
| > | Supérieure à |
| < | Inférieur à |
| >= | Supérieur ou égal à |
| <= | Inférieur ou égal à |
## Opérateurs logiques
****
| Opérateur | Description |
| --- | --- |
| AND | TRUE si toutes les conditions séparées par AND sont TRUE |
| BETWEEN | `TRUE` si l’opérande est comprise dans la plage des comparaisons. Cet opérateur inclut les limites inférieure et supérieure des opérandes auxquels vous l’appliquez. |
| IN | `TRUE`si l'opérande est égal à l'une d'une liste d'expressions (au maximum 50 valeurs d'attribut de hachage ou au maximum 100 valeurs d'attributs non clés). Les résultats sont affichés sous forme de pages contenant jusqu'à 10 éléments. Si la `IN` liste contient plus de valeurs, vous devez utiliser les valeurs `NextToken` renvoyées dans la réponse pour récupérer les pages suivantes. |
| IS | TRUE si l’opérande est un type de données PartiQL spécifique, dont NULL ou MISSING |
| NOT | Inverse la valeur d’une expression booléenne donnée |
| OR | TRUE si une ou plusieurs des conditions séparées par OR sont TRUE |
Pour plus d’informations sur l’utilisation des opérateurs logiques, consultez [Comparaisons](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Comparators) et [Évaluations logiques](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.LogicalEvaluations).
# Exécution de transactions avec PartiQL pour DynamoDB
Cette section décrit comment utiliser des transactions avec PartiQL pour DynamoDB. Les transactions PartiQL sont limitées à 100 instructions (actions) au total.
Pour plus d’informations sur les transactions DynamoDB, consultez [Gestion des flux de travail complexes avec les transactions DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html).
**Note**
La transaction entière doit être composée d’instructions de lecture ou d’instructions d’écriture. Vous ne pouvez pas mélanger les deux dans une seule transaction. La fonction EXISTS est une exception. Vous pouvez l'utiliser pour vérifier l'état d'attributs spécifiques de l'article de la même manière que dans le cadre de `ConditionCheck` l'opération [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems)d'API.
**Topics**
+ [Syntaxe](#ql-reference.multiplestatements.transactions.syntax)
+ [Parameters](#ql-reference.multiplestatements.transactions.parameters)
+ [Valeurs renvoyées](#ql-reference.multiplestatements.transactions.return)
+ [Exemples](#ql-reference.multiplestatements.transactions.examples)
## Syntaxe
```
[
{
"Statement":" statement ",
"Parameters":[
{
" parametertype " : " parametervalue "
}, ...]
} , ...
]
```
## Parameters
***statement***
(Obligatoire) Instruction prise en charge PartiQL pour DynamoDB.
La transaction entière doit être composée d’instructions de lecture ou d’instructions d’écriture. Vous ne pouvez pas mélanger les deux dans une seule transaction.
***parametertype***
(Facultatif) Type DynamoDB, si des paramètres ont été utilisés lors de la spécification de l’instruction PartiQL.
***parametervalue***
(Facultatif) Valeur de paramètre si des paramètres ont été utilisés lors de la spécification de l’instruction PartiQL.
## Valeurs renvoyées
Cette instruction ne renvoie aucune valeur pour les opérations d’écriture (INSERT, UPDATE ou DELETE). Toutefois, elle renvoie différentes valeurs pour les opérations de lecture (SELECT) en fonction des conditions spécifiées dans la clause WHERE.
**Note**
Si l’une des opérations singleton INSERT, UPDATE ou DELETE renvoie une erreur, les transactions sont annulées avec l’exception `TransactionCanceledException`, et le code de motif d’annulation inclut les erreurs des opérations singleton individuelles.
## Exemples
L’exemple suivant exécute plusieurs instructions sous forme de transaction.
------
#### [ AWS CLI ]
1. Enregistrez le code JSON suivant dans un fichier nommé partiql.json.
```
[
{
"Statement": "EXISTS(SELECT * FROM \"Music\" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)"
},
{
"Statement": "INSERT INTO Music value {'Artist':?,'SongTitle':'?'}",
"Parameters": [{\"S\": \"Acme Band\"}, {\"S\": \"Best Song\"}]
},
{
"Statement": "UPDATE \"Music\" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'"
}
]
```
1. Dans une invite de commande, exécutez la commande suivante.
```
aws dynamodb execute-transaction --transact-statements file://partiql.json
```
------
#### [ Java ]
```
public class DynamoDBPartiqlTransaction {
public static void main(String[] args) {
// Create the DynamoDB Client with the region you want
AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2");
try {
// Create ExecuteTransactionRequest
ExecuteTransactionRequest executeTransactionRequest = createExecuteTransactionRequest();
ExecuteTransactionResult executeTransactionResult = dynamoDB.executeTransaction(executeTransactionRequest);
System.out.println("ExecuteTransaction successful.");
// Handle executeTransactionResult
} catch (Exception e) {
handleExecuteTransactionErrors(e);
}
}
private static AmazonDynamoDB createDynamoDbClient(String region) {
return AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
}
private static ExecuteTransactionRequest createExecuteTransactionRequest() {
ExecuteTransactionRequest request = new ExecuteTransactionRequest();
// Create statements
List statements = getPartiQLTransactionStatements();
request.setTransactStatements(statements);
return request;
}
private static List getPartiQLTransactionStatements() {
List statements = new ArrayList();
statements.add(new ParameterizedStatement()
.withStatement("EXISTS(SELECT * FROM "Music" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)"));
statements.add(new ParameterizedStatement()
.withStatement("INSERT INTO "Music" value {'Artist':'?','SongTitle':'?'}")
.withParameters(new AttributeValue("Acme Band"),new AttributeValue("Best Song")));
statements.add(new ParameterizedStatement()
.withStatement("UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'"));
return statements;
}
// Handles errors during ExecuteTransaction execution. Use recommendations in error messages below to add error handling specific to
// your application use-case.
private static void handleExecuteTransactionErrors(Exception exception) {
try {
throw exception;
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Cancelled, implies a client issue, fix before retrying. Error: " + tce.getErrorMessage());
} catch (TransactionInProgressException tipe) {
System.out.println("The transaction with the given request token is already in progress, consider changing " +
"retry strategy for this type of error. Error: " + tipe.getErrorMessage());
} catch (IdempotentParameterMismatchException ipme) {
System.out.println("Request rejected because it was retried with a different payload but with a request token that was already used, " +
"change request token for this payload to be accepted. Error: " + ipme.getErrorMessage());
} catch (Exception e) {
handleCommonErrors(e);
}
}
private static void handleCommonErrors(Exception exception) {
try {
throw exception;
} catch (InternalServerErrorException isee) {
System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage());
} catch (RequestLimitExceededException rlee) {
System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " +
"retrying. Error: " + rlee.getErrorMessage());
} catch (ProvisionedThroughputExceededException ptee) {
System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " +
"Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " +
ptee.getErrorMessage());
} catch (ResourceNotFoundException rnfe) {
System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage());
} catch (AmazonServiceException ase) {
System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " +
"service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " +
"configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage());
} catch (AmazonClientException ace) {
System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " +
"service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+
"Error: " + ace.getMessage());
} catch (Exception e) {
System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage());
}
}
}
```
------
L’exemple suivant montre les différentes valeurs renvoyées lorsque DynamoDB lit des éléments avec des conditions différentes spécifiées dans la clause WHERE.
------
#### [ AWS CLI ]
1. Enregistrez le code JSON suivant dans un fichier nommé partiql.json.
```
[
// Item exists and projected attribute exists
{
"Statement": "SELECT * FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'"
},
// Item exists but projected attributes do not exist
{
"Statement": "SELECT non_existent_projected_attribute FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'"
},
// Item does not exist
{
"Statement": "SELECT * FROM "Music" WHERE Artist='No One I Know' and SongTitle='Call You Today'"
}
]
```
1. commande suivante, dans une invite de commande.
```
aws dynamodb execute-transaction --transact-statements file://partiql.json
```
1. La réponse suivante est renvoyée :
```
{
"Responses": [
// Item exists and projected attribute exists
{
"Item": {
"Artist":{
"S": "No One You Know"
},
"SongTitle":{
"S": "Call Me Today"
}
}
},
// Item exists but projected attributes do not exist
{
"Item": {}
},
// Item does not exist
{}
]
}
```
------
# Exécution d’opérations par lot avec PartiQL pour DynamoDB
Cette section décrit comment utiliser des opérations par lot avec PartiQL pour DynamoDB.
**Note**
Le lot entier doit être composé d'instructions de lecture ou d'instructions d'écriture. Vous ne pouvez pas mélanger les deux dans une seule opération par lot.
`BatchExecuteStatement` et `BatchWriteItem` ne peuvent pas exécuter plus de 25 instructions par lot.
`BatchExecuteStatement` utilise `BatchGetItem` ce qui prend une liste de clés primaires dans des instructions séparées.
**Topics**
+ [Syntaxe](#ql-reference.multiplestatements.batching.syntax)
+ [Parameters](#ql-reference.multiplestatements.batching.parameters)
+ [Exemples](#ql-reference.multiplestatements.batching.examples)
## Syntaxe
```
[
{
"Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#9StkWHYTxm7x2AqSXcrfu7' AND sk = 'info'"
},
{
"Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#isC2ChceGbxHgESc4szoTE' AND sk = 'info'"
}
]
```
```
[
{
"Statement":" statement ",
"Parameters":[
{
" parametertype " : " parametervalue "
}, ...]
} , ...
]
```
## Parameters
***statement***
(Obligatoire) Instruction prise en charge PartiQL pour DynamoDB.
+ Le lot entier doit être composé d'instructions de lecture ou d'instructions d'écriture. Vous ne pouvez pas mélanger les deux dans une seule opération par lot.
+ `BatchExecuteStatement` et `BatchWriteItem` ne peuvent pas exécuter plus de 25 instructions par lot.
***parametertype***
(Facultatif) Type DynamoDB, si des paramètres ont été utilisés lors de la spécification de l’instruction PartiQL.
***parametervalue***
(Facultatif) Valeur de paramètre si des paramètres ont été utilisés lors de la spécification de l’instruction PartiQL.
## Exemples
------
#### [ AWS CLI ]
1. Enregistrez le JSON suivant dans un fichier nommé partiql.json
```
[
{
"Statement": "INSERT INTO Music VALUE {'Artist':?,'SongTitle':?}",
"Parameters": [{"S": "Acme Band"}, {"S": "Best Song"}]
},
{
"Statement": "UPDATE Music SET AwardsWon=1, AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'"
}
]
```
1. Dans une invite de commande, exécutez la commande suivante.
```
aws dynamodb batch-execute-statement --statements file://partiql.json
```
------
#### [ Java ]
```
public class DynamoDBPartiqlBatch {
public static void main(String[] args) {
// Create the DynamoDB Client with the region you want
AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2");
try {
// Create BatchExecuteStatementRequest
BatchExecuteStatementRequest batchExecuteStatementRequest = createBatchExecuteStatementRequest();
BatchExecuteStatementResult batchExecuteStatementResult = dynamoDB.batchExecuteStatement(batchExecuteStatementRequest);
System.out.println("BatchExecuteStatement successful.");
// Handle batchExecuteStatementResult
} catch (Exception e) {
handleBatchExecuteStatementErrors(e);
}
}
private static AmazonDynamoDB createDynamoDbClient(String region) {
return AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
}
private static BatchExecuteStatementRequest createBatchExecuteStatementRequest() {
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest();
// Create statements
List statements = getPartiQLBatchStatements();
request.setStatements(statements);
return request;
}
private static List getPartiQLBatchStatements() {
List statements = new ArrayList();
statements.add(new BatchStatementRequest()
.withStatement("INSERT INTO Music value {'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}"));
statements.add(new BatchStatementRequest()
.withStatement("UPDATE Music set AwardDetail.BillBoard=[2020] where Artist='Acme Band' and SongTitle='PartiQL Rocks'"));
return statements;
}
// Handles errors during BatchExecuteStatement execution. Use recommendations in error messages below to add error handling specific to
// your application use-case.
private static void handleBatchExecuteStatementErrors(Exception exception) {
try {
throw exception;
} catch (Exception e) {
// There are no API specific errors to handle for BatchExecuteStatement, common DynamoDB API errors are handled below
handleCommonErrors(e);
}
}
private static void handleCommonErrors(Exception exception) {
try {
throw exception;
} catch (InternalServerErrorException isee) {
System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage());
} catch (RequestLimitExceededException rlee) {
System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " +
"retrying. Error: " + rlee.getErrorMessage());
} catch (ProvisionedThroughputExceededException ptee) {
System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " +
"Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " +
ptee.getErrorMessage());
} catch (ResourceNotFoundException rnfe) {
System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage());
} catch (AmazonServiceException ase) {
System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " +
"service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " +
"configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage());
} catch (AmazonClientException ace) {
System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " +
"service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+
"Error: " + ace.getMessage());
} catch (Exception e) {
System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage());
}
}
}
```
------
# Politiques de sécurité IAM avec PartiQL pour DynamoDB
Les autorisations suivantes sont requises :
+ Pour lire des éléments à l’aide de PartiQL pour DynamoDB, vous devez disposer de l’autorisation `dynamodb:PartiQLSelect` sur la table ou l’index.
+ Pour insérer des éléments à l’aide de PartiQL pour DynamoDB, vous devez disposer de l’autorisation `dynamodb:PartiQLInsert` sur la table ou l’index.
+ Pour mettre à jour des éléments à l’aide de PartiQL pour DynamoDB, vous devez disposer de l’autorisation `dynamodb:PartiQLUpdate` sur la table ou l’index.
+ Pour supprimer des éléments à l’aide de PartiQL pour DynamoDB, vous devez disposer de l’autorisation `dynamodb:PartiQLDelete` sur la table ou l’index.
## Exemple : autoriser toutes les instructions PartiQL pour DynamoDB () sur une table Select/Insert/Update/Delete
La politique IAM suivante accorde les autorisations nécessaires pour exécuter toutes les instructions PartiQL pour DynamoDB sur une table.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLInsert",
"dynamodb:PartiQLUpdate",
"dynamodb:PartiQLDelete",
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music"
]
}
]
}
```
------
## Exemple : Autoriser les instructions PartiQL select pour DynamoDB sur une table
La politique IAM suivante accorde les autorisations nécessaires pour exécuter l’instruction `select` sur une table spécifique.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music"
]
}
]
}
```
------
## Exemple : Autoriser les instructions PartiQL insert pour DynamoDB sur un index
La politique IAM suivante accorde les autorisations nécessaires pour exécuter l’instruction `insert` sur un index spécifique.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLInsert"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music/index/index1"
]
}
]
}
```
------
## Exemple : Autoriser les instructions transactionnelles PartiQL pour DynamoDB sur une table
La politique IAM suivante accorde les autorisations nécessaires pour exécuter uniquement des instructions transactionnelles sur une table spécifique.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLInsert",
"dynamodb:PartiQLUpdate",
"dynamodb:PartiQLDelete",
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music"
],
"Condition":{
"StringEquals":{
"dynamodb:EnclosingOperation":[
"ExecuteTransaction"
]
}
}
}
]
}
```
------
## Exemple : Autoriser les lectures et d’écritures non transactionnelles PartiQL pour DynamoDB, et bloquer les instructions de lectures et d’écritures transactionnelles PartiQL sur une table.
La politique IAM suivante accorde des autorisations pour exécuter des lectures et des écritures non transactionnelles PartiQL pour DynamoDB tout en bloquant les lectures et écritures transactionnelles PartiQL pour DynamoDB.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Deny",
"Action":[
"dynamodb:PartiQLInsert",
"dynamodb:PartiQLUpdate",
"dynamodb:PartiQLDelete",
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music"
],
"Condition":{
"StringEquals":{
"dynamodb:EnclosingOperation":[
"ExecuteTransaction"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLInsert",
"dynamodb:PartiQLUpdate",
"dynamodb:PartiQLDelete",
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/Music"
]
}
]
}
```
------
## Exemple : autoriser les instructions de sélection et rejeter les instructions d’analyse de table complète dans PartiQL pour DynamoDB
La politique IAM suivante accorde des autorisations pour exécuter l’instruction `select` sur une table spécifique tout en bloquant les instructions `select` qui entraînent une analyse de table complète.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Deny",
"Action":[
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/WatchList"
],
"Condition":{
"Bool":{
"dynamodb:FullTableScan":[
"true"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"dynamodb:PartiQLSelect"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/WatchList"
]
}
]
}
```
------
# 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;
}
}
```
# Utilisation des élements : .NET
Vous pouvez utiliser l'API de AWS SDK pour .NET bas niveau pour effectuer des opérations classiques de création, de lecture, de mise à jour et de suppression (CRUD) sur un élément d'une table. Voici les étapes courantes à suivre pour effectuer des opérations CRUD sur des données à l’aide de l’API de bas niveau .NET :
1. Créez une instance de la classe `AmazonDynamoDBClient` (le client).
1. Fournissez les paramètres obligatoires spécifiques à l’opération dans un objet de demande correspondant.
Par exemple, utilisez l’objet de demande `PutItemRequest` lors du chargement d’un élément, et l’objet de demande `GetItemRequest` lors de l’extraction d’un élément existant.
L’objet de demande vous permet de fournir les paramètres obligatoires et facultatifs.
1. Exécutez la méthode appropriée fournie par le client en transmettant l’objet de demande que vous avez créé à l’étape précédente.
Le client `AmazonDynamoDBClient` fournit les méthodes `PutItem`, `GetItem`, `UpdateItem`, et `DeleteItem` pour les opérations CRUD.
**Topics**
+ [Insertion d’un élément](#PutItemLowLevelAPIDotNet)
+ [Obtention d’un élément](#GetItemLowLevelDotNET)
+ [Mise à jour d’un élément](#UpdateItemLowLevelDotNet)
+ [Compteurs atomiques](#AtomicCounterLowLevelDotNet)
+ [Suppression d’un élément](#DeleteMidLevelDotNet)
+ [Écriture par lots : insertion et suppression de plusieurs éléments](#BatchWriteLowLevelDotNet)
+ [Obtention par lots : obtention de plusieurs éléments](#BatchGetLowLevelDotNet)
+ [Exemple : opérations CRUD à l'aide de l'API de AWS SDK pour .NET bas niveau](LowLevelDotNetItemsExample.md)
+ [Exemple : opérations par lots à l'aide de l'API de AWS SDK pour .NET bas niveau](batch-operation-lowlevel-dotnet.md)
+ [Exemple : gestion des attributs de type binaire à l'aide de l'API de AWS SDK pour .NET bas niveau](LowLevelDotNetBinaryTypeExample.md)
## Insertion d’un élément
La méthode `PutItem` charge un élément dans une table. Si l’élément existe, il remplace la totalité de l’élément.
**Note**
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](#UpdateItemLowLevelDotNet).
Pour charger un élément à l’aide de l’API SDK .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires en créant une instance de la classe `PutItemRequest`.
Pour insérer un élément, vous devez fournir le nom de la table et l’élément.
1. Appelez la méthode `PutItem` en fournissant l’objet `PutItemRequest` que vous avez créé à l’étape précédente.
L’exemple de code C\$1 suivant illustre les étapes précédentes. L’exemple charge un élément dans la table `ProductCatalog`.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new PutItemRequest
{
TableName = tableName,
Item = new Dictionary()
{
{ "Id", new AttributeValue { N = "201" }},
{ "Title", new AttributeValue { S = "Book 201 Title" }},
{ "ISBN", new AttributeValue { S = "11-11-11-11" }},
{ "Price", new AttributeValue { S = "20.00" }},
{
"Authors",
new AttributeValue
{ SS = new List{"Author1", "Author2"} }
}
}
};
client.PutItem(request);
```
Dans l’exemple précédent, vous chargez un élément book (livre) qui possède les attributs `Id`, `Title`, `ISBN` et `Authors`. Notez que `Id` est un attribut de type numérique et que tous les autres attributs sont de type String (chaîne). Authors est un ensemble `String`.
### Spécification de paramètres facultatifs
Vous pouvez également fournir des paramètres facultatifs à l’aide de l’objet `PutItemRequest`, comme illustré dans l’exemple C\$1 suivant. L’exemple spécifie les paramètres facultatifs suivants :
+ `ExpressionAttributeNames`, `ExpressionAttributeValues` et `ConditionExpression` spécifient que l’élément peut être remplacé seulement si l’élément existant possède l’attribut ISBN avec une valeur spécifique.
+ Paramètre `ReturnValues` pour demander l’ancien élément dans la réponse.
**Example**
```
var request = new PutItemRequest
{
TableName = tableName,
Item = new Dictionary()
{
{ "Id", new AttributeValue { N = "104" }},
{ "Title", new AttributeValue { S = "Book 104 Title" }},
{ "ISBN", new AttributeValue { S = "444-4444444444" }},
{ "Authors",
new AttributeValue { SS = new List{"Author3"}}}
},
// Optional parameters.
ExpressionAttributeNames = new Dictionary()
{
{"#I", "ISBN"}
},
ExpressionAttributeValues = new Dictionary()
{
{":isbn",new AttributeValue {S = "444-4444444444"}}
},
ConditionExpression = "#I = :isbn"
};
var response = client.PutItem(request);
```
Pour de plus amples informations, veuillez consulter [PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html).
## Obtention d’un élément
La méthode `GetItem` extrait un élément.
**Note**
Vous pouvez extraire plusieurs éléments à l’aide de la méthode `BatchGetItem`. Pour de plus amples informations, veuillez consulter [Obtention par lots : obtention de plusieurs éléments](#BatchGetLowLevelDotNet).
Pour extraire un élément à l’aide de l’API AWS SDK pour .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires en créant une instance de la classe `GetItemRequest`.
Pour obtenir un élément, vous devez fournir le nom de la table et la clé primaire de l’élément.
1. Appelez la méthode `GetItem` en fournissant l’objet `GetItemRequest` que vous avez créé à l’étape précédente.
L’exemple de code C\$1 suivant illustre les étapes précédentes. L’exemple extrait un élément de la table `ProductCatalog`.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new GetItemRequest
{
TableName = tableName,
Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } },
};
var response = client.GetItem(request);
// Check the response.
var result = response.GetItemResult;
var attributeMap = result.Item; // Attribute list in the response.
```
### Spécification de paramètres facultatifs
Vous pouvez également fournir des paramètres facultatifs à l’aide de l’objet `GetItemRequest`, comme illustré dans l’exemple C\$1 suivant. L’exemple spécifie les paramètres facultatifs suivants :
+ Paramètre `ProjectionExpression` pour spécifier les attributs à extraire.
+ Paramètre `ConsistentRead` pour effectuer une lecture fortement cohérente. Pour en savoir plus sur la cohérence de lecture, consultez [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md).
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new GetItemRequest
{
TableName = tableName,
Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } },
// Optional parameters.
ProjectionExpression = "Id, ISBN, Title, Authors",
ConsistentRead = true
};
var response = client.GetItem(request);
// Check the response.
var result = response.GetItemResult;
var attributeMap = result.Item;
```
Pour de plus amples informations, veuillez consulter [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html).
## Mise à jour d’un élément
La méthode `UpdateItem` met à jour un élément existant s’il est présent. L’opération `UpdateItem` vous permet de mettre à jour des valeurs d’attribut existantes, d’ajouter des attributs ou d’en supprimer dans la collection existante. Si l’élément qui possède la clé primaire spécifiée est introuvable, l’opération ajoute un nouvel élément.
L’opération `UpdateItem` suit les directives suivantes :
+ Si l’élément n’existe pas, `UpdateItem` ajoute un nouvel élément à l’aide de la clé primaire spécifiée dans l’entrée.
+ Si l’élément existe, `UpdateItem` applique les mises à jour comme suit :
+ Remplace les valeurs d’attribut existantes par les valeurs figurant dans la mise à jour.
+ Si un attribut que vous fournissez en entrée n’existe pas, l’opération ajoute un nouvel attribut à l’élément.
+ Si l’attribut en entrée a la valeur null, elle supprime l’attribut s’il est présent.
+ Si vous utilisez `ADD` pour `Action`, vous pouvez ajouter des valeurs à un ensemble existant (ensemble de chaînes ou de nombres), ou bien ajouter (utiliser un nombre positif) ou soustraire (utiliser un nombre négatif) mathématiquement de façon à augmenter ou réduire la valeur de l’attribut numérique existant.
**Note**
L’opération `PutItem` peut également effectuer une mise à jour. Pour de plus amples informations, veuillez consulter [Insertion d’un élément](#PutItemLowLevelAPIDotNet). Par exemple, si vous appelez `PutItem` pour charger un élément et que la clé primaire existe, l’opération `PutItem` remplace l’élément entier. Si l’élément existant comporte des attributs non spécifiés dans l’entrée, l’opération `PutItem` supprime ces attributs. Toutefois, l’opération `UpdateItem` ne met à jour que les attributs d’entrée spécifiés. Tous les autres attributs de cet élément demeurent inchangés.
Pour mettre à jour un élément à l’aide de l’API SDK .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires en créant une instance de la classe `UpdateItemRequest`.
Il s’agit de l’objet de demande dans lequel vous décrivez toutes les mises à jour, comme l’ajout, la mise à jour ou la suppression d’attributs. Pour supprimer un attribut, spécifiez son nom avec la valeur null.
1. Appelez la méthode `UpdateItem` en fournissant l’objet `UpdateItemRequest` que vous avez créé à l’étape précédente.
L’exemple de code C\$1 suivant illustre les étapes précédentes. L’exemple de code met à jour un élément book (livre) dans la table `ProductCatalog`. Il ajoute un nouvel auteur à la collection `Authors` et supprime l’attribut `ISBN` existant. Il permet également de réduire le prix d’une unité.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new UpdateItemRequest
{
TableName = tableName,
Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } },
ExpressionAttributeNames = new Dictionary()
{
{"#A", "Authors"},
{"#P", "Price"},
{"#NA", "NewAttribute"},
{"#I", "ISBN"}
},
ExpressionAttributeValues = new Dictionary()
{
{":auth",new AttributeValue { SS = {"Author YY","Author ZZ"}}},
{":p",new AttributeValue {N = "1"}},
{":newattr",new AttributeValue {S = "someValue"}},
},
// This expression does the following:
// 1) Adds two new authors to the list
// 2) Reduces the price
// 3) Adds a new attribute to the item
// 4) Removes the ISBN attribute from the item
UpdateExpression = "ADD #A :auth SET #P = #P - :p, #NA = :newattr REMOVE #I"
};
var response = client.UpdateItem(request);
```
### Spécification de paramètres facultatifs
Vous pouvez également fournir des paramètres facultatifs à l’aide de l’objet `UpdateItemRequest`, comme illustré dans l’exemple C\$1 suivant. Il spécifie les deux paramètres facultatifs suivants :
+ `ExpressionAttributeValues` et `ConditionExpression` pour spécifier que le prix peut être mis à jour seulement s’il est de 20,00.
+ Paramètre `ReturnValues` pour demander l’élément mis à jour dans la réponse.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new UpdateItemRequest
{
Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } },
// Update price only if the current price is 20.00.
ExpressionAttributeNames = new Dictionary()
{
{"#P", "Price"}
},
ExpressionAttributeValues = new Dictionary()
{
{":newprice",new AttributeValue {N = "22"}},
{":currprice",new AttributeValue {N = "20"}}
},
UpdateExpression = "SET #P = :newprice",
ConditionExpression = "#P = :currprice",
TableName = tableName,
ReturnValues = "ALL_NEW" // Return all the attributes of the updated item.
};
var response = client.UpdateItem(request);
```
Pour de plus amples informations, veuillez consulter [UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html).
## 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. Mettez à jour un compteur atomique à l’aide de `updateItem` avec un attribut de type `Number` dans le paramètre `UpdateExpression`, et `ADD` pour `Action`.
L’extrait de code suivant illustre cette action, en incrémentant l’attribut `Quantity` d’une unité.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new UpdateItemRequest
{
Key = new Dictionary() { { "Id", new AttributeValue { N = "121" } } },
ExpressionAttributeNames = new Dictionary()
{
{"#Q", "Quantity"}
},
ExpressionAttributeValues = new Dictionary()
{
{":incr",new AttributeValue {N = "1"}}
},
UpdateExpression = "SET #Q = #Q + :incr",
TableName = tableName
};
var response = client.UpdateItem(request);
```
## Suppression d’un élément
La méthode `DeleteItem` supprime un élément d’une table.
Pour supprimer un élément à l’aide de l’API SDK .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires en créant une instance de la classe `DeleteItemRequest`.
Pour supprimer un élément, le nom de la table et la clé primaire de l’élément sont requis.
1. Appelez la méthode `DeleteItem` en fournissant l’objet `DeleteItemRequest` que vous avez créé à l’étape précédente.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "ProductCatalog";
var request = new DeleteItemRequest
{
TableName = tableName,
Key = new Dictionary() { { "Id", new AttributeValue { N = "201" } } },
};
var response = client.DeleteItem(request);
```
### Spécification de paramètres facultatifs
Vous pouvez également fournir des paramètres facultatifs à l’aide de l’objet `DeleteItemRequest`, comme illustré dans l’exemple de code C\$1 suivant. Il spécifie les deux paramètres facultatifs suivants :
+ `ExpressionAttributeValues`et `ConditionExpression` pour spécifier que l'élément du livre ne peut être supprimé que s'il n'est plus en cours de publication (la valeur de InPublication l'attribut est fausse).
+ Paramètre `ReturnValues` pour demander l’élément supprimé dans la réponse.
**Example**
```
var request = new DeleteItemRequest
{
TableName = tableName,
Key = new Dictionary() { { "Id", new AttributeValue { N = "201" } } },
// Optional parameters.
ReturnValues = "ALL_OLD",
ExpressionAttributeNames = new Dictionary()
{
{"#IP", "InPublication"}
},
ExpressionAttributeValues = new Dictionary()
{
{":inpub",new AttributeValue {BOOL = false}}
},
ConditionExpression = "#IP = :inpub"
};
var response = client.DeleteItem(request);
```
Pour de plus amples informations, veuillez consulter [DeleteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html).
## É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 extraire plusieurs éléments à l’aide de l’API SDK .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Décrivez toutes les opérations d’insertion et de suppression en créant une instance de la classe `BatchWriteItemRequest`.
1. Appelez la méthode `BatchWriteItem` en fournissant l’objet `BatchWriteItemRequest` que vous avez créé à 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 [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html).
L’exemple de code C\$1 suivant illustre les étapes précédentes. L’exemple crée un objet `BatchWriteItemRequest` pour effectuer les opérations d’écriture suivantes :
+ Insérer un élément dans la table `Forum`
+ Insérer et supprimer un élément dans la table `Thread`
Le code exécute `BatchWriteItem` pour effectuer une opération par lots.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string table1Name = "Forum";
string table2Name = "Thread";
var request = new BatchWriteItemRequest
{
RequestItems = new Dictionary>
{
{
table1Name, new List
{
new WriteRequest
{
PutRequest = new PutRequest
{
Item = new Dictionary
{
{ "Name", new AttributeValue { S = "Amazon S3 forum" } },
{ "Threads", new AttributeValue { N = "0" }}
}
}
}
}
} ,
{
table2Name, new List
{
new WriteRequest
{
PutRequest = new PutRequest
{
Item = new Dictionary
{
{ "ForumName", new AttributeValue { S = "Amazon S3 forum" } },
{ "Subject", new AttributeValue { S = "My sample question" } },
{ "Message", new AttributeValue { S = "Message Text." } },
{ "KeywordTags", new AttributeValue { SS = new List { "Amazon S3", "Bucket" } } }
}
}
},
new WriteRequest
{
DeleteRequest = new DeleteRequest
{
Key = new Dictionary()
{
{ "ForumName", new AttributeValue { S = "Some forum name" } },
{ "Subject", new AttributeValue { S = "Some subject" } }
}
}
}
}
}
}
};
response = client.BatchWriteItem(request);
```
Pour obtenir un exemple pratique, consultez [Exemple : opérations par lots à l'aide de l'API de AWS SDK pour .NET bas niveau](batch-operation-lowlevel-dotnet.md).
## 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.
**Note**
Pour récupérer un seul élément, vous pouvez utiliser la méthode `GetItem`.
Pour extraire plusieurs éléments à l’aide de l’API AWS SDK pour .NET de bas niveau, procédez comme suit :
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires en créant une instance de la classe `BatchGetItemRequest`.
Pour extraire plusieurs éléments, le nom de la table et une liste de valeurs de clé primaire sont requis.
1. Appelez la méthode `BatchGetItem` en fournissant l’objet `BatchGetItemRequest` que vous avez créé à l’étape précédente.
1. Traitez la réponse. Vous devez vérifier s’il existe des clés non traitées, ce qui peut se produire si vous atteignez le quota de débit alloué ou en cas d’autre erreur temporaire.
L’exemple de code C\$1 suivant illustre les étapes précédentes. L’exemple extrait les éléments de deux tables : `Forum` et `Thread`. La demande spécifie deux éléments dans la table `Forum` et trois éléments dans la table `Thread`. La réponse inclut des éléments des deux tables. Le code montre comment vous pouvez traiter la réponse.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string table1Name = "Forum";
string table2Name = "Thread";
var request = new BatchGetItemRequest
{
RequestItems = new Dictionary()
{
{ table1Name,
new KeysAndAttributes
{
Keys = new List>()
{
new Dictionary()
{
{ "Name", new AttributeValue { S = "DynamoDB" } }
},
new Dictionary()
{
{ "Name", new AttributeValue { S = "Amazon S3" } }
}
}
}
},
{
table2Name,
new KeysAndAttributes
{
Keys = new List>()
{
new Dictionary()
{
{ "ForumName", new AttributeValue { S = "DynamoDB" } },
{ "Subject", new AttributeValue { S = "DynamoDB Thread 1" } }
},
new Dictionary()
{
{ "ForumName", new AttributeValue { S = "DynamoDB" } },
{ "Subject", new AttributeValue { S = "DynamoDB Thread 2" } }
},
new Dictionary()
{
{ "ForumName", new AttributeValue { S = "Amazon S3" } },
{ "Subject", new AttributeValue { S = "Amazon S3 Thread 1" } }
}
}
}
}
}
};
var response = client.BatchGetItem(request);
// Check the response.
var result = response.BatchGetItemResult;
var responses = result.Responses; // The attribute list in the response.
var table1Results = responses[table1Name];
Console.WriteLine("Items in table {0}" + table1Name);
foreach (var item1 in table1Results.Items)
{
PrintItem(item1);
}
var table2Results = responses[table2Name];
Console.WriteLine("Items in table {1}" + table2Name);
foreach (var item2 in table2Results.Items)
{
PrintItem(item2);
}
// Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error.
Dictionary unprocessedKeys = result.UnprocessedKeys;
foreach (KeyValuePair pair in unprocessedKeys)
{
Console.WriteLine(pair.Key, pair.Value);
}
```
### Spécification de paramètres facultatifs
Vous pouvez également fournir des paramètres facultatifs à l’aide de l’objet `BatchGetItemRequest`, comme illustré dans l’exemple de code C\$1 suivant. L’exemple extrait deux éléments de la table `Forum`. Il spécifie le paramètre facultatif suivant :
+ Paramètre `ProjectionExpression` pour spécifier les attributs à extraire.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string table1Name = "Forum";
var request = new BatchGetItemRequest
{
RequestItems = new Dictionary()
{
{ table1Name,
new KeysAndAttributes
{
Keys = new List>()
{
new Dictionary()
{
{ "Name", new AttributeValue { S = "DynamoDB" } }
},
new Dictionary()
{
{ "Name", new AttributeValue { S = "Amazon S3" } }
}
}
},
// Optional - name of an attribute to retrieve.
ProjectionExpression = "Title"
}
}
};
var response = client.BatchGetItem(request);
```
Pour de plus amples informations, veuillez consulter [BatchGetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html).
# Exemple : opérations CRUD à l'aide de l'API de AWS SDK pour .NET bas niveau
L’exemple de code C\$1 suivant illustre des opérations CRUD sur un élément Amazon DynamoDB. L’exemple ajoute un élément à la table `ProductCatalog`, l’extrait, exécute diverses mises à jour et supprime finalement l’élément. Si vous n’avez pas créé cette table, vous pouvez également la créer 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 .NET](AppendixSampleDataCodeDotNET.md).
Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelItemCRUDExample
{
private static string tableName = "ProductCatalog";
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
try
{
CreateItem();
RetrieveItem();
// Perform various updates.
UpdateMultipleAttributes();
UpdateExistingAttributeConditionally();
// Delete item.
DeleteItem();
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (Exception e)
{
Console.WriteLine(e.Message);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
}
private static void CreateItem()
{
var request = new PutItemRequest
{
TableName = tableName,
Item = new Dictionary()
{
{ "Id", new AttributeValue {
N = "1000"
}},
{ "Title", new AttributeValue {
S = "Book 201 Title"
}},
{ "ISBN", new AttributeValue {
S = "11-11-11-11"
}},
{ "Authors", new AttributeValue {
SS = new List{"Author1", "Author2" }
}},
{ "Price", new AttributeValue {
N = "20.00"
}},
{ "Dimensions", new AttributeValue {
S = "8.5x11.0x.75"
}},
{ "InPublication", new AttributeValue {
BOOL = false
} }
}
};
client.PutItem(request);
}
private static void RetrieveItem()
{
var request = new GetItemRequest
{
TableName = tableName,
Key = new Dictionary()
{
{ "Id", new AttributeValue {
N = "1000"
} }
},
ProjectionExpression = "Id, ISBN, Title, Authors",
ConsistentRead = true
};
var response = client.GetItem(request);
// Check the response.
var attributeList = response.Item; // attribute list in the response.
Console.WriteLine("\nPrinting item after retrieving it ............");
PrintItem(attributeList);
}
private static void UpdateMultipleAttributes()
{
var request = new UpdateItemRequest
{
Key = new Dictionary()
{
{ "Id", new AttributeValue {
N = "1000"
} }
},
// Perform the following updates:
// 1) Add two new authors to the list
// 1) Set a new attribute
// 2) Remove the ISBN attribute
ExpressionAttributeNames = new Dictionary()
{
{"#A","Authors"},
{"#NA","NewAttribute"},
{"#I","ISBN"}
},
ExpressionAttributeValues = new Dictionary()
{
{":auth",new AttributeValue {
SS = {"Author YY", "Author ZZ"}
}},
{":new",new AttributeValue {
S = "New Value"
}}
},
UpdateExpression = "ADD #A :auth SET #NA = :new REMOVE #I",
TableName = tableName,
ReturnValues = "ALL_NEW" // Give me all attributes of the updated item.
};
var response = client.UpdateItem(request);
// Check the response.
var attributeList = response.Attributes; // attribute list in the response.
// print attributeList.
Console.WriteLine("\nPrinting item after multiple attribute update ............");
PrintItem(attributeList);
}
private static void UpdateExistingAttributeConditionally()
{
var request = new UpdateItemRequest
{
Key = new Dictionary()
{
{ "Id", new AttributeValue {
N = "1000"
} }
},
ExpressionAttributeNames = new Dictionary()
{
{"#P", "Price"}
},
ExpressionAttributeValues = new Dictionary()
{
{":newprice",new AttributeValue {
N = "22.00"
}},
{":currprice",new AttributeValue {
N = "20.00"
}}
},
// This updates price only if current price is 20.00.
UpdateExpression = "SET #P = :newprice",
ConditionExpression = "#P = :currprice",
TableName = tableName,
ReturnValues = "ALL_NEW" // Give me all attributes of the updated item.
};
var response = client.UpdateItem(request);
// Check the response.
var attributeList = response.Attributes; // attribute list in the response.
Console.WriteLine("\nPrinting item after updating price value conditionally ............");
PrintItem(attributeList);
}
private static void DeleteItem()
{
var request = new DeleteItemRequest
{
TableName = tableName,
Key = new Dictionary()
{
{ "Id", new AttributeValue {
N = "1000"
} }
},
// Return the entire item as it appeared before the update.
ReturnValues = "ALL_OLD",
ExpressionAttributeNames = new Dictionary()
{
{"#IP", "InPublication"}
},
ExpressionAttributeValues = new Dictionary()
{
{":inpub",new AttributeValue {
BOOL = false
}}
},
ConditionExpression = "#IP = :inpub"
};
var response = client.DeleteItem(request);
// Check the response.
var attributeList = response.Attributes; // Attribute list in the response.
// Print item.
Console.WriteLine("\nPrinting item that was just deleted ............");
PrintItem(attributeList);
}
private static void PrintItem(Dictionary attributeList)
{
foreach (KeyValuePair kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]")
);
}
Console.WriteLine("************************************************");
}
}
}
```
# Exemple : opérations par lots à l'aide de l'API de AWS SDK pour .NET bas niveau
**Topics**
+ [Exemple : opération d'écriture par lots à l'aide de l'API de AWS SDK pour .NET bas niveau](#batch-write-low-level-dotnet)
+ [Exemple : opération Batch get à l'aide de l'API de AWS SDK pour .NET bas niveau](#LowLevelDotNetBatchGet)
Cette section fournit des exemples d’opérations par lots, *écriture par lots* et *obtention par lots*, qu’Amazon DynamoDB prend en charge.
## Exemple : opération d'écriture par lots à l'aide de l'API de AWS SDK pour .NET bas niveau
L’exemple de code C\$1 suivant exécute les opérations d’insertion et de suppression 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, DynamoDB `BatchWriteItem` limite la taille d’une demande d’écriture par lots et le nombre d’opérations d’insertion et de suppression dans une même opération d’écriture par lots. Pour de plus amples informations, veuillez consulter [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html). 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. Vous pouvez également créer ces exemples de 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 .NET](AppendixSampleDataCodeDotNET.md).
Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
namespace com.amazonaws.codesamples
{
class LowLevelBatchWrite
{
private static string table1Name = "Forum";
private static string table2Name = "Thread";
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
try
{
TestBatchWrite();
}
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
private static void TestBatchWrite()
{
var request = new BatchWriteItemRequest
{
ReturnConsumedCapacity = "TOTAL",
RequestItems = new Dictionary>
{
{
table1Name, new List
{
new WriteRequest
{
PutRequest = new PutRequest
{
Item = new Dictionary
{
{ "Name", new AttributeValue {
S = "S3 forum"
} },
{ "Threads", new AttributeValue {
N = "0"
}}
}
}
}
}
},
{
table2Name, new List
{
new WriteRequest
{
PutRequest = new PutRequest
{
Item = new Dictionary
{
{ "ForumName", new AttributeValue {
S = "S3 forum"
} },
{ "Subject", new AttributeValue {
S = "My sample question"
} },
{ "Message", new AttributeValue {
S = "Message Text."
} },
{ "KeywordTags", new AttributeValue {
SS = new List { "S3", "Bucket" }
} }
}
}
},
new WriteRequest
{
// For the operation to delete an item, if you provide a primary key value
// that does not exist in the table, there is no error, it is just a no-op.
DeleteRequest = new DeleteRequest
{
Key = new Dictionary()
{
{ "ForumName", new AttributeValue {
S = "Some partition key value"
} },
{ "Subject", new AttributeValue {
S = "Some sort key value"
} }
}
}
}
}
}
}
};
CallBatchWriteTillCompletion(request);
}
private static void CallBatchWriteTillCompletion(BatchWriteItemRequest request)
{
BatchWriteItemResponse response;
int callCount = 0;
do
{
Console.WriteLine("Making request");
response = client.BatchWriteItem(request);
callCount++;
// Check the response.
var tableConsumedCapacities = response.ConsumedCapacity;
var unprocessed = response.UnprocessedItems;
Console.WriteLine("Per-table consumed capacity");
foreach (var tableConsumedCapacity in tableConsumedCapacities)
{
Console.WriteLine("{0} - {1}", tableConsumedCapacity.TableName, tableConsumedCapacity.CapacityUnits);
}
Console.WriteLine("Unprocessed");
foreach (var unp in unprocessed)
{
Console.WriteLine("{0} - {1}", unp.Key, unp.Value.Count);
}
Console.WriteLine();
// For the next iteration, the request will have unprocessed items.
request.RequestItems = unprocessed;
} while (response.UnprocessedItems.Count > 0);
Console.WriteLine("Total # of batch write API calls made: {0}", callCount);
}
}
}
```
## Exemple : opération Batch get à l'aide de l'API de AWS SDK pour .NET bas niveau
L’exemple de code C\$1 suivant extrait plusieurs éléments des tables `Forum` et `Thread` dans Amazon DynamoDB à l’aide de la méthode `BatchGetItem`. La demande `BatchGetItemRequest` spécifie les noms de table et une liste de clés primaires pour chaque table. L’exemple traite la réponse en imprimant les éléments récupérés.
Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
namespace com.amazonaws.codesamples
{
class LowLevelBatchGet
{
private static string table1Name = "Forum";
private static string table2Name = "Thread";
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
try
{
RetrieveMultipleItemsBatchGet();
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void RetrieveMultipleItemsBatchGet()
{
var request = new BatchGetItemRequest
{
RequestItems = new Dictionary()
{
{ table1Name,
new KeysAndAttributes
{
Keys = new List >()
{
new Dictionary()
{
{ "Name", new AttributeValue {
S = "Amazon DynamoDB"
} }
},
new Dictionary()
{
{ "Name", new AttributeValue {
S = "Amazon S3"
} }
}
}
}},
{
table2Name,
new KeysAndAttributes
{
Keys = new List >()
{
new Dictionary()
{
{ "ForumName", new AttributeValue {
S = "Amazon DynamoDB"
} },
{ "Subject", new AttributeValue {
S = "DynamoDB Thread 1"
} }
},
new Dictionary()
{
{ "ForumName", new AttributeValue {
S = "Amazon DynamoDB"
} },
{ "Subject", new AttributeValue {
S = "DynamoDB Thread 2"
} }
},
new Dictionary()
{
{ "ForumName", new AttributeValue {
S = "Amazon S3"
} },
{ "Subject", new AttributeValue {
S = "S3 Thread 1"
} }
}
}
}
}
}
};
BatchGetItemResponse response;
do
{
Console.WriteLine("Making request");
response = client.BatchGetItem(request);
// Check the response.
var responses = response.Responses; // Attribute list in the response.
foreach (var tableResponse in responses)
{
var tableResults = tableResponse.Value;
Console.WriteLine("Items retrieved from table {0}", tableResponse.Key);
foreach (var item1 in tableResults)
{
PrintItem(item1);
}
}
// Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error.
Dictionary unprocessedKeys = response.UnprocessedKeys;
foreach (var unprocessedTableKeys in unprocessedKeys)
{
// Print table name.
Console.WriteLine(unprocessedTableKeys.Key);
// Print unprocessed primary keys.
foreach (var key in unprocessedTableKeys.Value.Keys)
{
PrintItem(key);
}
}
request.RequestItems = unprocessedKeys;
} while (response.UnprocessedKeys.Count > 0);
}
private static void PrintItem(Dictionary attributeList)
{
foreach (KeyValuePair kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]")
);
}
Console.WriteLine("************************************************");
}
}
}
```
# Exemple : gestion des attributs de type binaire à l'aide de l'API de AWS SDK pour .NET bas niveau
L’exemple de code C\$1 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. A titre d’illustration, l’exemple compresse un exemple de flux et l’affecte à l’attribut `ExtendedMessage` à l’aide de la classe `GZipStream`, puis le décompresse lors de l’affichage de la valeur de l’attribut.
Pour step-by-step obtenir des instructions sur le test de l'exemple suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.IO;
using System.IO.Compression;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
namespace com.amazonaws.codesamples
{
class LowLevelItemBinaryExample
{
private static string tableName = "Reply";
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
// Reply table primary key.
string replyIdPartitionKey = "Amazon DynamoDB#DynamoDB Thread 1";
string replyDateTimeSortKey = Convert.ToString(DateTime.UtcNow);
try
{
CreateItem(replyIdPartitionKey, replyDateTimeSortKey);
RetrieveItem(replyIdPartitionKey, replyDateTimeSortKey);
// Delete item.
DeleteItem(replyIdPartitionKey, replyDateTimeSortKey);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateItem(string partitionKey, string sortKey)
{
MemoryStream compressedMessage = ToGzipMemoryStream("Some long extended message to compress.");
var request = new PutItemRequest
{
TableName = tableName,
Item = new Dictionary()
{
{ "Id", new AttributeValue {
S = partitionKey
}},
{ "ReplyDateTime", new AttributeValue {
S = sortKey
}},
{ "Subject", new AttributeValue {
S = "Binary type "
}},
{ "Message", new AttributeValue {
S = "Some message about the binary type"
}},
{ "ExtendedMessage", new AttributeValue {
B = compressedMessage
}}
}
};
client.PutItem(request);
}
private static void RetrieveItem(string partitionKey, string sortKey)
{
var request = new GetItemRequest
{
TableName = tableName,
Key = new Dictionary()
{
{ "Id", new AttributeValue {
S = partitionKey
} },
{ "ReplyDateTime", new AttributeValue {
S = sortKey
} }
},
ConsistentRead = true
};
var response = client.GetItem(request);
// Check the response.
var attributeList = response.Item; // attribute list in the response.
Console.WriteLine("\nPrinting item after retrieving it ............");
PrintItem(attributeList);
}
private static void DeleteItem(string partitionKey, string sortKey)
{
var request = new DeleteItemRequest
{
TableName = tableName,
Key = new Dictionary()
{
{ "Id", new AttributeValue {
S = partitionKey
} },
{ "ReplyDateTime", new AttributeValue {
S = sortKey
} }
}
};
var response = client.DeleteItem(request);
}
private static void PrintItem(Dictionary attributeList)
{
foreach (KeyValuePair kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```