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. # Commencez à utiliser l'API client améliorée DynamoDB Le didacticiel suivant présente les principes fondamentaux dont vous avez besoin pour utiliser l'API client améliorée DynamoDB. ## Ajouter des dépendances Pour commencer à utiliser l'API client améliorée DynamoDB dans votre projet, ajoutez une dépendance à l'artefact Maven. `dynamodb-enhanced` Cela est illustré dans les exemples suivants. ------ #### [ Maven ] ``` software.amazon.awssdk bom pom import software.amazon.awssdk dynamodb-enhanced ... ``` Effectuez une recherche dans le référentiel central Maven pour trouver la [dernière version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) et remplacez-la ** par cette valeur. ------ #### [ Gradle ] ``` repositories { mavenCentral() } dependencies { implementation(platform("software.amazon.awssdk:bom:")) implementation("software.amazon.awssdk:dynamodb-enhanced") ... } ``` Effectuez une recherche dans le référentiel central Maven pour trouver la [dernière version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) et remplacez-la ** par cette valeur. ------ # Générer un `TableSchema` à partir d'une classe de données A `[TableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/TableSchema.html)` permet au client amélioré de mapper les valeurs d'attribut DynamoDB vers et depuis vos classes côté client. Dans ce didacticiel, vous découvrirez `TableSchema` s dérivé d'une classe de données statique et généré à partir de code à l'aide d'un générateur. ## Utiliser une classe de données annotée Le SDK pour Java 2.x inclut [un ensemble d'annotations que vous pouvez utiliser avec une classe de](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html) données pour générer `TableSchema` rapidement un fichier permettant de mapper vos classes à des tables. Commencez par créer une classe de données conforme à la [JavaBean spécification](https://download.oracle.com/otn-pub/jcp/7224-javabeans-1.01-fr-spec-oth-JSpec/beans.101.pdf). La spécification exige qu'une classe ait un constructeur public sans argument et dispose de getters et setters pour chaque attribut de la classe. Incluez une annotation au niveau de la classe pour indiquer que la classe de données est une. `DynamoDbBean` Incluez également, au minimum, une `DynamoDbPartitionKey` annotation sur le getter ou le setter pour l'attribut clé primaire. Vous pouvez appliquer des [annotations au niveau des attributs](ddb-en-client-anno-index.md) aux getters ou aux setters, mais pas aux deux. **Note** Le terme `property` est normalement utilisé pour une valeur encapsulée dans un JavaBean. Toutefois, ce guide utilise ce terme à la `attribute` place, par souci de cohérence avec la terminologie utilisée par DynamoDB. La `Customer` classe suivante affiche les annotations qui lient la définition de classe à une table DynamoDB. ### classe `Customer` ``` package org.example.tests.model; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey; import java.time.Instant; @DynamoDbBean public class Customer { private String id; private String name; private String email; private Instant regDate; @DynamoDbPartitionKey public String getId() { return this.id; } public void setId(String id) { this.id = id; } public String getCustName() { return this.name; } public void setCustName(String name) { this.name = name; } @DynamoDbSortKey public String getEmail() { return this.email; } public void setEmail(String email) { this.email = email; } public Instant getRegistrationDate() { return this.regDate; } public void setRegistrationDate(Instant registrationDate) { this.regDate = registrationDate; } @Override public String toString() { return "Customer [id=" + id + ", name=" + name + ", email=" + email + ", regDate=" + regDate + "]"; } } ``` Après avoir créé une classe de données annotée, utilisez-la pour créer la`TableSchema`, comme indiqué dans l'extrait de code suivant. ``` static final TableSchema customerTableSchema = TableSchema.fromBean(Customer.class); ``` A `TableSchema` est conçu pour être statique et immuable. Vous pouvez généralement l'instancier au moment du chargement de la classe. La méthode static `TableSchema.fromBean()` factory introspecte le bean pour générer le mappage des attributs de classe de données (propriétés) vers et depuis les attributs DynamoDB. Pour un exemple d'utilisation d'un modèle de données composé de plusieurs classes de données, consultez la `Person` classe dans la [Travaillez avec des attributs tels que des beans, des cartes, des listes et des ensembles](ddb-en-client-adv-features-nested.md) section. ## Utilisez un constructeur Vous pouvez éviter le coût de l'introspection des haricots si vous définissez le schéma de table dans le code. Si vous codez le schéma, votre classe n'a pas besoin de suivre les normes de JavaBean dénomination ni d'être annotée. L'exemple suivant utilise un générateur et est équivalent à l'exemple de `Customer` classe qui utilise des annotations. ``` static final TableSchema customerTableSchema = TableSchema.builder(Customer.class) .newItemSupplier(Customer::new) .addAttribute(String.class, a -> a.name("id") .getter(Customer::getId) .setter(Customer::setId) .tags(StaticAttributeTags.primaryPartitionKey())) .addAttribute(String.class, a -> a.name("email") .getter(Customer::getEmail) .setter(Customer::setEmail) .tags(StaticAttributeTags.primarySortKey())) .addAttribute(String.class, a -> a.name("name") .getter(Customer::getCustName) .setter(Customer::setCustName)) .addAttribute(Instant.class, a -> a.name("registrationDate") .getter(Customer::getRegistrationDate) .setter(Customer::setRegistrationDate)) .build(); ``` # Créez un client amélioré et `DynamoDbTable` ## Créez un client amélioré La [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)classe, ou son équivalent asynchrone [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html), est le point d'entrée pour utiliser l'API DynamoDB Enhanced Client. Le client amélioré a besoin d'une norme `[DynamoDbClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html)` pour effectuer le travail. L'API propose deux méthodes pour créer une `DynamoDbEnhancedClient` instance. La première option, illustrée dans l'extrait suivant, crée une norme dont les paramètres `DynamoDbClient` par défaut sont extraits des paramètres de configuration. ``` DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create(); ``` Si vous souhaitez configurer le client standard sous-jacent, vous pouvez le fournir à la méthode de création du client amélioré, comme indiqué dans l'extrait suivant. ``` // Configure an instance of the standard DynamoDbClient. DynamoDbClient standardClient = DynamoDbClient.builder() .region(Region.US_EAST_1) .credentialsProvider(ProfileCredentialsProvider.create()) .build(); // Use the configured standard client with the enhanced client. DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(standardClient) .build(); ``` ## Créer une instance `DynamoDbTable` Considérez a [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)comme la représentation côté client d'une table DynamoDB qui utilise la fonctionnalité de mappage fournie par a. `TableSchema` La `DynamoDbTable` classe fournit des méthodes pour les opérations CRUD qui vous permettent d'interagir avec une seule table DynamoDB. `DynamoDbTable`est une classe générique qui prend un seul argument de type, qu'il s'agisse d'une classe personnalisée ou d'un `EnhancedDocument` lorsque vous travaillez avec des éléments de type document. Ce type d'argument établit la relation entre la classe que vous utilisez et l'unique table DynamoDB. Utilisez la méthode `table()` factory du `DynamoDbEnhancedClient` pour créer une `DynamoDbTable` instance, comme indiqué dans l'extrait de code suivant. ``` static final DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class)); ``` `DynamoDbTable`les instances sont candidates aux singletons car elles sont immuables et peuvent être utilisées dans l'ensemble de votre application. Votre code possède désormais une représentation en mémoire d'une table DynamoDB qui peut fonctionner avec des instances. `Customer` La table DynamoDB réelle peut exister ou ne pas exister. Si la table nommée existe `Customer` déjà, vous pouvez commencer à effectuer des opérations CRUD sur elle. Si elle n'existe pas, utilisez l'`DynamoDbTable`instance pour créer la table comme indiqué dans la section suivante. # Créez une table DynamoDB si nécessaire Après avoir créé une `DynamoDbTable` instance, utilisez-la pour créer une *seule fois* une table dans DynamoDB. ## Créer un exemple de code de table L'exemple suivant crée une table DynamoDB basée sur `Customer` la classe de données. Cet exemple crée une table DynamoDB dont le nom est identique au `Customer` nom de classe, mais le nom de la table peut être différent. Quel que soit le nom que vous donnez à la table, vous devez utiliser ce nom dans d'autres applications pour travailler avec la table. Fournissez ce nom à la `table()` méthode chaque fois que vous créez un autre `DynamoDbTable` objet afin de travailler avec la table DynamoDB sous-jacente. Le paramètre Java lambda,`builder`, transmis à la `createTable` méthode vous permet de [personnaliser le tableau](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/CreateTableEnhancedRequest.Builder.html). Dans cet exemple, le [débit provisionné](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.ProvisionedThroughput.Manual) est configuré. Si vous souhaitez utiliser les paramètres par défaut lorsque vous créez une table, ignorez le générateur, comme indiqué dans l'extrait de code suivant. ``` customerTable.createTable(); ``` Lorsque les paramètres par défaut sont utilisés, les valeurs du débit provisionné ne sont pas définies. Au lieu de cela, le mode de facturation de la table est défini [sur demande](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.OnDemand). L'exemple utilise également un `[DynamoDbWaiter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/waiters/DynamoDbWaiter.html)` avant de tenter d'imprimer le nom de la table reçu dans la réponse. La création d'une table prend un certain temps. Par conséquent, l'utilisation d'un serveur signifie que vous n'avez pas à écrire une logique qui interroge le service DynamoDB pour vérifier si la table existe avant de l'utiliser. ### Importations ``` import com.example.dynamodb.Customer; import software.amazon.awssdk.core.internal.waiters.ResponseOrException; import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient; import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable; import software.amazon.awssdk.enhanced.dynamodb.TableSchema; import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest; import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse; import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter; ``` ### Code ``` public static void createCustomerTable(DynamoDbTable customerTable, DynamoDbClient standardClient) { // Create the DynamoDB table using the 'customerTable' DynamoDbTable instance. customerTable.createTable(builder -> builder .provisionedThroughput(b -> b .readCapacityUnits(10L) .writeCapacityUnits(10L) .build()) ); // The DynamoDbClient instance (named 'standardClient') passed to the builder for the DynamoDbWaiter is the same instance // that was passed to the builder of the DynamoDbEnhancedClient instance that we created previously. // By using the same instance, it ensures that the same Region that was configured on the standard DynamoDbClient // instance is used for other service clients that accept a DynamoDbClient during construction. try (DynamoDbWaiter waiter = DynamoDbWaiter.builder().client(standardClient).build()) { // DynamoDbWaiter is Autocloseable ResponseOrException response = waiter .waitUntilTableExists(builder -> builder.tableName("Customer").build()) .matched(); DescribeTableResponse tableDescription = response.response().orElseThrow( () -> new RuntimeException("Customer table was not created.")); // The actual error can be inspected in response.exception() logger.info("Customer table was created."); } } ``` **Note** Les noms d'attributs d'une table DynamoDB commencent par une lettre minuscule lorsque la table est générée à partir d'une classe de données. Si vous souhaitez que le nom d'attribut de la table commence par une lettre majuscule, utilisez l'[`@DynamoDbAttribute(NAME)`annotation](ddb-en-client-adv-features-inex-attr.md) et indiquez le nom souhaité en tant que paramètre. # Réaliser des opérations Une fois la table créée, utilisez l'`DynamoDbTable`instance pour effectuer des opérations sur la table DynamoDB. Dans l'exemple suivant, un singleton `DynamoDbTable` est transmis en tant que paramètre avec une instance de [classe de `Customer` données](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) pour ajouter un nouvel élément à la table. ``` public static void putItemExample(DynamoDbTable customerTable, Customer customer){ logger.info(customer.toString()); customerTable.putItem(customer); } ``` ## Objet `Customer` ``` Customer customer = new Customer(); customer.setId("1"); customer.setCustName("Customer Name"); customer.setEmail("customer@example.com"); customer.setRegistrationDate(Instant.parse("2023-07-03T10:15:30.00Z")); ``` Avant d'envoyer l'`customer`objet au service DynamoDB, enregistrez le résultat de la méthode de l'objet `toString()` pour le comparer à ce que le client amélioré envoie. ``` Customer [id=1, name=Customer Name, email=customer@example.com, regDate=2023-07-03T10:15:30Z] ``` La journalisation au niveau du fil indique la charge utile de la demande générée. Le client amélioré a généré la représentation de bas niveau à partir de la classe de données. L'`regDate`attribut, qui est un `Instant` type en Java, est représenté sous la forme d'une chaîne DynamoDB. ``` { "TableName": "Customer", "Item": { "registrationDate": { "S": "2023-07-03T10:15:30Z" }, "id": { "S": "1" }, "custName": { "S": "Customer Name" }, "email": { "S": "customer@example.com" } } } ``` # Travailler avec une table existante La section précédente a montré comment créer une table DynamoDB à partir d'une classe de données Java. Si vous possédez déjà une table et que vous souhaitez utiliser les fonctionnalités du client amélioré, vous pouvez créer une classe de données Java qui fonctionnera avec la table. Vous devez examiner la table DynamoDB et ajouter les annotations nécessaires à la classe de données. Avant de travailler avec une table existante, appelez la `DynamoDbEnhanced.table()` méthode. Cela a été fait dans l'exemple précédent avec l'instruction suivante. ``` DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class)); ``` Une fois l'`DynamoDbTable`instance renvoyée, vous pouvez commencer à travailler immédiatement avec la table sous-jacente. Il n'est pas nécessaire de recréer la table en appelant la `DynamoDbTable.createTable()` méthode. L'exemple suivant illustre cela en récupérant immédiatement une `Customer` instance de la table DynamoDB. ``` DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class)); // The Customer table exists already and has an item with a primary key value of "1" and a sort key value of "customer@example.com". customerTable.getItem( Key.builder(). partitionValue("1"). sortValue("customer@example.com").build()); ``` **Important** Le nom de table utilisé dans la `table()` méthode doit correspondre au nom de table DynamoDB existant.