在适用于 Java 的 亚马逊云科技 开发工具包 2.x 中介绍适用于 DynamoDB 的增强文档 API

作者： 约翰·维加 斯 | 2023 日

我们很高兴地宣布，适用于 Java 2.x 的 亚马逊云科技 开发工具包 现在提供适用于 DynamoDB 的增强文档 API，为处理 A mazon DynamoDB 项目提供了一种增强的方式。
这篇文章介绍了如何在 DynamoDB 增强版客户端中使用适用于 DynamoDB 的 增强文档 API。 通过使用增强文档 API，您可以创建一个 Enhan cedDocum ent 实例来表示没有固定架构的项目，然后使用 DynamoDB 增强客户端读取和写入 DynamoDB。
此外，与提供类型不安全的参数和返回类型的 aws-sdk-java 1.x 的文档 API 不同，增强型文档提供用于处理文档的强类型化 API。该接口简化了开发过程并确保了数据的正确输入。

先决条件：

开始之前，请确保您使用的是最新版本的 亚马逊云科技 Java SDK 依赖项，其中包含所有最新发布的错误修复和功能。要获得增强文档 API 支持，您必须使用 2.20.33 或更高版本。有关如何管理 项目中的 亚马逊云科技 Java 开发工具包依赖关系的详细信息，请参阅我们的 “ 设置 Apache Maven 项目 ” 指南。

在 pom.xml 中添加对动态增强版的依赖关系。 

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>dynamodb-enhanced</artifactId>
    <version>2.20.33</version>
</dependency>

使用增强文档 API 与 DDB 进行交互的快速演练

步骤 1：创建 DynamoDB 增强型客户端

创建 DynamodBenhancedClient 类的实例，该类为 Amazon DynamoDB 提供了一个高级接口，可以简化 DynamoDB 表的使用。 

DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                                               .dynamoDbClient(DynamoDbClient.create())
                                               .build();

步骤 2：使用文档表架构创建 DynamodbTable 资源对象

要使用增强文档 API 对 DynamoDB 表执行命令，必须将该表与您的文档表架构关联以创建 DynamoD BTable 资源对象。文档表架构生成器需要主索引键和属性转换器提供商。使用 A ttributeConverterProvider.defaultProvider () 来转换默认类型的文档属性 。 可以向生成器中添加可选的二级索引键。 


DynamoDbTable<EnhancedDocument> documentTable = enhancedClient.table("my_table",
                                              TableSchema.documentSchemaBuilder()
                                                         .addIndexPartitionKey(TableMetadata.primaryIndexName(),"hashKey", AttributeValueType.S)
                                                         .addIndexSortKey(TableMetadata.primaryIndexName(), "sortKey", AttributeValueType.N)
                                                         .attributeConverterProviders(AttributeConverterProvider.defaultProvider())
                                                         .build());
                                                         
// call documentTable.createTable() if "my_table" does not exist in DynamoDB

步骤 3：使用增强文档编写 DynamoDB 项目

En hancedDocument 类具有静态工厂方法以及 用于向文档 添加属性的 生成器 方法。以下代码段演示了在构造 文档项目 时由 enhancedDoc ument 提供的类型安全性。 

EnhancedDocument simpleDoc = EnhancedDocument.builder()
 .attributeConverterProviders(defaultProvider())
 .putString("hashKey", "sampleHash")
 .putNull("nullKey")
 .putNumber("sortKey", 1.0)
 .putBytes("byte", SdkBytes.fromUtf8String("a"))
 .putBoolean("booleanKey", true)
 .build();
 
documentTable.putItem(simpleDoc);

步骤 4：将 Dynamo 数据库项目作为增强文档读取

可以使用 getter 方法访问从 DynamoDB 表中检索到的文档的属性 

EnhancedDocument docGetItem = documentTable.getItem(r -> r.key(k -> k.partitionValue("samppleHash").sortValue(1)));

docGetItem.getString("hashKey");
docGetItem.isNull("nullKey")
docGetItem.getNumber("sortKey").floatValue();
docGetItem.getBytes("byte");
docGetItem.getBoolean("booleanKey");

用于以自定义对象形式访问文档属性的属性转换器提供商

您可以向 EnhancedDocument 提供自定义 A ttribute ConverterProvider 实例，以将文档 属性 转换为特定的对象类型。
可以在 DocumentT ableSchema 或 En hancedDocum ent 上设置这些提供器 ， 以便将属性作为自定义对象读取或写入。 

TableSchema.documentSchemaBuilder()
           .attributeConverterProviders(CustomClassConverterProvider.create(), defaultProvider())
           .build();
    
// Insert a custom class instance into an EnhancedDocument as attribute 'customMapOfAttribute'.
EnhancedDocument customAttributeDocument =
EnhancedDocument.builder().put("customMapOfAttribute", customClassInstance, CustomClass.class).build();

// Retrieve attribute 'customMapOfAttribute' as CustomClass object.
CustomClass customClassObject = customAttributeDocument.get("customMapOfAttribute", CustomClass.class);

将文档转换为 JSON，反之亦然

增强文档 API 允许您将 JSON 字符串转换为 增强文档，反之亦然 。 

// Enhanced document created from JSON string using defaultConverterProviders.
EnhancedDocument documentFromJson = EnhancedDocument.fromJson("{\"key\": \"Value\"}")
                                              
// Converting an EnhancedDocument to JSON string "{\"key\": \"Value\"}"                                                 
String jsonFromDocument = documentFromJson.toJson();

定义自定义属性转换器提供商

自定义属性转换器提供者是 Att ributeConverterProvider 的实现 ，它为自定义类提供 转换器。
以下是 cu stomClassforDocumentAPI 的示例，其单个字段为字符串类型 的 StringAttribute 及其相应的 Attribute Con verterProvider 实现。 

