本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用适用于 DynamoDB 的增强型文档 API 处理 JSON 文档
的[增强型文档 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) AWS SDK for Java 2.x 旨在处理没有固定架构的面向文档的数据。该 API 也允许您使用自定义类来映射单个属性。
增强型文档 API 是 适用于 Java 的 AWS SDK 1.x 版[文档 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) 的继任者。
**Contents**
+ [开始使用增强型文档 API](ddb-en-client-doc-api-steps.md)
+ [创建 `DocumentTableSchema` 和 `DynamoDbTable`。](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [生成增强型文档](ddb-en-client-doc-api-steps-create-ed.md)
+ [使用 JSON 字符串生成](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [基于单个元素构建](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [执行 CRUD 操作](ddb-en-client-doc-api-steps-use.md)
+ [将增强型文档属性作为自定义对象进行访问](ddb-en-client-doc-api-convert.md)
+ [在没有 DynamoDB 的情况下使用 `EnhancedDocument`](ddb-en-client-doc-api-standalone.md)
# 开始使用增强型文档 API
增强型文档 API 所需的[依赖项](ddb-en-client-getting-started.md#ddb-en-client-gs-dep)与 DynamoDB 增强型客户端 API 所需的依赖项相同。它还需要一个 [`DynamoDbEnhancedClient` 实例](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient)，如本主题开头所示。
由于增强型文档 API 是在 2.20.3 版本中发布的 AWS SDK for Java 2.x，因此您需要该版本或更高版本。
## 创建 `DocumentTableSchema` 和 `DynamoDbTable`。
要使用增强文档 API 对 DynamoDB 表调用命令，请将该表与[DynamoDbTable客户端 EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) < > 资源对象相关联。
增强型客户端的 `table()` 方法会创建一个 `DynamoDbTable` 实例，并且需要用于 DynamoDB 表名称和 `DocumentTableSchema` 的参数。
的生成器[DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)需要主索引键和一个或多个属性转换器提供程序。`AttributeConverterProvider.defaultProvider()` 方法为[默认类型](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html)提供转换器。即使您提供了自定义属性转换器提供程序，也应指定它。您可以向生成器添加可选的二级索引键。
以下代码段显示的代码将生成一个 DynamoDB `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.
```
以下显示了本部分中使用的 `person` 对象的 JSON 表示形式。
### JSON `person` 对象
```
{
"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"
}
]
}
```
# 生成增强型文档
`[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` 表示具有复杂结构和嵌套属性的文档类型对象。`EnhancedDocument` 需要与为 `DocumentTableSchema` 指定的主键属性相匹配的顶级属性。其余内容是任意的，可以由顶级属性以及深度嵌套的属性组成。
您可以使用提供多种元素添加方法的生成器来创建 `EnhancedDocument` 实例。
## 使用 JSON 字符串生成
使用 JSON 字符串，您可以在一个方法调用中生成 `EnhancedDocument`。以下代码段从 `jsonPerson()` 帮助程序方法返回的 JSON 字符串创建一个 `EnhancedDocument`。`jsonPerson()` 方法返回前面显示的 [person 对象](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj)的 JSON 字符串版本。
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## 基于单个元素构建
或者，您可以使用生成器的类型安全方法从各个组件生成 `EnhancedDocument` 实例。
以下示例生成一个 `person` 增强型文档，该文档类似于上一个示例中从 JSON 字符串生成的增强型文档。
```
/* 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();
```
### 帮助程序方法
```
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"));
}
```
# 执行 CRUD 操作
定义 `EnhancedDocument` 实例后，您可以将其保存到 DynamoDB 表。以下代码段使用基于单个元素创建的 [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)。
```
documentDynamoDbTable.putItem(personDocument);
```
读取 DynamoDB 中的增强型文档实例后，您可以使用 getter 提取各个属性值，如以下代码段所示，这些代码段用于访问从 `personDocument` 中保存的数据。或者，您可以将完整内容提取为 JSON 字符串，如示例代码的最后一部分所示。
```
// 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`实例可以与映射的数据类的任何方法一起使用 [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)，`[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)`也可以代替映射的数据类。
# 将增强型文档属性作为自定义对象进行访问
除了提供用于读取和写入具有无架构结构的属性的 API 之外，增强型文档 API 还允许您在自定义类的实例之间转换属性。
增强型文档 API 使用[控制属性转换](ddb-en-client-adv-features-conversion.md)部分中显示的 `AttributeConverterProvider` 和 `AttributeConverter`，作为 DynamoDB 增强型客户端 API 的一部分。
在以下示例中，我们使用 `CustomAttributeConverterProvider` 及其嵌套 `AddressConverter` 类来转换 `Address` 对象。
此示例表明，您可以混合类中的数据以及根据需要构建的结构中的数据。此示例还表明，自定义类可以在嵌套结构的任何级别上使用。此示例中的 `Address` 对象是映射中使用的值。
```
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` 代码
```
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` 类
```
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;
}
}
```
## 提供地址的帮助程序方法
以下帮助程序方法提供的映射使用自定义 `Address` 实例作为值，而不是使用通用 `Map` 实例作为值。
```
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);
}
```
# 在没有 DynamoDB 的情况下使用 `EnhancedDocument`
尽管您通常使用 `EnhancedDocument` 的实例来读取和写入文档类型的 DynamoDB 项目，但它也可以独立于 DynamoDB 使用。
您可以使用 `EnhancedDocuments` 的功能，在 JSON 字符串或自定义对象之间，执行到 `AttributeValues` 的低级映射的转换，如以下示例所示。
```
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'}
*/
```
**注意**
当您独立于 DynamoDB 表使用增强型文档时，请务必在生成器上明确设置属性转换器提供程序。
相比之下，当增强型文档与 DynamoDB 表结合使用时，文档表架构会提供转换器提供程序。