Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Arbeiten Sie mit JSON-Dokumenten mit der Enhanced Document API für DynamoDB Die [Enhanced Document API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) für AWS SDK for Java 2.x ist für die Arbeit mit dokumentenorientierten Daten konzipiert, die kein festes Schema haben. Sie können damit jedoch auch benutzerdefinierte Klassen verwenden, um einzelne Attribute zuzuordnen. Die Enhanced Document API ist der Nachfolger der [Document API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) der AWS SDK für Java Version v1.x. **Contents** + [Beginnen Sie mit der Verwendung der Enhanced Document API](ddb-en-client-doc-api-steps.md) + [Erstellen Sie ein und ein `DocumentTableSchema` `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema) + [Erstellen Sie erweiterte Dokumente](ddb-en-client-doc-api-steps-create-ed.md) + [Aus einer JSON-Zeichenfolge erstellen](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson) + [Aus einzelnen Elementen zusammensetzen](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) + [Führen Sie CRUD-Operationen durch](ddb-en-client-doc-api-steps-use.md) + [Greifen Sie als benutzerdefinierte Objekte auf erweiterte Dokumentattribute zu](ddb-en-client-doc-api-convert.md) + [Verwenden Sie eine `EnhancedDocument` ohne DynamoDB](ddb-en-client-doc-api-standalone.md) # Beginnen Sie mit der Verwendung der Enhanced Document API Die Enhanced Document API erfordert dieselben [Abhängigkeiten](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) wie die DynamoDB Enhanced Client API. Außerdem ist eine [`DynamoDbEnhancedClient`Instanz](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient) erforderlich, wie am Anfang dieses Themas beschrieben. Da die Enhanced Document API mit Version 2.20.3 von veröffentlicht wurde AWS SDK for Java 2.x, benötigen Sie diese Version oder eine höhere Version. ## Erstellen Sie ein und ein `DocumentTableSchema` `DynamoDbTable` [Um mithilfe der Enhanced Document API Befehle für eine DynamoDB-Tabelle aufzurufen, verknüpfen Sie die Tabelle mit einem clientseitigen DynamoDbTable < > -Ressourcenobjekt. EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) Die `table()` Methode des erweiterten Clients erstellt eine `DynamoDbTable` Instanz und benötigt Parameter für den DynamoDB-Tabellennamen und a. `DocumentTableSchema` Der Builder für a [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)erfordert einen primären Indexschlüssel und einen oder mehrere Attributkonverter-Anbieter. Die `AttributeConverterProvider.defaultProvider()` Methode stellt Konverter für [Standardtypen](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html) bereit. Sie sollte auch dann angegeben werden, wenn Sie einen benutzerdefinierten Attributkonverter-Anbieter angeben. Sie können dem Builder einen optionalen sekundären Indexschlüssel hinzufügen. Der folgende Codeausschnitt zeigt den Code, der die clientseitige Darstellung einer DynamoDB-Tabelle generiert, in der schemalose Objekte gespeichert `person` werden. `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. ``` Im Folgenden wird die JSON-Darstellung eines Objekts gezeigt, die in diesem Abschnitt verwendet wird`person`. ### `person`JSON-Objekt ``` { "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" } ] } ``` # Erstellen Sie erweiterte Dokumente An `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` steht für ein Objekt vom Typ Dokument mit einer komplexen Struktur mit verschachtelten Attributen. An `EnhancedDocument` erfordert Attribute der obersten Ebene, die den für den angegebenen Primärschlüsselattributen entsprechen. `DocumentTableSchema` Der restliche Inhalt ist willkürlich und kann aus Attributen der obersten Ebene und auch tief verschachtelten Attributen bestehen. Sie erstellen eine `EnhancedDocument` Instanz mithilfe eines Builders, der mehrere Möglichkeiten zum Hinzufügen von Elementen bietet. ## Aus einer JSON-Zeichenfolge erstellen Mit einer JSON-Zeichenfolge können Sie einen Methodenaufruf `EnhancedDocument` in einem Schritt erstellen. Das folgende Snippet erstellt `EnhancedDocument` aus einer JSON-Zeichenfolge, die von der `jsonPerson()` Hilfsmethode zurückgegeben wird. Die `jsonPerson()` Methode gibt die JSON-String-Version des zuvor gezeigten [Personenobjekts](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) zurück. ``` EnhancedDocument document = EnhancedDocument.builder() .json( jsonPerson() ) .build()); ``` ## Aus einzelnen Elementen zusammensetzen Alternativ können Sie mit den typsicheren Methoden des Builders eine `EnhancedDocument` Instanz aus einzelnen Komponenten erstellen. Im folgenden Beispiel wird ein `person` erweitertes Dokument erstellt, das dem erweiterten Dokument ähnelt, das aus der JSON-Zeichenfolge im vorherigen Beispiel erstellt wurde. ``` /* 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(); ``` ### Hilfsmethoden ``` 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")); } ``` # Führen Sie CRUD-Operationen durch Nachdem Sie eine `EnhancedDocument` Instanz definiert haben, können Sie sie in einer DynamoDB-Tabelle speichern. Der folgende Codeausschnitt verwendet das [PersonDocument, das aus einzelnen Elementen](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) erstellt wurde. ``` documentDynamoDbTable.putItem(personDocument); ``` Nachdem Sie eine erweiterte Dokumentinstanz aus DynamoDB gelesen haben, können Sie die einzelnen Attributwerte mithilfe von Getter extrahieren, wie im folgenden Codeausschnitt gezeigt, die auf die Daten zugreifen, die aus dem gespeichert wurden. `personDocument` Alternativ können Sie den gesamten Inhalt in eine JSON-Zeichenfolge extrahieren, wie im letzten Teil des Beispielcodes gezeigt. ``` // 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`Instanzen können mit jeder Methode von `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` oder [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)anstelle von zugewiesenen Datenklassen verwendet werden. # Greifen Sie als benutzerdefinierte Objekte auf erweiterte Dokumentattribute zu Die Enhanced Document API bietet nicht nur eine API zum Lesen und Schreiben von Attributen mit schemalosen Strukturen, sondern ermöglicht auch die Konvertierung von Attributen in und aus Instanzen benutzerdefinierter Klassen. Die Enhanced Document API verwendet `AttributeConverterProvider` s und `AttributeConverter` s, die im Abschnitt zur [Konvertierung von Steuerattributen](ddb-en-client-adv-features-conversion.md) als Teil der DynamoDB Enhanced Client API angezeigt wurden. Im folgenden Beispiel verwenden wir a `CustomAttributeConverterProvider` mit seiner verschachtelten `AddressConverter` Klasse, um Objekte zu konvertieren. `Address` Dieses Beispiel zeigt, dass Sie Daten aus Klassen und auch Daten aus Strukturen kombinieren können, die nach Bedarf erstellt werden. Dieses Beispiel zeigt auch, dass benutzerdefinierte Klassen auf jeder Ebene einer verschachtelten Struktur verwendet werden können. Die `Address` Objekte in diesem Beispiel sind Werte, die in einer Map verwendet werden. ``` 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'} ``` ## `CustomAttributeConverterProvider`-Code ``` 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; } } } ``` ## `Address`-Klasse ``` 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; } } ``` ## Hilfsmethode, die Adressen bereitstellt Die folgende Hilfsmethode stellt die Map bereit, die benutzerdefinierte `Address` Instanzen für Werte anstelle von generischen `Map` Instanzen für Werte verwendet. ``` 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); } ``` # Verwenden Sie eine `EnhancedDocument` ohne DynamoDB Normalerweise verwenden Sie eine Instanz von an, `EnhancedDocument` um DynamoDB-Elemente vom Typ Dokument zu lesen und zu schreiben, sie kann jedoch auch unabhängig von DynamoDB verwendet werden. Sie können ihre Fähigkeit verwenden`EnhancedDocuments`, zwischen JSON-Zeichenfolgen oder benutzerdefinierten Objekten in Low-Level-Maps von `AttributeValues` zu konvertieren, wie im folgenden Beispiel gezeigt. ``` 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'} */ ``` **Anmerkung** Wenn Sie ein erweitertes Dokument verwenden, das unabhängig von einer DynamoDB-Tabelle ist, stellen Sie sicher, dass Sie im Builder explizit Attributkonverter-Anbieter festlegen. Im Gegensatz dazu stellt das Dokumenttabellenschema die Konverteranbieter bereit, wenn ein erweitertes Dokument mit einer DynamoDB-Tabelle verwendet wird.