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. # Travaillez avec des documents JSON avec l'API de document améliorée pour DynamoDB L'[API de document améliorée](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) pour AWS SDK for Java 2.x est conçue pour fonctionner avec des données orientées document qui n'ont aucun schéma fixe. Toutefois, il vous permet également d'utiliser des classes personnalisées pour mapper des attributs individuels. L'Enhanced Document API est le successeur de l'[API Document](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) de la AWS SDK pour Java v1.x. **Contents** + [Commencez à utiliser l'API Enhanced Document](ddb-en-client-doc-api-steps.md) + [Créez un `DocumentTableSchema` et un `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema) + [Créez des documents améliorés](ddb-en-client-doc-api-steps-create-ed.md) + [Construire à partir d'une chaîne JSON](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson) + [Construisez à partir d'éléments individuels](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) + [Effectuer des opérations CRUD](ddb-en-client-doc-api-steps-use.md) + [Accédez aux attributs de document améliorés sous forme d'objets personnalisés](ddb-en-client-doc-api-convert.md) + [Utiliser et `EnhancedDocument` sans DynamoDB](ddb-en-client-doc-api-standalone.md) # Commencez à utiliser l'API Enhanced Document L'API de document améliorée nécessite les mêmes [dépendances](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) que celles requises pour l'API client améliorée DynamoDB. Cela nécessite également une [`DynamoDbEnhancedClient`instance](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient), comme indiqué au début de cette rubrique. Étant donné que l'API Enhanced Document a été publiée avec la version 2.20.3 du AWS SDK for Java 2.x, vous avez besoin de cette version ou d'une version ultérieure. ## Créez un `DocumentTableSchema` et un `DynamoDbTable` Pour appeler des commandes sur une table DynamoDB à l'aide de l'API Enhanced Document, associez la table à un objet de ressource < > [DynamoDbTablecôté client EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html). La `table()` méthode du client amélioré crée une `DynamoDbTable` instance et nécessite des paramètres pour le nom de la table DynamoDB et un. `DocumentTableSchema` Le générateur d'un [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)nécessite une clé d'index principale et un ou plusieurs fournisseurs de convertisseurs d'attributs. La `AttributeConverterProvider.defaultProvider()` méthode fournit des convertisseurs pour les [types par défaut](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html). Il doit être spécifié même si vous fournissez un fournisseur de convertisseur d'attributs personnalisé. Vous pouvez ajouter une clé d'index secondaire facultative au générateur. L'extrait de code suivant montre le code qui génère la représentation côté client d'une table DynamoDB qui stocke des objets sans schéma. `person` `EnhancedDocument` ``` DynamoDbTable documentDynamoDbTable = enhancedClient.table("person", TableSchema.documentSchemaBuilder() // Specify the primary key attributes. .addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S) .addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S) // Specify attribute converter providers. Minimally add the default one. .attributeConverterProviders(AttributeConverterProvider.defaultProvider()) .build()); // Call documentTable.createTable() if "person" does not exist in DynamoDB. // createTable() should be called only one time. ``` Ce qui suit montre la représentation JSON d'un `person` objet utilisé dans cette section. ### `person`Objet JSON ``` { "id": 1, "firstName": "Richard", "lastName": "Roe", "age": 25, "addresses": { "home": { "zipCode": "00000", "city": "Any Town", "state": "FL", "street": "123 Any Street" }, "work": { "zipCode": "00001", "city": "Anywhere", "state": "FL", "street": "100 Main Street" } }, "hobbies": [ "Hobby 1", "Hobby 2" ], "phoneNumbers": [ { "type": "Home", "number": "555-0100" }, { "type": "Work", "number": "555-0119" } ] } ``` # Créez des documents améliorés An `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` représente un objet de type document doté d'une structure complexe avec des attributs imbriqués. An `EnhancedDocument` nécessite des attributs de haut niveau qui correspondent aux attributs de clé primaire spécifiés pour le`DocumentTableSchema`. Le contenu restant est arbitraire et peut être composé d'attributs de haut niveau ou d'attributs profondément imbriqués. Vous créez une `EnhancedDocument` instance à l'aide d'un générateur qui propose plusieurs méthodes pour ajouter des éléments. ## Construire à partir d'une chaîne JSON Avec une chaîne JSON, vous pouvez créer un appel de méthode `EnhancedDocument` en un. L'extrait suivant crée une chaîne `EnhancedDocument` à partir d'une chaîne JSON renvoyée par la méthode d'`jsonPerson()`assistance. La `jsonPerson()` méthode renvoie la version de chaîne JSON de l'[objet person](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) affiché précédemment. ``` EnhancedDocument document = EnhancedDocument.builder() .json( jsonPerson() ) .build()); ``` ## Construisez à partir d'éléments individuels Vous pouvez également créer une `EnhancedDocument` instance à partir de composants individuels à l'aide des méthodes de type sécurisé du générateur. L'exemple suivant crée un document `person` amélioré similaire au document amélioré créé à partir de la chaîne JSON de l'exemple précédent. ``` /* Define the shape of an address map whose JSON representation looks like the following. Use 'addressMapEnhancedType' in the following EnhancedDocument.builder() to simplify the code. "home": { "zipCode": "00000", "city": "Any Town", "state": "FL", "street": "123 Any Street" }*/ EnhancedType> addressMapEnhancedType = EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class)); // Use the builder's typesafe methods to add elements to the enhanced document. EnhancedDocument personDocument = EnhancedDocument.builder() .putNumber("id", 50) .putString("firstName", "Shirley") .putString("lastName", "Rodriguez") .putNumber("age", 53) .putNull("nullAttribute") .putJson("phoneNumbers", phoneNumbersJSONString()) /* Add the map of addresses whose JSON representation looks like the following. { "home": { "zipCode": "00000", "city": "Any Town", "state": "FL", "street": "123 Any Street" } } */ .putMap("addresses", getAddresses(), EnhancedType.of(String.class), addressMapEnhancedType) .putList("hobbies", List.of("Theater", "Golf"), EnhancedType.of(String.class)) .build(); ``` ### Méthodes auxiliaires ``` private static String phoneNumbersJSONString() { return " [" + " {" + " \"type\": \"Home\"," + " \"number\": \"555-0140\"" + " }," + " {" + " \"type\": \"Work\"," + " \"number\": \"555-0155\"" + " }" + " ]"; } private static Map> getAddresses() { return Map.of( "home", Map.of( "zipCode", "00002", "city", "Any Town", "state", "ME", "street", "123 Any Street")); } ``` # Effectuer des opérations CRUD Après avoir défini une `EnhancedDocument` instance, vous pouvez l'enregistrer dans une table DynamoDB. L'extrait de code suivant utilise le [PersonDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) créé à partir d'éléments individuels. ``` documentDynamoDbTable.putItem(personDocument); ``` Après avoir lu une instance de document améliorée depuis DynamoDB, vous pouvez extraire les valeurs d'attribut individuelles à l'aide de getters, comme indiqué dans l'extrait de code suivant qui accède aux données enregistrées depuis le. `personDocument` Vous pouvez également extraire le contenu complet dans une chaîne JSON, comme indiqué dans la dernière partie de l'exemple de code. ``` // Read the item. EnhancedDocument personDocFromDb = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).build()); // Access top-level attributes. logger.info("Name: {} {}", personDocFromDb.getString("firstName"), personDocFromDb.getString("lastName")); // Name: Shirley Rodriguez // Typesafe access of a deeply nested attribute. The addressMapEnhancedType shown previously defines the shape of an addresses map. Map> addresses = personDocFromDb.getMap("addresses", EnhancedType.of(String.class), addressMapEnhancedType); addresses.keySet().forEach(k -> logger.info(addresses.get(k).toString())); // {zipCode=00002, city=Any Town, street=123 Any Street, state=ME} // Alternatively, work with AttributeValue types checking along the way for deeply nested attributes. Map addressesMap = personDocFromDb.getMapOfUnknownType("addresses"); addressesMap.keySet().forEach((String k) -> { logger.info("Looking at data for [{}] address", k); // Looking at data for [home] address AttributeValue value = addressesMap.get(k); AttributeValue cityValue = value.m().get("city"); if (cityValue != null) { logger.info(cityValue.s()); // Any Town } }); List phoneNumbers = personDocFromDb.getListOfUnknownType("phoneNumbers"); phoneNumbers.forEach((AttributeValue av) -> { if (av.hasM()) { AttributeValue type = av.m().get("type"); if (type.s() != null) { logger.info("Type of phone: {}", type.s()); // Type of phone: Home // Type of phone: Work } } }); String jsonPerson = personDocFromDb.toJson(); logger.info(jsonPerson); // {"firstName":"Shirley","lastName":"Rodriguez","addresses":{"home":{"zipCode":"00002","city":"Any Town","street":"123 Any Street","state":"ME"}},"hobbies":["Theater","Golf"], // "id":50,"nullAttribute":null,"age":53,"phoneNumbers":[{"number":"555-0140","type":"Home"},{"number":"555-0155","type":"Work"}]} ``` `EnhancedDocument`les instances peuvent être utilisées avec n'importe quelle méthode `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` ou [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)à la place de classes de données mappées. # Accédez aux attributs de document améliorés sous forme d'objets personnalisés En plus de fournir une API pour lire et écrire des attributs avec des structures sans schéma, l'API Enhanced Document vous permet de convertir des attributs depuis et vers des instances de classes personnalisées. L'API de document améliorée utilise `AttributeConverterProvider` les valeurs s et `AttributeConverter` s affichées dans la section de [conversion des attributs de contrôle](ddb-en-client-adv-features-conversion.md) dans le cadre de l'API client améliorée DynamoDB. Dans l'exemple suivant, nous utilisons a `CustomAttributeConverterProvider` avec sa `AddressConverter` classe imbriquée pour convertir `Address` des objets. Cet exemple montre que vous pouvez mélanger des données provenant de classes et des données provenant de structures créées selon les besoins. Cet exemple montre également que les classes personnalisées peuvent être utilisées à n'importe quel niveau d'une structure imbriquée. Les `Address` objets de cet exemple sont des valeurs utilisées dans une carte. ``` public static void attributeToAddressClassMappingExample(DynamoDbEnhancedClient enhancedClient, DynamoDbClient standardClient) { String tableName = "customer"; // Define the DynamoDbTable for an enhanced document. // The schema builder provides methods for attribute converter providers and keys. DynamoDbTable documentDynamoDbTable = enhancedClient.table(tableName, DocumentTableSchema.builder() // Add the CustomAttributeConverterProvider along with the default when you build the table schema. .attributeConverterProviders( List.of( new CustomAttributeConverterProvider(), AttributeConverterProvider.defaultProvider())) .addIndexPartitionKey(TableMetadata.primaryIndexName(), "id", AttributeValueType.N) .addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S) .build()); // Create the DynamoDB table if needed. documentDynamoDbTable.createTable(); waitForTableCreation(tableName, standardClient); // The getAddressesForCustomMappingExample() helper method that provides 'addresses' shows the use of a custom Address class // rather than using a Map to hold the address data. Map addresses = getAddressesForCustomMappingExample(); // Build an EnhancedDocument instance to save an item with a mix of structures defined as needed and static classes. EnhancedDocument personDocument = EnhancedDocument.builder() .putNumber("id", 50) .putString("firstName", "Shirley") .putString("lastName", "Rodriguez") .putNumber("age", 53) .putNull("nullAttribute") .putJson("phoneNumbers", phoneNumbersJSONString()) // Note the use of 'EnhancedType.of(Address.class)' instead of the more generic // 'EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class))' that was used in a previous example. .putMap("addresses", addresses, EnhancedType.of(String.class), EnhancedType.of(Address.class)) .putList("hobbies", List.of("Hobby 1", "Hobby 2"), EnhancedType.of(String.class)) .build(); // Save the item to DynamoDB. documentDynamoDbTable.putItem(personDocument); // Retrieve the item just saved. EnhancedDocument srPerson = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).sortValue("Rodriguez").build()); // Access the addresses attribute. Map srAddresses = srPerson.get("addresses", EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(Address.class))); srAddresses.keySet().forEach(k -> logger.info(addresses.get(k).toString())); documentDynamoDbTable.deleteTable(); // The content logged to the console shows that the saved maps were converted to Address instances. Address{street='123 Main Street', city='Any Town', state='NC', zipCode='00000'} Address{street='100 Any Street', city='Any Town', state='NC', zipCode='00000'} ``` ## Code de la `CustomAttributeConverterProvider` ``` public class CustomAttributeConverterProvider implements AttributeConverterProvider { private final Map, AttributeConverter> converterCache = ImmutableMap.of( // 1. Add AddressConverter to the internal cache. EnhancedType.of(Address.class), new AddressConverter()); public static CustomAttributeConverterProvider create() { return new CustomAttributeConverterProvider(); } // 2. The enhanced client queries the provider for attribute converters if it // encounters a type that it does not know how to convert. @SuppressWarnings("unchecked") @Override public AttributeConverter converterFor(EnhancedType enhancedType) { return (AttributeConverter) converterCache.get(enhancedType); } // 3. Custom attribute converter private class AddressConverter implements AttributeConverter
{ // 4. Transform an Address object into a DynamoDB map. @Override public AttributeValue transformFrom(Address address) { Map attributeValueMap = Map.of( "street", AttributeValue.fromS(address.getStreet()), "city", AttributeValue.fromS(address.getCity()), "state", AttributeValue.fromS(address.getState()), "zipCode", AttributeValue.fromS(address.getZipCode())); return AttributeValue.fromM(attributeValueMap); } // 5. Transform the DynamoDB map attribute to an Address oject. @Override public Address transformTo(AttributeValue attributeValue) { Map m = attributeValue.m(); Address address = new Address(); address.setStreet(m.get("street").s()); address.setCity(m.get("city").s()); address.setState(m.get("state").s()); address.setZipCode(m.get("zipCode").s()); return address; } @Override public EnhancedType
type() { return EnhancedType.of(Address.class); } @Override public AttributeValueType attributeValueType() { return AttributeValueType.M; } } } ``` ## classe `Address` ``` public class Address { private String street; private String city; private String state; private String zipCode; public Address() { } public String getStreet() { return this.street; } public String getCity() { return this.city; } public String getState() { return this.state; } public String getZipCode() { return this.zipCode; } public void setStreet(String street) { this.street = street; } public void setCity(String city) { this.city = city; } public void setState(String state) { this.state = state; } public void setZipCode(String zipCode) { this.zipCode = zipCode; } } ``` ## Méthode d'assistance qui fournit des adresses La méthode d'assistance suivante fournit la carte qui utilise des `Address` instances personnalisées pour les valeurs plutôt que des `Map` instances génériques pour les valeurs. ``` private static Map getAddressesForCustomMappingExample() { Address homeAddress = new Address(); homeAddress.setStreet("100 Any Street"); homeAddress.setCity("Any Town"); homeAddress.setState("NC"); homeAddress.setZipCode("00000"); Address workAddress = new Address(); workAddress.setStreet("123 Main Street"); workAddress.setCity("Any Town"); workAddress.setState("NC"); workAddress.setZipCode("00000"); return Map.of("home", homeAddress, "work", workAddress); } ``` # Utiliser et `EnhancedDocument` sans DynamoDB Bien que vous utilisiez généralement une instance d'un `EnhancedDocument` pour lire et écrire des éléments DynamoDB de type document, elle peut également être utilisée indépendamment de DynamoDB. Vous pouvez `EnhancedDocuments` les utiliser pour leur capacité à convertir des chaînes JSON ou des objets personnalisés en cartes de bas niveau, `AttributeValues` comme indiqué dans l'exemple suivant. ``` public static void conversionWithoutDynamoDbExample() { Address address = new Address(); address.setCity("my city"); address.setState("my state"); address.setStreet("my street"); address.setZipCode("00000"); // Build an EnhancedDocument instance for its conversion functionality alone. EnhancedDocument addressEnhancedDoc = EnhancedDocument.builder() // Important: You must specify attribute converter providers when you build an EnhancedDocument instance not used with a DynamoDB table. .attributeConverterProviders(new CustomAttributeConverterProvider(), DefaultAttributeConverterProvider.create()) .put("addressDoc", address, Address.class) .build(); // Convert address to a low-level item representation. final Map addressAsAttributeMap = addressEnhancedDoc.getMapOfUnknownType("addressDoc"); logger.info("addressAsAttributeMap: {}", addressAsAttributeMap.toString()); // Convert address to a JSON string. String addressAsJsonString = addressEnhancedDoc.getJson("addressDoc"); logger.info("addressAsJsonString: {}", addressAsJsonString); // Convert addressEnhancedDoc back to an Address instance. Address addressConverted = addressEnhancedDoc.get("addressDoc", Address.class); logger.info("addressConverted: {}", addressConverted.toString()); } /* Console output: addressAsAttributeMap: {zipCode=AttributeValue(S=00000), state=AttributeValue(S=my state), street=AttributeValue(S=my street), city=AttributeValue(S=my city)} addressAsJsonString: {"zipCode":"00000","state":"my state","street":"my street","city":"my city"} addressConverted: Address{street='my street', city='my city', state='my state', zipCode='00000'} */ ``` **Note** Lorsque vous utilisez un document amélioré indépendant d'une table DynamoDB, assurez-vous de définir explicitement les fournisseurs de convertisseurs d'attributs dans le générateur. En revanche, le schéma de table de documents fournit les fournisseurs de conversion lorsqu'un document amélioré est utilisé avec une table DynamoDB.