public class CustomClassForDocumentAPI {
    private final String stringAttribute;

    public CustomClassForDocumentAPI(Builder builder) {
        this.stringAttribute = builder.stringAttribute;
    }
    public static Builder builder() {
        return new Builder();
    }
    public String stringAttribute() {
        return stringAttribute;
    }
    public static final class Builder {
        private String stringAttribute;
        private Builder() {
        }
        public Builder stringAttribute(String stringAttribute) {
            this.stringAttribute = string;
            return this;
        }
        public CustomClassForDocumentAPI build() {
            return new CustomClassForDocumentAPI(this);
        }
    }
}
import java.util.Map;
import software.amazon.awssdk.enhanced.dynamodb.AttributeConverter;
import software.amazon.awssdk.enhanced.dynamodb.AttributeConverterProvider;
import software.amazon.awssdk.enhanced.dynamodb.EnhancedType;
import software.amazon.awssdk.utils.ImmutableMap;

public class CustomAttributeForDocumentConverterProvider implements AttributeConverterProvider {
    private final Map<EnhancedType<?>, AttributeConverter<?>> converterCache = ImmutableMap.of(
        EnhancedType.of(CustomClassForDocumentAPI.class), new CustomClassForDocumentAttributeConverter());
        // Different types of converters can be added to this map.

    public static CustomAttributeForDocumentConverterProvider create() {
        return new CustomAttributeForDocumentConverterProvider();
    }

    @Override
    public <T> AttributeConverter<T> converterFor(EnhancedType<T> enhancedType) {
        return (AttributeConverter<T>) converterCache.get(enhancedType);
    }
}

自定义属性转换器是 A ttributeConv erter 的实现 ，它可以将自定义类与属性值映射进行转换，如下所示。 

import java.util.LinkedHashMap;
import java.util.Map;
import software.amazon.awssdk.enhanced.dynamodb.AttributeConverter;
import software.amazon.awssdk.enhanced.dynamodb.AttributeValueType;
import software.amazon.awssdk.enhanced.dynamodb.EnhancedType;
import software.amazon.awssdk.enhanced.dynamodb.internal.converter.attribute.EnhancedAttributeValue;
import software.amazon.awssdk.enhanced.dynamodb.internal.converter.attribute.StringAttributeConverter;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;

public class CustomClassForDocumentAttributeConverter implements AttributeConverter<CustomClassForDocumentAPI> {
    public static CustomClassForDocumentAttributeConverter create() {
        return new CustomClassForDocumentAttributeConverter();
    }
    @Override
    public AttributeValue transformFrom(CustomClassForDocumentAPI input) {
        Map<String, AttributeValue> attributeValueMap = new LinkedHashMap<>();
        if(input.string() != null){
            attributeValueMap.put("stringAttribute", AttributeValue.fromS(input.string()));
        }
        return EnhancedAttributeValue.fromMap(attributeValueMap).toAttributeValue();
    }

    @Override
    public CustomClassForDocumentAPI transformTo(AttributeValue input) {
        Map<String, AttributeValue> customAttr = input.m();
        CustomClassForDocumentAPI.Builder builder = CustomClassForDocumentAPI.builder();
        if (customAttr.get("stringAttribute") != null) {
            builder.stringAttribute(StringAttributeConverter.create().transformTo(customAttr.get("stringAttribute")));
        }
        return builder.build();
    }
    @Override
    public EnhancedType<CustomClassForDocumentAPI> type() {
        return EnhancedType.of(CustomClassForDocumentAPI.class);
    }
    @Override
    public AttributeValueType attributeValueType() {
        return AttributeValueType.M;
    }
}

增强型文档生成器的属性转换器提供商

在 DynamoDB 表上下文之外工作时，请务必在 EnhancedDocument 生成器上明确设置属性转换器提供程序 。 在 DynamoDB 表上下文中使用时，表架构的转换器提供程序将自动用于 EnhancedDocument。
下面的代码片段显示了如何使用 EnhancedDocument 生成器方法设置 A ttributeConverterProvid er。 

// Enhanced document created from JSON string using custom AttributeConverterProvider.
EnhancedDocument documentFromJson = EnhancedDocument.builder()
                                                    .attributeConverterProviders(CustomClassConverterProvider.create())
                                                    .json("{\"key\": \"Values\"}")
                                                    .build();
                                                    
CustomClassForDocumentAPI customClass = documentFromJson.get("key", CustomClassForDocumentAPI.class)

结论

在这篇博客文章中，我们向您展示了如何在 DynamoDB 增强型客户端中设置和开始使用增强文档 API，以及如何在 EnhancedD ocument 类中独立使用 增强 文档 API。增强版客户端是开源的，与适用于 Java 2.0 的 亚马逊云科技 开发工具包 位于同一个存储库中。更多与此相关的示例，请访问我们的 开发者指南 。我们希望您会发现这项新功能很有用。您可以随时在我们的 GitHub 问题页面 上分享您的反馈 。

作者简介：

Hayden Baker

约翰·维加斯

约翰·维加斯担任亚马逊网络服务 (亚马逊云科技) Java SDK 团队的软件开发工程师。他热衷于增强开发者体验，积极参与旨在提升软件开发水平的项目和工具。要进一步了解他的贡献，请随时在 @joviegas 账号下浏览他的 GitHub 个人资料。

*前述特定亚马逊云科技生成式人工智能相关的服务仅在亚马逊云科技海外区域可用，亚马逊云科技中国仅为帮助您发展海外业务和/或了解行业前沿技术选择推荐该服务。