| 直接可恢复对象 | 不支持 |
### 结果对象
| V1 类 | V2 类 | 迁移状态 |
| --- | --- | --- |
| CopyResult | CompletedCopy | 支持 |
| UploadResult | CompletedUpload | 支持 |
### 配置对象
| V1 类 | V2 类 | 迁移状态 |
| --- | --- | --- |
| TransferManagerConfiguration | MultipartConfiguration（在 Amazon S3 客户端上） | 支持 |
| TransferProgress | TransferProgress \$1 TransferProgressSnapshot | 支持 |
| KeyFilter | DownloadFilter | 支持 |
### 不支持的对象
| V1 类 | V2 替代方案 | 迁移状态 |
| --- | --- | --- |
| PauseStatus | 不支持 | 不支持 |
| UploadContext | 不支持 | 不支持 |
| ObjectCannedAclProvider | PutObjectRequest.builder().acl() | 不支持 |
| ObjectMetadataProvider | PutObjectRequest.builder().metadata() | 不支持 |
| ObjectTaggingProvider | PutObjectRequest.builder().tagging() | 不支持 |
| PresignedUrlDownload | 不支持 | 不支持 |
## TransferManagerBuilder 配置迁移
### 配置更改
您需要为 v2 传输管理器设置的配置更改取决于您使用的 S3 客户端。您可以选择 AWS 基于 CRT 的 S3 客户端或基于 Java 的标准的 S3 异步客户端。有关差异的信息，请参阅 [中的 S3 客户端 AWS SDK for Java 2.x](examples-s3.md#s3-clients) 主题。
------
#### [ Use the AWS CRT-based S3 client ]
****
| 设置 | v1 | v2-使用 AWS 基于 CRT 的 S3 客户端的传输管理器 |
| --- | --- | --- |
| （获取生成器） | TransferManagerBuilder tmBuilder =
TransferManagerBuilder.standard();
| S3TransferManager.Builder tmBuilder =
S3TransferManager.builder();
|
| S3 客户端 | tmBuilder.withS3Client(...);
tmBuilder.setS3Client(...);
| tmBuilder.s3Client(...);
|
| 执行程序 | tmBuilder.withExecutorFactory(...);
tmBuilder.setExecutorFactory(...);
| tmBuilder.executor(...);
|
| 关闭线程池 | tmBuilder.withShutDownThreadPools(...);
tmBuilder.setShutdownThreadPools(...);
| 不支持。关闭 S3TransferManager 时，不会关闭提供的执行程序 |
| 最小上传段大小 | tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
|
| 分段上传阈值 | tmBuilder.withMultipartUploadThreshold(...);
tmBuilder.setMultipartUploadThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
|
| 最小复制段大小 | tmBuilder.withMultipartCopyPartSize(...);
tmBuilder.setMultipartCopyPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
|
| 分段复制阈值 | tmBuilder.withMultipartCopyThreshold(...);
tmBuilder.setMultipartCopyThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
|
| 禁用并行下载 | tmBuilder.withDisableParallelDownloads(...);
tmBuilder.setDisableParallelDownloads(...);
| 通过将默认禁用分段的基于 Java 的标准 S3 客户端传递给 Transfer Manager 来禁用并行下载。S3AsyncClient s3 =
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
|
| 始终计算分段 md5 | tmBuilder.withAlwaysCalculateMultipartMd5(...);
tmBuilder.setAlwaysCalculateMultipartMd5(...);
| 不支持。 |
------
#### [ Use Java-based S3 async client ]
****
| 设置 | v1 | v2 - 使用基于 Java 的 S3 异步客户端的 Transfer Manager |
| --- | --- | --- |
| （获取生成器） | TransferManagerBuilder tmBuilder =
TransferManagerBuilder.standard();
| S3TransferManager.Builder tmBuilder =
S3TransferManager.builder();
|
| S3 客户端 | tmBuilder.withS3Client(...);
tmBuilder.setS3Client(...);
| tmBuilder.s3Client(...);
|
| 执行程序 | tmBuilder.withExecutorFactory(...);
tmBuilder.setExecutorFactory(...);
| tmBuilder.executor(...);
|
| 关闭线程池 | tmBuilder.withShutDownThreadPools(...);
tmBuilder.setShutdownThreadPools(...);
| 不支持。关闭 S3TransferManager 时，不会关闭提供的执行程序 |
| 最小上传段大小 | tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| 分段上传阈值 | tmBuilder.withMultipartUploadThreshold(...);
tmBuilder.setMultipartUploadThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| 最小复制段大小 | tmBuilder.withMultipartCopyPartSize(...);
tmBuilder.setMultipartCopyPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| 分段复制阈值 | tmBuilder.withMultipartCopyThreshold(...);
tmBuilder.setMultipartCopyThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| 禁用并行下载 | tmBuilder.withDisableParallelDownloads(...);
tmBuilder.setDisableParallelDownloads(...);
| 通过将默认禁用分段的基于 Java 的标准 S3 客户端传递给 Transfer Manager 来禁用并行下载。S3AsyncClient s3 =
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
|
| 始终计算分段 md5 | tmBuilder.withAlwaysCalculateMultipartMd5(...);
tmBuilder.setAlwaysCalculateMultipartMd5(...);
| 不支持。 |
------
## 行为更改
### 异步操作
**V1（阻塞）：**
```
Upload upload = transferManager.upload("amzn-s3-demo-bucket", "key", file);
upload.waitForCompletion(); // Blocks until complete
```
**V2（异步）：**
```
FileUpload upload = transferManager.uploadFile(UploadFileRequest.builder()
.putObjectRequest(PutObjectRequest.builder()
.bucket("amzn-s3-demo-bucket")
.key("key")
.build())
.source(file)
.build());
CompletedFileUpload result = upload.completionFuture().join(); // Blocks until complete
// Or handle asynchronously:
upload.completionFuture().thenAccept(result -> {
System.out.println("Upload completed: " + result.response().eTag());
});
```
### 错误处理
**V1：**如果任何子请求失败，则目录传输将完全失败。
**V2：**即使某些子请求失败，目录传输也会成功完成。明确检查错误：
```
DirectoryUpload directoryUpload = transferManager.uploadDirectory(request);
CompletedDirectoryUpload result = directoryUpload.completionFuture().join();
// Check for failed transfers
if (!result.failedTransfers().isEmpty()) {
System.out.println("Some uploads failed:");
result.failedTransfers().forEach(failed ->
System.out.println("Failed: " + failed.exception().getMessage()));
}
```
### 通过字节范围提取进行并行下载
在 v2 SDK 中启用自动并行传输功能后，S3 Transfer Manager 使用[字节范围提取](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance-guidelines.html#optimizing-performance-guidelines-get-range)来并行检索对象的特定部分（分段下载）。使用 v2 下载对象的方式不取决于对象最初的上传方式。所有下载都可以从高吞吐量和并发性中受益。
相比之下，使用 v1 Transfer Manager 时，对象最初的上传方式确实很重要。v1 Transfer Manager 检索对象各个分段的方式与上传分段的方式相同。如果对象最初是作为单个对象上传的，则 v1 Transfer Manager 无法通过使用子请求来加速下载过程。
# 在解析 Amazon S3 时 URIs 从版本 1 到版本 2 的变化
本主题详细介绍了解析 Amazon S3 URIs 从版本 1 (v1) 到版本 2 (v2.) 时所做的更改。
## 高级别更改
在 v1 中，要开始解析 S3 URI，可使用构造函数对 `AmazonS3URI` 进行实例化。在 v2 中，在 `S3Utilities` 的实例上调用 `parseUri()`，以便返回 `S3URI`。
****
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
s3
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
s3
|
| 软件包名称 | com.amazonaws.services.s3 | software.amazon.awssdk.services.s3 |
| 类名 | [AmazonS3URI](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3URI.html) | [S3URI](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Uri.html) |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## API 更改
| 行为 | v1 | v2 |
| --- | --- | --- |
| 解析 S3 URI。 | URI uri = URI.create( "https://s3.amazonaws.com");
AmazonS3Uri s3Uri =
new AmazonS3URI(uri, false);
| S3Client s3Client = S3Client.create();
S3Utilities s3Utilities =
s3Client.utilities();
S3Uri s3Uri =
s3Utilities.parseUri(uri);
|
| 从 S3 URI 检索存储桶名称。 | String bucket = s3Uri.getBucket();
| Optional bucket = s3Uri.bucket();
|
| 检索密钥。 | String key = s3Uri.getKey();
| Optional key = s3Uri.key();
|
| 检索区域。 | String region = s3Uri.getRegion();
| Optional region = s3Uri.region();
String region;
if (s3Uri.region().isPresent()) {
region = s3Uri.region().get().id();
}
|
| 检索 S3 URI 是否为路径风格。 | boolean isPathStyle = s3Uri.isPathStyle();
| boolean isPathStyle = s3Uri.isPathStyle();
|
| 检索版本 ID。 | String versionId = s3Uri.getVersionId();
| Optional versionId =
s3Uri.firstMatchingRawQueryParameter("versionId");
|
| 检索查询参数。 | 不适用 | Map> queryParams =
s3Uri.rawQueryParameters();
|
### 行为更改
#### URL 编码
v1 提供了传入标志的选项，用于指定 URI 是否应进行 URL 编码。默认值为 `true`。
在 v2 中，不支持 URL 编码。如果您使用包含保留字符或不安全字符的对象键或查询参数，则必须对其进行 URL 编码。例如，您需要将空格 `" "` 替换为 `%20`。
# S3 事件通知 API 从版本 1 到版本 2 的更改
本主题详细说明了 S3 事件通知 API 从 适用于 Java 的 AWS SDK版本 1.x（v1）到版本 2（v2）的更改。
## 高级别更改
### 结构变化
V1 对 `EventNotificationRecord` 类型及其属性使用静态内部类，而 v2 对 `EventNotificationRecord` 类型使用单独的公共类。
### 命名约定更改
*在 v1 中，属性类名称包含后缀 Ent *it* y，而 v2 为了更简单的命名省略了这个后缀：例如，用 eventData 代替。*eventDataEntity**
## 依赖项、软件包和类名的更改
在 v1 中，S3 事件通知 API 类会随着 S3 模块（artifactId `aws-java-sdk-s3`）一起以传递依赖方式导入。但在 v2 中，您需要在 `s3-event-notifications` 构件上添加依赖项。
****
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-s3
|
software.amazon.awssdk
bom
2.X.X1
pom
import
software.amazon.awssdk
s3-event-notifications
|
| 软件包名称 | com.amazonaws.services.s3.event | software.amazon.awssdk.eventnotifications.s3.model |
| 类名 | [S3EventNotification](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.html) [S3 EventNotification .S3 EventNotificationRecord](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3EventNotificationRecord.html) [S3 EventNotification。 GlacierEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.GlacierEventDataEntity.html) [S3 EventNotification。 IntelligentTieringEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.IntelligentTieringEventDataEntity.html) [S3 EventNotification。 LifecycleEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.LifecycleEventDataEntity.html) [S3 EventNotification。 ReplicationEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ReplicationEventDataEntity.html) [S3 EventNotification。 RequestParametersEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RequestParametersEntity.html) [S3 EventNotification。 ResponseElementsEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ResponseElementsEntity.html) [S3 EventNotification。 RestoreEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RestoreEventDataEntity.html) [S3 EventNotification .S3 BucketEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3BucketEntity.html) [S3 EventNotification .S3Entity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3Entity.html) [S3 EventNotification .S3 ObjectEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3ObjectEntity.html) [S3 EventNotification。 TransitionEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.TransitionEventDataEntity.html) [S3 EventNotification。 UserIdentityEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.UserIdentityEntity.html) | [S3EventNotification](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotification.html) [S3EventNotificationRecord](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotificationRecord.html) [GlacierEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/GlacierEventData.html) [IntelligentTieringEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/IntelligentTieringEventData.html) [LifecycleEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/LifecycleEventData.html) [ReplicationEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/ReplicationEventData.html) [RequestParameters](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/RequestParameters.html) [ResponseElements](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/ResponseElements.html) [RestoreEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/RestoreEventData.html) [S3Bucket](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3Bucket.html) [S3](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3.html) [S3OBJECT](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3Object.html) [TransitionEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/TransitionEventData.html) [UserIdentity](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/UserIdentity.html) |
1 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## API 更改
### JSON 和 `S3EventNotification` 的相互转换
| 使用案例 | v1 | v2 |
| --- | --- | --- |
| 从 JSON 字符串创建 S3EventNotification | S3EventNotification notification =
S3EventNotification.parseJson(message.body());
| S3EventNotification notification =
S3EventNotification.fromJson(message.body());
|
| 将 S3EventNotification 转换为 JSON 字符串 | String json = notification.toJson();
| String json = notification.toJson();
|
### `S3EventNotification` 的访问属性
| 使用案例 | v1 | v2 |
| --- | --- | --- |
| 从通知中检索记录 | List records =
notifcation.getRecords();
| List records =
notification.getRecords();
|
| 从记录列表中检索记录 | S3EventNotification.S3EventNotificationRecord record =
records.stream().findAny().get();
| S3EventNotificationRecord record =
records.stream().findAny().get();
|
| 检索 Glacier 事件数据 | S3EventNotification.GlacierEventDataEntity glacierEventData =
record.getGlacierEventData();
| GlacierEventData glacierEventData =
record.getGlacierEventData();
|
| 从 Glacier 事件中检索还原事件数据 | S3EventNotification.RestoreEventDataEntity restoreEventData =
glacierEventData.getRestoreEventDataEntity();
| RestoreEventData restoreEventData =
glacierEventData.getRestoreEventData();
|
| 检索请求参数 | S3EventNotification.RequestParametersEntity requestParameters =
record.getRequestParameters();
| RequestParameters requestParameters =
record.getRequestParameters();
|
| 检索智能分层事件数据 | S3EventNotification.IntelligentTieringEventDataEntity tieringEventData =
record.getIntelligentTieringEventData();
| IntelligentTieringEventData intelligentTieringEventData =
record.getIntelligentTieringEventData();
|
| 检索生命周期事件数据 | S3EventNotification.LifecycleEventDataEntity lifecycleEventData =
record.getLifecycleEventData();
| LifecycleEventData lifecycleEventData =
record.getLifecycleEventData();
|
| 以枚举形式检索事件名称 | S3Event eventNameAsEnum = record.getEventNameAsEnum();
| //getEventNameAsEnum does not exist; use 'getEventName()'
String eventName = record.getEventName();
|
| 检索复制事件数据 | S3EventNotification.ReplicationEventDataEntity replicationEntity =
record.getReplicationEventDataEntity();
| ReplicationEventData replicationEventData =
record.getReplicationEventData();
|
| 检索 S3 存储桶和对象信息 | S3EventNotification.S3Entity s3 = record.getS3();
| S3 s3 = record.getS3();
|
| 检索用户身份信息 | S3EventNotification.UserIdentityEntity userIdentity =
record.getUserIdentity();
| UserIdentity userIdentity =
record.getUserIdentity();
|
| 检索响应元素 | S3EventNotification.ResponseElementsEntity responseElements =
record.getResponseElements();
| ResponseElements responseElements =
record.getResponseElements();
|
## 迁移 `aws-lambda-java-events` 库版本
如果您习惯在 Lambda 函数中处理 S3 通知事件，我们建议您升级到最新的 3.x.x 版本。[aws-lambda-java-events](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events)最新版本消除了 S3 事件通知 API 中对 适用于 Java 的 AWS SDK 1.x 的所有依赖。
若要详细了解 `aws-lambda-java-events` 库和适用于 Java 的 SDK 2.x 在处理 S3 事件通知方面的差异，请参阅[使用 Java 库在 Lambda 中处理 S3 事件：以及 AWS SDK for Java 2.x `aws-lambda-java-events`](examples-s3-event-notifications.md#s3-event-notif-processing-options)。
# 配置文件更改
AWS SDK for Java 2.x 解析 `~/.aws/config` 和 `~/.aws/credentials` 中的配置文件定义，以便更贴近地模拟 AWS CLI 解析文件的方式。
适用于 Java 的 SDK 2.x：
+ 通过按顺序检查 `$HOME`、`$USERPROFILE`（仅 Windows）、`$HOMEDRIVE`、`$HOMEPATH`（仅 Windows），然后检查 `user.home` 系统属性，来解析路径开头处的 `~/` 或 `~`（后跟文件系统的默认路径分隔符）。
+ 查找 `AWS_SHARED_CREDENTIALS_FILE` 环境变量，而不是查找 `AWS_CREDENTIAL_PROFILES_FILE`。
+ 在配置文件中，如果配置项名称开头未包含单词 `profile`，则静默忽略该配置项定义。
+ 静默忽略不包含字母数字、下划线或连接号字符的配置项定义（为配置文件移除了开头的 `profile` 单词之后）。
+ 合并同一文件中重复的配置项定义的设置。
+ 合并配置文件和凭证文件中重复的配置项定义的设置。
+ 如果在同一个文件中找到 `[profile foo]` 和 `[foo]`，则不合并设置。
+ 如果在配置文件中找到 `[profile foo]` 和 `[foo]`，则使用 `[profile foo]` 中的设置。
+ 使用同一个文件和配置文件中最后一个重复设置的值。
+ 认识用于定义注释的 `;` 和 `#`。
+ 认识配置项定义中用于定义注释的 `;` 和 `#`，即使这些字符与右括号相邻也要认出来。
+ 只有当 `;` 和 `#` 前面有空格时，才在设置值中将其视为注释。
+ 只有当 `;` 和 `#` 前面没有空格时，才在设置值中将这些符号及后面的所有内容视为注释。
+ 将基于角色的凭证视为优先级最高的凭证。如果用户指定了 `role_arn` 属性，2.x SDK 将始终使用基于角色的凭证。
+ 将基于会话的凭证视为优先级第二高的凭证。如果未使用基于角色的凭证且用户指定了 `aws_access_key_id` 和 `aws_session_token` 属性，则 2.x SDK 将始终使用基于会话的凭证。
+ 如果未使用基于角色的凭证和基于会话的凭证且用户指定了 `aws_access_key_id` 属性，则使用基本凭证。
# 环境变量和系统属性更改
| 1.x 环境变量 | 1.x 系统属性 | 2.x 环境变量 | 2.x 系统属性 |
| --- | --- | --- | --- |
| AWS\$1ACCESS\$1KEY\$1IDAWS\$1ACCESS\$1KEY | aws.accessKeyId | AWS\$1ACCESS\$1KEY\$1ID | aws.accessKeyId |
| AWS\$1SECRET\$1KEYAWS\$1SECRET\$1ACCESS\$1KEY | aws.secretKey | AWS\$1SECRET\$1ACCESS\$1KEY | aws.secretAccessKey |
| AWS\$1SESSION\$1TOKEN | aws.sessionToken | AWS\$1SESSION\$1TOKEN | aws.sessionToken |
| AWS\$1REGION | aws.region | AWS\$1REGION | aws.region |
| AWS\$1CONFIG\$1FILE | | AWS\$1CONFIG\$1FILE | aws.configFile |
| AWS\$1CREDENTIAL\$1PROFILES\$1FILE | | AWS\$1SHARED\$1CREDENTIALS\$1FILE | aws.sharedCredentialsFile |
| AWS\$1PROFILE | aws.profile | AWS\$1PROFILE | aws.profile |
| AWS\$1EC2\$1METADATA\$1DISABLED | com.amazonaws.sdk.disableEc2Metadata | AWS\$1EC2\$1METADATA\$1DISABLED | aws.disableEc2Metadata |
| | com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | aws.ec2MetadataServiceEndpoint |
| AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI | | AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI | aws.containerCredentialsPath |
| AWS\$1CONTAINER\$1CREDENTIALS\$1FULL\$1URI | | AWS\$1CONTAINER\$1CREDENTIALS\$1FULL\$1URI | aws.containerCredentialsFullUri |
| AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN | | AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN | aws.containerAuthorizationToken |
| AWS\$1CBOR\$1DISABLED | com.amazonaws.sdk.disableCbor | CBOR\$1ENABLED | aws.cborEnabled |
| AWS\$1ION\$1BINARY\$1DISABLE | com.amazonaws.sdk.disableIonBinary | BINARY\$1ION\$1ENABLED | aws.binaryIonEnabled |
| AWS\$1EXECUTION\$1ENV | | AWS\$1EXECUTION\$1ENV | aws.executionEnvironment |
| | com.amazonaws.sdk.disableCertChecking | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） |
| | com.amazonaws.sdk.enableDefaultMetrics | [不支持](https://github.com/aws/aws-sdk-java-v2/issues/23) | [不支持](https://github.com/aws/aws-sdk-java-v2/issues/23) |
| | com.amazonaws.sdk.enableThrottledRetry | [不支持](https://github.com/aws/aws-sdk-java-v2/issues/645) | [不支持](https://github.com/aws/aws-sdk-java-v2/issues/645) |
| | com.amazonaws.regions.RegionUtils.fileOverride | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） |
| | com.amazonaws.regions.RegionUtils.disableRemote | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） |
| | com.amazonaws.services.s3.disableImplicitGlobalClients | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） |
| | com.amazonaws.sdk.enableInRegionOptimizedMode | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） | 不支持（[请求功能](https://github.com/aws/aws-sdk-java-v2/issues/new)） |
# Waiter 从版本 1 到版本 2 的变化
本主题详细介绍了 Waiter 的功能从版本 1（v1）到版本 2（v2）的变化。
下表展示了 DynamoDB Waiter 的具体差异。其他服务的 Waiter 也遵循同样的模式。
## 高级别更改
Waiter 类与服务位于相同的 Maven 构件中。
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.6801
pom
import
com.amazonaws
dynamodb
|
software.amazon.awssdk
bom
2.27.102
pom
import
software.amazon.awssdk
dynamodb
|
| 软件包名称 | com.amazonaws.services.dynamodbv2.waiters | software.amazon.awssdk.services.dynamodb.waiters |
| 类名 | `[AmazonDynamoDBWaiters](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/waiters/AmazonDynamoDBWaiters.html)` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/migration-waiters.html) |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## API 更改
| 更改 | v1 | v2 |
| --- | --- | --- |
| 创建 Waiter | AmazonDynamoDB client = AmazonDynamoDBClientBuilder
.standard().build();
AmazonDynamoDBWaiters waiter = client.waiters();
| 同步：DynamoDbClient client = DynamoDbClient.create();
DynamoDbWaiter waiter = client.waiter();
异步：DynamoDbAsyncClient asyncClient =
DynamoDbAsyncClient.create();
DynamoDbAsyncWaiter waiter = asyncClient.waiter();
|
| 等待表完成创建 | 同步：waiter.tableExists()
.run(new WaiterParameters<>(
new DescribeTableRequest(tableName)));
异步：waiter.tableExists()
.runAsync(new WaiterParameters()
.withRequest(new DescribeTableRequest(tableName)),
new WaiterHandler() {
@Override
public void onWaitSuccess(
AmazonWebServiceRequest amazonWebServiceRequest) {
System.out.println("Table creation succeeded");
}
@Override
public void onWaitFailure(Exception e) {
e.printStackTrace();
}
}).get();
| 同步： WaiterResponse waiterResponse =
waiter.waitUntilTableExists(
r -> r.tableName("myTable"));
waiterResponse.matched().response()
.ifPresent(System.out::println);
异步： waiter.waitUntilTableExists(r -> r.tableName(tableName))
.whenComplete((r, t) -> {
if (t != null) {
t.printStackTrace();
} else {
System.out.println(
"Table creation succeeded");
}
}).join();
|
## 配置更改
| 更改 | v1 | v2 |
| --- | --- | --- |
| 轮询策略（最大尝试次数和固定延迟） | MaxAttemptsRetryStrategy maxAttemptsRetryStrategy =
new MaxAttemptsRetryStrategy(10);
FixedDelayStrategy fixedDelayStrategy =
new FixedDelayStrategy(3);
PollingStrategy pollingStrategy =
new PollingStrategy(maxAttemptsRetryStrategy,
fixedDelayStrategy);
waiter.tableExists().run(
new WaiterParameters<>(
new DescribeTableRequest(tableName)),
pollingStrategy);
|
FixedDelayBackoffStrategy fixedDelayBackoffStrategy =
FixedDelayBackoffStrategy
.create(Duration.ofSeconds(3));
waiter.waitUntilTableExists(r -> r.tableName(tableName),
c -> c.maxAttempts(10)
.backoffStrategy(fixedDelayBackoffStrategy));
|
# EC2 元数据实用程序从版本 1 到版本 2 的变化
本主题详细介绍了 SDK for Java Amazon Elastic Compute Cloud（EC2）元数据实用程序从版本 1（v1）到版本 2（v2）的变化。
## 高级别更改
****
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
aws-java-sdk-core
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
apache-client3
|
| 软件包名称 | com.amazonaws.util | software.amazon.awssdk.imds |
| 实例化方法 | 使用静态实用程序方法；不进行实例化： String localHostName =
EC2MetadataUtils.getLocalHostName();
| 使用静态工厂方法： Ec2MetadataClient client = Ec2MetadataClient.create();
或者使用生成器方法： Ec2MetadataClient client = Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
|
| 客户端类型 | 仅同步实用程序方法：EC2MetadataUtils | 同步：`Ec2MetadataClient` 异步：`Ec2MetadataAsyncClient` |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
3 注意 v2 的 `apache-client` 模块声明。EC2 元数据实用程序的 V2 需要为同步元数据客户端实现 `SdkHttpClient` 接口，或为异步元数据客户端实现 `SdkAsyncHttpClient` 接口。[在中配置 HTTP 客户端 AWS SDK for Java 2.x](http-configuration.md)部分显示了您可以使用的 HTTP 客户端列表。
### 请求元数据
在 v1 中，您可以使用不接受任何参数的静态方法来请求 EC2 资源的元数据。相比之下，在 v2 中，您需要将 EC2 资源的路径指定为参数。下表显示了不同的方法。
****
| v1 | v2 |
| --- | --- |
| String userMetaData = EC2MetadataUtils.getUserData();
| Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response =
client.get("/latest/user-data");
String userMetaData =
response.asString();
|
请参阅[实例元数据类别](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instancedata-data-categories.html)，查找请求元数据时需要提供的路径。
**注意**
在 v2 中使用实例元数据客户端时，您应该针对检索元数据的所有请求使用同一客户端。
## 行为更改
### JSON 数据
在 EC2 上，本地运行的实例元数据服务（IMDS）以 JSON 格式的字符串形式返回一些元数据。[实例身份文档](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html)的动态元数据就是一个例子。
v1 API 针对每种实例身份元数据包含不同的方法，而 v2 API 会直接返回 JSON 字符串。要处理 JSON 字符串，您可以使用[文档 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) 解析响应并浏览 JSON 结构。
下表比较了在 v1 和 v2 中检索实例身份文档元数据的方式。
****
| 使用案例 | v1 | v2 |
| --- | --- | --- |
| 检索区域 | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String region = instanceInfo.getRegion();
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String region = instanceInfo.asMap().get("region").asString();
|
| 检索实例 ID | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String instanceId = instanceInfo.instanceId;
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceId = instanceInfo.asMap().get("instanceId").asString();
|
| 检索实例类型 | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String instanceType = instanceInfo.instanceType();
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceType = instanceInfo.asMap().get("instanceType").asString();
|
### 端点解析差异
下表显示了 SDK 为将端点解析到 IMDS 而检查的位置。这些位置按优先级降序列出。
****
| v1 | v2 |
| --- | --- |
| 系统属性：com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | 客户端生成器配置方法：endpoint(...) |
| 环境变量：AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | 系统属性：aws.ec2MetadataServiceEndpoint |
| 默认值：http://169.254.169.254 | Config 文件：\$1.aws/config，及 ec2\$1metadata\$1service\$1endpoint 设置 |
| | 与已解析的 endpoint-mode 相关联的值 |
| | 默认值：http://169.254.169.254 |
### v2 中的端点解析
如果您使用生成器显式设置端点，该端点值的优先级高于所有其他设置。当以下代码执行时，`aws.ec2MetadataServiceEndpoint` 系统属性和 config 文件 `ec2_metadata_service_endpoint` 设置如果存在，将被忽略。
```
Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpoint(URI.create("endpoint.to.use"))
.build();
```
#### 端点模式
在 v2 中，您可以指定端点模式，将元数据客户端配置为使用或的默认端点值。 IPv4 IPv6端点模式不适用于 v1。使用的默认值为`http://169.254.169.254`和 IPv4 fo `http://[fd00:ec2::254]` r IPv6。
下表按优先级降序显示了设置端点模式时可以采用的不同方法。
****
| | | 可能的值 |
| --- | --- | --- |
| 客户端生成器配置方法：endpointMode(...) | Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpointMode(EndpointMode.IPV4)
.build();
| EndpointMode.IPV4, EndpointMode.IPV6 |
| 系统属性 | aws.ec2MetadataServiceEndpointMode | IPv4、IPv6（大小写没有影响） |
| Config 文件：\$1.aws/config | ec2\$1metadata\$1service\$1endpoint 设置 | IPv4、IPv6（大小写没有影响） |
| 未在前面的方法中指定 | IPv4 被使用了 | |
#### 在 v2 中，SDK 如何解析`endpoint`或`endpoint-mode`
1. SDK 使用您通过客户端生成器在代码中设置的值，并忽略任何外部设置。由于在客户端生成器上同时调用 `endpoint` 和 `endpointMode` 时，SDK 会抛出异常，因此 SDK 将使用您所用的任一方法中的端点值。
1. 如果您没有在代码中设置值，SDK 会查看外部配置；首先查找系统属性，然后是 config 文件中的设置。
1. SDK 会先检查端点值。如果找到值，则使用该值。
1. 如果 SDK 仍未找到值，则会查找端点模式设置。
1. 最后，如果 SDK 未找到任何外部设置，并且您尚未在代码中配置元数据客户端，则 SDK 将使用 IPv4 值`http://169.254.169.254`。
### IMDSv2
Amazon EC2 定义了两种访问实例元数据的方法：
+ 实例元数据服务版本 1 (IMDSv1)-请求/响应方法
+ 实例元数据服务版本 2 (IMDSv2)-面向会话的方法
下表比较了 Java SDKs 如何与 IMDS 配合使用。
****
| v1 | v2 |
| --- | --- |
| IMDSv2 默认情况下使用 | 始终使用 IMDSv2 |
| 尝试为每个请求获取会话令牌， IMDSv1 如果无法获取会话令牌，则回退到会话令牌 | 将会话令牌保存在内部缓存中，该令牌可重复用于多个请求 |
适用于 Java 的 SDK 2.x 仅支持 IMDSv2 ，不能回退到。 IMDSv1
## 配置差异
下表列出了不同的配置选项。
****
| 配置 | v1 | v2 |
| --- | --- | --- |
| 重试 | 配置不可用 | 可通过生成器方法 retryPolicy(...) 配置 |
| HTTP | 连接超时可通过 AWS\$1METADATA\$1SERVICE\$1TIMEOUT 环境变量配置。默认值为 1 秒。 | 通过将 HTTP 客户端传递给生成器方法 httpClient(...) 即可进行配置。HTTP 客户端的默认连接超时为 2 秒。 |
### v2 HTTP 配置示例
以下示例演示了如何配置元数据客户端。此示例配置连接超时并使用 Apache HTTP 客户端。
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(1))
.build();
Ec2MetadataClient imdsClient = Ec2MetadataClient.builder()
.httpClient(httpClient)
.build();
```
# Amazon CloudFront 预签名从版本 1 更改为版本 2
本主题详细介绍了 Amazon CloudFront 从版本 1 (v1) 到版本 2 (v2) 的变化。
## 高级别更改
****
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
cloudfront
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
cloudfront
|
| 软件包名称 | com.amazonaws.services.cloudfront | software.amazon.awssdk.services.cloudfront |
| 类名 | [CloudFrontUrlSigner](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/cloudfront/CloudFrontUrlSigner.html) [CloudFrontCookieSigner](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/cloudfront/CloudFrontCookieSigner.html) | [CloudFrontUtilities](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/CloudFrontUtilities.html) [SignedUrl](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/url/SignedUrl.html) [CannedSignerRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/model/CannedSignerRequest.html) [CustomSignerRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/model/CustomSignerRequest.html) |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## API 更改
| 行为 | v1 | v2 |
| --- | --- | --- |
| 构建标准请求 | 参数直接传递给 API。 | CannedSignerRequest cannedRequest =
CannedSignerRequest.builder()
.resourceUrl(resourceUrl)
.privateKey(privateKey)
.keyPairId(keyPairId)
.expirationDate(expirationDate)
.build();
|
| 构建自定义请求 | 参数直接传递给 API。 | CustomSignerRequest customRequest =
CustomSignerRequest.builder()
.resourceUrl(resourceUrl)
.resourceUrlPattern(resourceUrlPattern)
.privateKey(keyFile)
.keyPairId(keyPairId)
.expirationDate(expirationDate)
.activeDate(activeDate)
.ipRange(ipRange)
.build();
|
| 生成签名 URL（标准） | String signedUrl =
CloudFrontUrlSigner.getSignedURLWithCannedPolicy(
resourceUrl, keyPairId, privateKey, expirationDate);
| CloudFrontUtilities cloudFrontUtilities =
CloudFrontUtilities.create();
SignedUrl signedUrl =
cloudFrontUtilities.getSignedUrlWithCannedPolicy(cannedRequest);
String url = signedUrl.url();
|
| 生成签名 Cookie（自定义） | CookiesForCustomPolicy cookies =
CloudFrontCookieSigner.getCookiesForCustomPolicy(
resourceUrl, privateKey, keyPairId, expirationDate,
activeDate, ipRange);
| CloudFrontUtilities cloudFrontUtilities =
CloudFrontUtilities.create();
CookiesForCustomPolicy cookies =
cloudFrontUtilities.getCookiesForCustomPolicy(customRequest);
|
### v2 中重构的 Cookie 标头
在 Java v1 中，Java SDK 以 `Map.Entry` 形式提供 Cookie 标头。
```
Map.Entry signatureMap = cookies.getSignature();
String signatureKey = signatureMap.getKey(); // "CloudFront-Signature"
String signatureValue = signatureMap.getValue(); // "[SIGNATURE_VALUE]"
```
Java v2 SDK 以单个 `String` 形式提供整个标头。
```
String signatureHeaderValue = cookies.signatureHeaderValue(); // "CloudFront-Signature=[SIGNATURE_VALUE]"
```
# IAM 策略生成器 API 从版本 1 到版本 2 的变化
本主题详细说明了 IAM 策略生成器 API 从版本 1（v1）到版本 2（v2）发生的变化。
## 高级别更改
****
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
aws-java-sdk-core
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
iam-policy-builder
|
| 软件包名称 | com.amazonaws.auth.policy | software.amazon.awssdk.policybuilder.iam |
| 类名 | [Policy](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Policy.html) [Statement](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Statement.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/migration-iam-policy-builder.html) | [IamPolicy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamPolicy.html) [IamStatement](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamStatement.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/migration-iam-policy-builder.html) |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## API 更改
****
| 设置 | v1 | v2 |
| --- | --- | --- |
| 实例化策略 | Policy policy = new Policy();
| IamPolicy.Builder policyBuilder = IamPolicy.builder();
...
IamPolicy policy = policyBuilder.build();
|
| 设置 ID | policy.withtId(...);
policy.setId(...);
| policyBuilder.id(...);
|
| 设置版本 | 不适用 - 使用默认版本 2012-10-17 | policyBuilder.version(...);
|
| 创建语句 | Statement statement =
new Statement(Effect.Allow)
.withActions(...)
.withConditions(...)
.withId(...)
.withPrincipals(...)
.withResources(...);
| IamStatement statement =
IamStatement.builder()
.effect(IamEffect.ALLOW)
.actions(...)
.notActions(...)
.conditions(...)
.sid(...)
.principals(...)
.notPrincipals(...)
.resources(...)
.notResources(...)
.build()
|
| 设置语句 | policy.withStatements(statement);
policy.setStatements(statement);
| policyBuilder.addStatement(statement);
|
## 构建语句时的差异
### 操作
#### v1
v1 SDK 为服务操作使用 [`enum` 类型](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Action.html)，表示策略语句中的 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html)` 元素。以下 `enum` 类型是一些示例。
+ `[IdentityManagementActions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/IdentityManagementActions.html)`
+ `[DynamoDBv2Actions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/DynamoDBv2Actions.html)`
+ `[SQSActions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/SQSActions.html)`
以下示例显示 `SQSActions` 的 `SendMessage` 常量。
```
Action action = SQSActions.SendMessage;
```
在 v1 中，您无法为语句指定 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html)` 元素。
#### v2
在 v2 中，[IamAction](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamAction.html)接口代表所有操作。要指定[特定于服务的操作](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html)元素，请向 `create` 方法传递一个字符串，如以下代码所示。
```
IamAction action = IamAction.create("sqs:SendMessage");
```
如以下代码所示，使用 v2 时，您可为语句指定 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html)`。
```
IamAction action = IamAction.create("sqs:SendMessage");
IamStatement.builder().addNotAction(action);
```
### Conditions
#### v1
为了表示语句条件，v1 SDK 使用 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Condition.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Condition.html) 的子类。
+ [ArnCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/ArnCondition.html)
+ [BooleanCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/BooleanCondition.html)
+ [DateCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/DateCondition.html)
+ [IpAddressCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/IpAddressCondition.html)
+ [NumericCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/NumericCondition.html)
+ [ StringCondition ](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/StringCondition.html)
每个 `Condition` 子类都定义一个比较 `enum` 类型来帮助定义条件。例如，下面显示了条件的*不相似*[字符串比较](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String)。
```
Condition condition = new StringCondition(StringComparisonType.StringNotLike, "key", "value");
```
#### v2
在 v2 中，您可以使用 `[IamCondition](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamCondition.html)` 并提供 `[IamConditionOperator](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamConditionOperator.html)`（包含所有类型的 `enums` 条件）来为策略语句构建条件。
```
IamCondition condition = IamCondition.create(IamConditionOperator.STRING_NOT_LIKE, "key", "value");
```
### 资源
#### v1
策略语句的 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html)` 元素用 SDK 的 `[Resource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Resource.html)` 类表示。在构造函数中以字符串形式提供 ARN。以下子类提供了便捷的构造函数。
+ [S3BucketResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/S3BucketResource.html)
+ [S3ObjectResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/S3ObjectResource.html)
+ [SQSQueue资源](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/SQSQueueResource.html)
在 v1 中，您可以通过调用 `withIsNotType` 方法为 `[Resource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Resource.html)` 指定 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html)` 元素，如以下语句所示。
```
Resource resource = new Resource("arn:aws:s3:::amzn-s3-demo-bucket").withIsNotType(true);
```
#### v2
在 v2 中，您可以通过将 ARN 传递给 `IamResource.create` 方法来创建 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html)` 元素。
```
IamResource resource = IamResource.create("arn:aws:s3:::amzn-s3-demo-bucket");
```
`[IamResource](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamResource.html)` 可以设置为 *[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html)* 元素，如以下代码段所示。
```
IamResource resource = IamResource.create("arn:aws:s3:::amzn-s3-demo-bucket");
IamStatement.builder().addNotResource(resource);
```
`IamResource.ALL` 表示所有资源。
### 主体
#### v1
v1 SDK 提供以下 `[Principal](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Principal.html)` 类来表示包括所有成员的主体的类型：
+ `AllUsers`
+ `AllServices`
+ `AllWebProviders`
+ `All`
您无法向语句添加 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html)` 元素。
#### v2
在 v2 中，`IamPrincipal.ALL` 表示所有主体：
要表示其他类型主体中的所有成员，请在创建 `IamPrincipal` 时使用 `[IamPrincipalType](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamPrincipalType.html)` 类。
+ `IamPrincipal.create(IamPrincipalType.AWS,"*")` 适用于所有用户。
+ `IamPrincipal.create(IamPrincipalType.SERVICE,"*")` 适用于所有服务。
+ `IamPrincipal.create(IamPrincipalType.FEDERATED,"*")` 适用于所有 Web 提供程序。
+ `IamPrincipal.create(IamPrincipalType.CANONICAL_USER,"*")` 适用于所有规范用户。
在创建策略语句时，您可以使用 `addNotPrincipal` 方法来表示 `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html)` 元素，如以下语句所示。
```
IamPrincipal principal = IamPrincipal.create(IamPrincipalType.AWS, "arn:aws:iam::444455556666:root");
IamStatement.builder().addNotPrincipal(principal);
```
# 在使用 DynamoDB 时发生了变化，从版本 1 变为版本 2 适用于 Java 的 AWS SDK
**Topics**
+ [DynamoDB 映射 API 的版本 1 和版本 2 之间的区别 适用于 Java 的 AWS SDK](ddb-mapping.md)
+ [文档 API 的版本 1 和版本 2 之间的差异 适用于 Java 的 AWS SDK](dynamodb-mapping-document-api.md)
+ [加密库迁移](ddb-encryption-lib-migrate.md)
# DynamoDB 映射 API 的版本 1 和版本 2 之间的区别 适用于 Java 的 AWS SDK
在的版本 1 和版本 2 之间，DynamoDB APIs 映射发生了显著变化。 适用于 Java 的 AWS SDK在版本 1 中，您可以使用`DynamoDBMapper`来处理 Java POJOs。在版本 2 中使用 `DynamoDbEnhancedClient`，该方法具有更新的方法名称、增强的架构定义选项和改进的类型安全性。
关键差异包括：
+ 新的方法名称（例如 `getItem`，而不使用 `load`）
+ 显式表架构创建
+ 同步和异步操作的内置支持
+ 空字符串和配置的处理方式发生了变化
本节介绍映射 API 更改、注释差异、配置更新和迁移指导，以协助您从 v1 `DynamoDBMapper` 转变到 v2 `DynamoDbEnhancedClient`。
**Contents**
+ [适用于 Java 的 SDK 版本 1 升级到版本 2 时，映射库发生的高级别更改](dynamodb-mapping-high-level.md)
+ [导入依赖项差异](dynamodb-mapping-high-level.md#dynamodb-mapping-deps)
+ [适用于 Java 的 SDK 版本 1 和版本 2 之间的 DynamoDB APIs 映射发生了变化](dynamodb-mapping-api-changes.md)
+ [创建客户端](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-client)
+ [建立到 DynamoDB 表/索引的映射](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-mapping)
+ [表操作](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-tobleops)
+ [映射类和属性](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas)
+ [bean 注释](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos)
+ [V2 附加注释](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos-v2-addnl)
+ [配置](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration)
+ [每个操作的配置](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration-per-op)
+ [条件](dynamodb-mapping-api-changes.md#dynamodb-mapping-conditionals)
+ [类型转换](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv)
+ [默认转换器](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-defaults)
+ [为属性设置自定义转换器](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-anno)
+ [添加类型转换器工厂或提供程序](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-factory)
+ [适用于 Java 的 SDK 版本 1 和版本 2 之间的字符串处理差异](dynamodb-migration-string-handling.md)
+ [适用于 Java 的 SDK 版本 1 和版本 2 之间的乐观锁差异](dynamodb-migrate-optimstic-locking.md)
+ [适用于 Java 的 SDK 版本 1 和版本 2 之间的 fluent setter 方法差异](dynamodb-migrate-fluent-setters.md)
# 适用于 Java 的 SDK 版本 1 升级到版本 2 时，映射库发生的高级别更改
在 V1 和 V2 中，每个库中映射客户端的名称不同：
+ V1-迪纳摩 DBMapper
+ V2 - DynamoDB 增强型客户端
您与这两个库的交互方式大致相同：实例化 a， mapper/client 然后为其提供一个 Java POJO，用于 APIs 读取这些项目并将其写入 DynamoDB 表。这两个库还为 POJO 的类提供了注释，以指导客户端如何处理 POJO。
迁移到 V2 时的显著差异包括：
+ V2 和 V1 为低级 DynamoDB 操作使用不同的方法名称。例如：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 提供了多种定义表架构和映射 POJOs 到表格的方法。您可以选择使用注释或使用生成器从代码中生成的架构。V2 还提供架构的可变和不可变版本。
+ 在 V2 中，您需要在最初几个步骤中明确地创建表架构；而在 V1 中，根据需要从注释类中推断出表架构。
+ V2 在增强型客户端 API 中包括[文档 API 客户端](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)，而 V1 则使用[单独的 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html)。
+ 在 V2 中，所有版本 APIs 均提供同步和异步版本。
有关 V2 增强型客户端的更多详细信息，请参阅本指南中的 [DynamoDB 映射部分](dynamodb-enhanced-client.md)。
## 导入依赖项差异
| V1 | V2 |
| --- | --- |
|
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-dynamodb
|
software.amazon.awssdk
bom
2.X.X*
pom
import
software.amazon.awssdk
dynamodb-enhanced
|
\$1 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
在 V1 中，单个依赖项包括低级 DynamoDB API 和 API，而在 V2 中，您可以使用构件依赖项来访问 mapping/document API。`dynamodb-enhanced` mapping/document `dynamodb-enhanced` 模块包含低级 `dynamodb` 模块的传递依赖项。
# 适用于 Java 的 SDK 版本 1 和版本 2 之间的 DynamoDB APIs 映射发生了变化
## 创建客户端
****
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 正常实例化 | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard()
.withCredentials(credentialsProvider)
.withRegion(Regions.US_EAST_1)
.build();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbClient standardClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create())
.region(Region.US_EAST_1)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.build();
|
| 最小实例化 | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
|
| 带属性转换器\$1 | DynamoDBMapper mapper = new DynamoDBMapper(standardClient,
attributeTransformerInstance);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.extensions(extensionAInstance, extensionBInstance)
.build();
|
\$1V2 中的扩展与 V1 中的属性转换器大致对应。[使用扩展自定义 DynamoDB 增强型客户端操作](ddb-en-client-extensions.md) 部分包含有关 V2 中扩展的更多信息。
## 建立到 DynamoDB 表/索引的映射
在 V1 中，通过 bean 注释指定 DynamoDB 表名。在 V2 中，使用一种工厂方法 `table()` 来生成代表远程 DynamoDB 表的 `DynamoDbTable` 实例。`table()` 方法的第一个参数是 DynamoDB 表名。
****
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 将 Java POJO 类映射到 DynamoDB 表 | @DynamoDBTable(tableName ="Customer")
public class Customer {
...
}
| DynamoDbTable customerTable = enhancedClient.table("Customer",
TableSchema.fromBean(Customer.class));
|
| 映射到 DynamoDB 二级索引 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) 《DynamoDB 开发人员指南》中讨论 [V1 `query` 方法](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html#DynamoDBMapper.Methods.query)的部分展示了一个完整的示例。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) 本指南中的 [使用二级索引](ddb-en-client-use-secindex.md) 部分提供了更多信息。 |
## 表操作
本节介绍大多数标准用例中 V1 和 V2 之间存在差异的操作 APIs 。
在 V2 中，所有涉及单个表的操作都是在 `DynamoDbTable` 实例上调用，而不是在增强型客户端上调用。增强型客户端包含可以针对多个表的方法。
在下面名为*表操作*的表中，POJO 实例被称为 `item` 或称为某个具体类型（例如 `customer1`）。对于 V2 示例，名为 `table` 的实例是先前调用 `enhancedClient.table()` 的结果，该调用返回对 `DynamoDbTable` 实例的引用。
请注意，即使未显示，也可以使用 fluent 使用者模式调用大多数 V2 操作。例如，
```
Customer customer = table.getItem(r → r.key(key));
or
Customer customer = table.getItem(r → r.key(k -> k.partitionValue("id").sortValue("email")))
```
对于 V1 操作，*表操作*（在下方）包含一些常用的表单，并未涵盖所有重载表单。例如，`load()` 方法有以下重载：
```
mapper.load(Customer.class, hashKey)
mapper.load(Customer.class, hashKey, rangeKey)
mapper.load(Customer.class, hashKey, config)
mapper.load(Customer.class, hashKey, rangeKey, config)
mapper.load(item)
mapper.load(item, config)
```
*表操作*（在下方）显示了常用的表单：
```
mapper.load(item)
mapper.load(item, config)
```
**表操作**
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 将 Java POJO 写入 DynamoDB 表 **DynamoDB 操作**：`PutItem`，`UpdateItem` | mapper.save(item)
mapper.save(item, config)
mapper.save(item, saveExpression, config)
在 V1 中，`DynamoDBMapperConfig.SaveBehavior` 和注释决定了将调用哪个低级 DynamoDB 方法。通常，除非在使用 `SaveBehavior.CLOBBER` 和 `SaveBehavior.PUT`，否则会调用 `UpdateItem`。自动生成的密钥是一种特殊的使用案例，偶尔会同时使用 `PutItem` 和 `UpdateItem`。 | table.putItem(putItemRequest)
table.putItem(item)
table.putItemWithResponse(item) //Returns metadata.
updateItem(updateItemRequest)
table.updateItem(item)
table.updateItemWithResponse(item) //Returns metadata.
|
| 从 DynamoDB 表中将项目读取到 Java POJO **DynamoDB 操作：**`GetItem` | mapper.load(item)
mapper.load(item, config)
| table.getItem(getItemRequest)
table.getItem(item)
table.getItem(key)
table.getItemWithResponse(key) //Returns POJO with metadata.
|
| 从 DynamoDB 表中删除项目 **DynamoDB 操作：**`DeleteItem` | mapper.delete(item, deleteExpression, config)
| table.deleteItem(deleteItemRequest)
table.deleteItem(item)
table.deleteItem(key)
|
| 查询 DynamoDB 表或二级索引并返回分页列表 **DynamoDB 操作：**`Query` | mapper.query(Customer.class, queryExpression)
mapper.query(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
使用返回的 `PageIterable.stream()`（延迟加载）进行同步响应，使用 `PagePublisher.subscribe()` 进行异步响应 |
| 查询 DynamoDB 表或二级索引并返回列表 **DynamoDB 操作：**`Query` | mapper.queryPage(Customer.class, queryExpression)
mapper.queryPage(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
使用返回的 `PageIterable.items()`（延迟加载）进行同步响应，使用 `PagePublisher.items.subscribe()` 进行异步响应 |
| 扫描 DynamoDB 表或二级索引并返回分页列表 **DynamoDB 操作：**`Scan` | mapper.scan(Customer.class, scanExpression)
mapper.scan(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
使用返回的 `PageIterable.stream()`（延迟加载）进行同步响应，使用 `PagePublisher.subscribe()` 进行异步响应 |
| 扫描 DynamoDB 表或二级索引并返回列表 **DynamoDB 操作：**`Scan` | mapper.scanPage(Customer.class, scanExpression)
mapper.scanPage(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
使用返回的 `PageIterable.items()`（延迟加载）进行同步响应，使用 `PagePublisher.items.subscribe()` 进行异步响应 |
| 批量读取多个表中的多个项目 **DynamoDB 操作：**`BatchGetItem` | mapper.batchLoad(Arrays.asList(customer1,
customer2,
book1))
mapper.batchLoad(itemsToGet)
// itemsToGet: Map, List>
| enhancedClient.batchGetItem(batchGetItemRequest)
enhancedClient.batchGetItem(r -> r.readBatches(
ReadBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build(),
ReadBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build()))
// Iterate over pages with lazy loading or over all items
from the same table.
|
| 批量将多个项目写入多个表 **DynamoDB 操作：**`BatchWriteItem` | mapper.batchSave(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(batchWriteItemRequest)
enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addPutItem(item2)
.build()))
|
| 批量删除多个表中的多个项目 **DynamoDB 操作：**`BatchWriteItem` | mapper.batchDelete(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addDeleteItem(item1key)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| 批量写入/删除多个项目 **DynamoDB 操作：**`BatchWriteItem` | mapper.batchWrite(Arrays.asList(customer1, book1),
Arrays.asList(customer2))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| 执行事务性写入 **DynamoDB 操作：**`TransactWriteItems` | mapper.transactionWrite(transactionWriteRequest)
| enhancedClient.transactWriteItems(transasctWriteItemsRequest)
|
| 执行事务性读取 **DynamoDB 操作：**`TransactGetItems` | mapper.transactionLoad(transactionLoadRequest)
| enhancedClient.transactGetItems(transactGetItemsRequest)
|
| 获取查询中匹配项的计数 **DynamoDB 操作：**使用 `Select.COUNT` 执行 `Query` | mapper.count(Customer.class, queryExpression)
| // Get the count from query results.
PageIterable pageIterable =
customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| 获取扫描中匹配项的计数 **DynamoDB 操作：**使用 `Select.COUNT` 执行 `Scan` | mapper.count(Customer.class, scanExpression)
| // Get the count from scan results.
PageIterable pageIterable =
customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| 在 DynamoDB 中创建与 POJO 类对应的表 **DynamoDB 操作：**`CreateTable` | mapper.generateCreateTableRequest(Customer.class)
前面的语句生成一个低级别的创建表请求；用户必须在 DynamoDB 客户端中调用 `createTable`。 | table.createTable(createTableRequest)
table.createTable(r -> r.provisionedThroughput(defaultThroughput())
.globalSecondaryIndices(
EnhancedGlobalSecondaryIndex.builder()
.indexName("gsi_1")
.projection(p -> p.projectionType(ProjectionType.ALL))
.provisionedThroughput(defaultThroughput())
.build()));
|
| 在 DynamoDB 中执行并行扫描 **DynamoDB 操作：**使用 `Segment` 和 `TotalSegments` 参数执行 `Scan` | mapper.parallelScan(Customer.class,
scanExpression,
numTotalSegments)
| 用户需要处理工作线程并为每个分段调用 `scan`： table.scan(r -> r.segment(0).totalSegments(5))
|
| 将 Amazon S3 与 DynamoDB 集成以存储智能 S3 链接 | mapper.createS3Link(bucket, key)
mapper.getS3ClientCache()
| 不支持，因为它将 Amazon S3 与 DynamoDB 结合在一起。 |
## 映射类和属性
在 V1 和 V2 中，都使用 bean 样式的注释将类映射到表。V2 还提供了[其他方法来为特定使用案例定义架构](ddb-en-client-adv-features.md#ddb-en-client-adv-features-schm-overview)，例如使用不可变类。
### bean 注释
下表显示了 V1 和 V2 中使用的特定使用案例的等效 bean 注释。`Customer` 类场景用于说明参数。
V2 中的注释以及类和枚举遵循驼峰大小写惯例，使用 “” 而不是 “DynamoDB”。DynamoDb
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 将类映射到表 | @DynamoDBTable (tableName ="CustomerTable")
| @DynamoDbBean
@DynamoDbBean(converterProviders = {...})
表名在调用 DynamoDbEnhancedClient\$1table() 方法时定义。 |
| 将类成员指定为表属性 | @DynamoDBAttribute(attributeName = "customerName")
| @DynamoDbAttribute("customerName") |
| 指定班级成员是 hash/partition 关键 | @DynamoDBHashKey
| @DynamoDbPartitionKey
|
| 指定班级成员是 range/sort 关键 | @DynamoDBRangeKey
| @DynamoDbSortKey
|
| 将类成员指定为二级索引哈希键/分区键 | @DynamoDBIndexHashKey
| @DynamoDbSecondaryPartitionKey
|
| 将类成员指定为二级索引范围键/排序键 | @DynamoDBIndexRangeKey
| @DynamoDbSecondarySortKey
|
| 映射到表时忽略此类成员 | @DynamoDBIgnore
| @DynamoDbIgnore
|
| 将类成员指定为自动生成的 UUID 键属性 | @DynamoDBAutoGeneratedKey
| @DynamoDbAutoGeneratedUuid
默认情况下，不加载提供此功能的扩展；您必须将扩展添加到客户端生成器中。 |
| 将类成员指定为自动生成的时间戳属性 | @DynamoDBAutoGeneratedTimestamp
| @DynamoDbAutoGeneratedTimestampAttribute
默认情况下，不加载提供此功能的扩展；您必须将扩展添加到客户端生成器中。 |
| 将类成员指定为自动递增的版本属性 | @DynamoDBVersionAttribute
| @DynamoDbVersionAttribute
提供此功能的扩展会自动加载。 |
| 将类成员指定为需要自定义转换 | @DynamoDBTypeConverted
| @DynamoDbConvertedBy
|
| 将类成员指定为存储为另一个属性类型 | @DynamoDBTyped()
| 使用 `AttributeConverter` 实现。V2 为常用 Java 类型提供许多内置转换器。您也可以实施自己的自定义 `AttributeConverter` 或 `AttributeConverterProvider`。请参阅本指南中的[控制属性转换](ddb-en-client-adv-features-conversion.md)。 |
| 指定一个可以序列化为 DynamoDB 文档（JSON 风格的文档）或子文档的类 | @DynamoDBDocument
| 使用增强型文档 API。请参阅以下资源：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
### V2 附加注释
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 如果 Java 值为 null，则将类成员指定为不存储为 Null 属性 | 不适用 | @DynamoDbIgnoreNulls
|
| 如果所有属性都为 null，则将类成员指定为空对象 | 不适用 | @DynamoDbPreserveEmptyObject
|
| 为类成员指定特殊更新操作 | 不适用 | @DynamoDbUpdateBehavior
|
| 指定一个不可变类 | 不适用 | @DynamoDbImmutable
|
| 将类成员指定为自动递增的计数器属性 | 不适用 | @DynamoDbAtomicCounter
提供此功能的扩展会自动加载。 |
## 配置
在 V1 中，通常使用 `DynamoDBMapperConfig` 的实例来控制特定行为。您可以在创建映射器时或在发出请求时提供配置对象。在 V2 中，配置特定于操作的请求对象。
| 使用案例 | V1 | V1 中的默认设置 | V2 |
| --- | --- | --- | --- |
| | DynamoDBMapperConfig.builder()
| | |
| Batch load/write 重试策略 | .withBatchLoadRetryStrategy(loadRetryStrategy)
.withBatchWriteRetryStrategy(writeRetryStrategy)
| 重试失败的项目 | 在底层 DynamoDBClient 中配置重试策略。请参阅本指南中的[在中配置重试行为 AWS SDK for Java 2.x](retry-strategy.md)。 |
| 一致性读取 | .withConsistentReads(CONSISTENT)
| EVENTUAL | 默认情况下，读取操作的一致性读取为 false。在请求对象上使用 .consistentRead(true) 覆盖。 |
| 包含编组器/解组器集合的转换架构 | .withConversionSchema(conversionSchema)
静态实现与旧版本向后兼容。 | V2\$1COMPATIBLE | 不适用。这是一项遗留特性，指的是 DynamoDB 的最早版本（V1）存储数据类型的方式，而在增强型客户端中不再保留此行为。DynamoDB V1 中的一个行为示例是将布尔值存储为数字而不是布尔值。 |
| 表名称 | .withObjectTableNameResolver()
.withTableNameOverride()
.withTableNameResolver()
静态实现与旧版本向后兼容 | 使用注释或根据类来推断 | 表名在调用 `DynamoDbEnhancedClient#table()` 方法时定义。 |
| 分页加载策略 | .withPaginationLoadingStrategy(strategy)
选项包括：LAZY\$1`LOADING`、`EAGER_LOADING` 或 `ITERATION_ONLY` | LAZY\$1LOADING | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| 请求指标收集 | .withRequestMetricCollector(collector)
| null | 在构建标准 DynamoDB 客户端时在 ClientOverrideConfiguration 中使用 metricPublisher()。 |
| 保存行为 | .withSaveBehavior(SaveBehavior.CLOBBER)
选项包括 `UPDATE`、`CLOBBER`、`PUT`、`APPEND_SET` 或 `UPDATE_SKIP_NULL_ATTRIBUTES`。 | UPDATE | 在 V2 中，您可以显式调用 `putItem()` 或 `updateItem()`。 `CLOBBER or PUT`：V2 中的相应动作是调用 `putItem()`。没有特定的 `CLOBBER` 配置。 `UPDATE`: 对应于 `updateItem()` `UPDATE_SKIP_NULL_ATTRIBUTES`: 对应于`updateItem()`。使用请求设置 `ignoreNulls` 和注释/标签 `DynamoDbUpdateBehavior` 控制更新行为。 `APPEND_SET`：不支持 |
| 类型转换器工厂 | .withTypeConverterFactory(typeConverterFactory)
| 标准类型转换器 | 使用以下方式在 bean 上设置 @DynamoDbBean(converterProviders = {ConverterProvider.class,
DefaultAttributeConverterProvider.class}) |
### 每个操作的配置
在 V1 中，某些操作（例如 `query()`）可以通过提交给操作的“表达式”对象来进行高度灵活的配置。例如：
```
DynamoDBQueryExpression emailBwQueryExpr = new DynamoDBQueryExpression()
.withRangeKeyCondition("Email",
new Condition()
.withComparisonOperator(ComparisonOperator.BEGINS_WITH)
.withAttributeValueList(
new AttributeValue().withS("my")));
mapper.query(Customer.class, emailBwQueryExpr);
```
在 V2 中，不使用配置对象，而是使用生成器对请求对象设置参数。例如：
```
QueryEnhancedRequest emailBw = QueryEnhancedRequest.builder()
.queryConditional(QueryConditional
.sortBeginsWith(kb -> kb
.sortValue("my"))).build();
customerTable.query(emailBw);
```
## 条件
在 V2 中，条件表达式和筛选表达式使用 `Expression` 对象来表达，该对象封装了条件以及名称和筛选条件的映射。
| 使用案例 | 操作 | V1 | V2 |
| --- | --- | --- | --- |
| 预期的属性条件 | save()、delete()、query()、scan() | new DynamoDBSaveExpression()
.withExpected(Collections.singletonMap(
"otherAttribute", new ExpectedAttributeValue(false)))
.withConditionalOperator(ConditionalOperator.AND);
| 已弃用；改用 ConditionExpression。 |
| 条件表达式 | delete() | deleteExpression.setConditionExpression("zipcode = :zipcode")
deleteExpression.setExpressionAttributeValues(...)
| Expression conditionExpression =
Expression.builder()
.expression("#key = :value OR #key1 = :value1")
.putExpressionName("#key", "attribute")
.putExpressionName("#key1", "attribute3")
.putExpressionValue(":value", AttributeValues.stringValue("wrong"))
.putExpressionValue(":value1", AttributeValues.stringValue("three"))
.build();
DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder()
.conditionExpression(conditionExpression).build();
|
| 筛选表达式 | query()、scan() | scanExpression
.withFilterExpression("#statename = :state")
.withExpressionAttributeValues(attributeValueMapBuilder.build())
.withExpressionAttributeNames(attributeNameMapBuilder.build())
| Map values = singletonMap(":key", stringValue("value"));
Expression filterExpression =
Expression.builder()
.expression("name = :key")
.expressionValues(values)
.build();
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
.filterExpression(filterExpression).build();
|
| 查询的条件表达式 | query() | queryExpression.withKeyConditionExpression()
| QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b
.partitionValue("movie01"));
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(keyEqual)
.build();
|
## 类型转换
### 默认转换器
在 V2 中，SDK 为所有常见类型提供了一组默认转换器。既可以在整体提供程序级别更改类型转换器，也可以为单个属性更改类型转换器。您可以在 [AttributeConverter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/AttributeConverter.html)API 参考中找到可用转换器的列表。
### 为属性设置自定义转换器
在 V1 中，您可以使用 `@DynamoDBTypeConverted` 对 getter 方法添加注释，以指定在 Java 属性类型和 DynamoDB 属性类型之间进行转换的类。例如，`CurrencyFormatConverter` 可以在 Java `Currency` 类型和 DynamoDB 字符串之间应用转换，如以下代码段所示。
```
@DynamoDBTypeConverted(converter = CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
上一个代码段的 V2 等效代码如下所示。
```
@DynamoDbConvertedBy(CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
**注意**
在 V1 中，您可以将注释应用于属性本身、类型或用户定义的注释，V2 仅支持将注释应用于 getter。
### 添加类型转换器工厂或提供程序
在 V1 中，您可以提供自己的类型转换器集，也可以通过在配置中添加类型转换器工厂来覆盖您在意的类型。类型转换器工厂扩展 `DynamoDBTypeConverterFactory`，通过获取对默认集的引用并对其进行扩展来完成覆盖。以下代码段演示了如何执行此操作。
```
DynamoDBTypeConverterFactory typeConverterFactory =
DynamoDBTypeConverterFactory.standard().override()
.with(String.class, CustomBoolean.class, new DynamoDBTypeConverter() {
@Override
public String convert(CustomBoolean bool) {
return String.valueOf(bool.getValue());
}
@Override
public CustomBoolean unconvert(String string) {
return new CustomBoolean(Boolean.valueOf(string));
}}).build();
DynamoDBMapperConfig config =
DynamoDBMapperConfig.builder()
.withTypeConverterFactory(typeConverterFactory)
.build();
DynamoDBMapper mapperWithTypeConverterFactory = new DynamoDBMapper(dynamo, config);
```
V2 通过 `@DynamoDbBean` 注释提供了类似的功能。您可以提供单个 `AttributeConverterProvider` 或一个有序的 `AttributeConverterProvider` 链。请注意，如果您提供自己的属性转换器提供程序链，则将覆盖默认的转换器提供程序，且必须在链中包括它才能使用其属性转换器。
```
@DynamoDbBean(converterProviders = {
ConverterProvider1.class,
ConverterProvider2.class,
DefaultAttributeConverterProvider.class})
public class Customer {
...
}
```
本指南中关于[属性转换](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-example)的部分包含了 V2 的完整示例。
# 适用于 Java 的 SDK 版本 1 和版本 2 之间的字符串处理差异
向 DynamoDB 发送数据时，V1 和 V2 对空字符串的处理方式有所不同：
+ **V1**：在发送到 DynamoDB 之前将空字符串转换为 null 值（导致没有属性）
+ **V2**：将空字符串作为实际的空字符串值发送给 DynamoDB
**重要**
迁移到 V2 后，如果您不想在 DynamoDB 中存储空字符串，则必须实施自定义转换器。如果没有自定义转换器，V2 会将空字符串作为实际的空字符串属性存储在 DynamoDB 项目中，这与 V1 完全省略这些属性的行为不同。
**Example V2 的自定义转换器，用于将空字符串属性转换为 null**
```
/**
* Custom converter that maintains V1 behavior by converting empty strings to null values
* when writing to DynamoDB, ensuring compatibility with existing data. No attribute will be saved to DynamoDB.
*/
public class NullifyEmptyStringConverter implements AttributeConverter {
@Override
public AttributeValue transformFrom(String value) {
if (value == null || value.isEmpty()) {
return AttributeValue.builder().nul(true).build();
}
return AttributeValue.builder().s(value).build();
}
@Override
public String transformTo(AttributeValue attributeValue) {
if (attributeValue.nul()) {
return null;
}
return attributeValue.s();
}
@Override
public EnhancedType type() {
return EnhancedType.of(String.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.S;
}
}
// V2 usage:
@DynamoDbBean
public class Customer {
private String name;
@DynamoDbConvertedBy(NullifyEmptyStringConverter.class)
public String getName() {
return name;
}
}
```
# 适用于 Java 的 SDK 版本 1 和版本 2 之间的乐观锁差异
V1 和 V2 都使用属性注释来实施乐观锁，注释在 bean 类上标记一个属性以存储版本号。
**乐观锁行为的差异**
| | V1 | V2 |
| --- | --- | --- |
| bean 类注释 | @DynamoDBVersionAttribute | @DynamoDbVersionAttribute（请注意，V2 使用小写的“b”） |
| 初始保存 | 版本号属性设置为 1。 | 使用 `@DynamoDbVersionAttribute(startAt = X)` 设置的版本属性的起始值。默认值为 0。 |
| 更新 | 如果条件检查确认正在更新的对象的版本号与数据库中的版本号相匹配，则版本号属性将增加 1。 | 如果条件检查确认正在更新的对象的版本号与数据库中的版本号相匹配，则版本号属性会递增。 按照使用 `@DynamoDbVersionAttribute(incrementBy = X)` 设置的 `incrementBy` 选项来增加版本号属性。默认值为 1。 |
| 删除 | DynamoDBMapper 添加条件检查，以确认要删除的对象的版本号与数据库中的版本号相匹配。 | V2 不会自动为删除操作添加条件。如果要控制删除行为，则必须手动添加条件表达式。 在以下示例中，`recordVersion` 是 bean 的版本属性。 // 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
|
| 带条件检查的事务写入 | 您不能使用在 addConditionCheck 方法中用 @DynamoDBVersionAttribute 进行注释的 bean 类。 | 您可以在 addConditionCheck 生成器方法中通过 @DynamoDbVersionAttribute 注释为 transactWriteItems 请求使用 bean 类。 |
| 禁用 | 通过将 DynamoDBMapperConfig.SaveBehavior 枚举值从 UPDATE 更改为 CLOBBER 来禁用乐观锁。 | 不使用 `@DynamoDbVersionAttribute` 注释。 |
# 适用于 Java 的 SDK 版本 1 和版本 2 之间的 fluent setter 方法差异
你可以在 V1 的 DynamoDB 映射 API 中使用 POJOs 流畅的设置器，也可以在 2.30.29 版本之后的 V2 中使用。
例如，以下 POJO 通过 `setName` 方法返回一个 `Customer` 实例：
```
// V1
@DynamoDBTable(tableName ="Customer")
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this;
}
}
```
但是，如果您使用的是 2.30.29 之前的 V2 版本，则 `setName` 会返回 `Customer` 实例，其 `name` 值为 `null`。
```
// V2 prior to version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Bug: returns this instance with a `name` value of `null`.
}
}
```
```
// Available in V2 since version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Returns this instance for method chaining with the `name` value set.
}
}
```
# 文档 API 的版本 1 和版本 2 之间的差异 适用于 Java 的 AWS SDK
文档 API 支持将 JSON 风格的文档作为 DynamoDB 表中的单个项目来处理。V1 文档 API 在 V2 中有对应的 API，但是 V2 没有像 V1 那样为文档 API 使用单独的客户端，而是在 DynamoDB 增强型客户端中整合了文档 API 功能。
在 V1 中，[https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Item.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Item.html) 类代表来自 DynamoDB 表的非结构化记录。在 V2 中，非结构化记录由 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) 类的实例表示。请注意，在 V2 中，主键在表架构中定义，在 V1 中，主键在项目本身定义。
下表比较了 V1 和 V2 APIs 中文档之间的差异。
| 使用案例 | V1 | V2 |
| --- |--- |--- |
| 创建文档客户端 | AmazonDynamoDB client = ... //Create a client.
DynamoDB documentClient = new DynamoDB(client);
| // The V2 Document API uses the same DynamoDbEnhancedClient
// that is used for mapping POJOs.
DynamoDbClient standardClient = ... //Create a standard client.
DynamoDbEnhancedClient enhancedClient = ... // Create an enhanced client.
|
| 引用表格 | Table documentTable = docClient.documentClient("Person"); | DynamoDbTable documentTable = enhancedClient.table("Person",
TableSchema.documentSchemaBuilder()
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S)
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
|
| **Work with semi-structured data** |
| --- |
| 放置项目 | Item item = new Item()
.withPrimaryKey("id", 50)
.withString("firstName", "Shirley");
PutItemOutcome outcome = documentTable.putItem(item);
| EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.build();
documentTable.putItem(personDocument);
|
| 获取项目 | GetItemOutcome outcome = documentTable.getItemOutcome( "id", 50);
Item personDocFromDb = outcome.getItem();
String firstName = personDocFromDb.getString("firstName");
| EnhancedDocument personDocFromDb = documentTable
.getItem(Key.builder()
.partitionValue(50)
.build());
String firstName = personDocFromDb.getString("firstName");
|
| **Work with JSON items** |
| --- |
| 转换 JSON 结构以将其与文档 API 配合使用 | // The 'jsonPerson' identifier is a JSON string.
Item item = new Item().fromJSON(jsonPerson);
| // The 'jsonPerson' identifier is a JSON string.
EnhancedDocument document = EnhancedDocument.builder()
.json(jsonPerson).build());
|
| 把 JSON | documentTable.putItem(item)
| documentTable.putItem(document);
|
| 阅读 JSON | GetItemOutcome outcome = //Get item.
String jsonPerson = outcome.getItem().toJSON();
| String jsonPerson = documentTable.getItem(Key.builder()
.partitionValue(50).build())
.fromJson();
|
## API 参考和文档指南 APIs
| | V1 | V2 |
| --- | --- | --- |
| API 参考 | [API 参考](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/package-summary.html) | [API 参考](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) |
| 文档指南 | [Amazon DynamoDB 开发人员指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/JavaDocumentAPIItemCRUD.html) | [增强型文档 API](ddb-en-client-doc-api.md)（本指南） |
# V1 Xpec API 到 V2 表达式 API
V1 中提供的表达式规范（Xspec）API 协助创建用于处理面向文档的数据的表达式，该 API 在 V2 中不可用。V2 使用 Expression API，它可以处理面向文档的数据和映射的数据。 object-to-item
****
| | V1 | V2 |
| --- | --- | --- |
| API 名称 | 表达式规范（Xspec）API | 表达式 API |
| 结合使用 | 文档 API [表](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html)类的方法，例如 [updateItem](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html#updateItem-java.lang.String-java.lang.Object-com.amazonaws.services.dynamodbv2.xspec.UpdateItemExpressionSpec-) 和 [scan](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html#scan-com.amazonaws.services.dynamodbv2.xspec.ScanExpressionSpec-) | 两个 APIs DynamoDB 增强版客户端： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) 对于这两种类型 APIs，在您获取[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)实例之后： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) 创建请求对象时，在 `DynamoDbTable` 方法中使用表达式。例如，在 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryEnhancedRequest.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryEnhancedRequest.Builder.html) 的 `filterExpression` 方法中 |
| 资源 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) | 本 Java 开发人员指南中的[表达式信息](ddb-en-client-expressions.md) |
# 加密库迁移
有关迁移 DynamoDB 加密库以与 Java SDK 的 V2 配合使用的信息，请参阅《[Amazon DynamoDB Encryption Client 开发人员指南](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/ddb-java-migrate.html)》。
# Amazon SQS 请求批处理从版本 1 到版本 2 的更改
本主题详细介绍了 适用于 Java 的 AWS SDK版本 1 和版本 2 之间的 Amazon SQS 自动请求批处理的更改。
## 高级别更改
适用于 Java 的 AWS SDK 1.x 使用单独的类执行客户端缓冲，该`[AmazonSQSBufferedAsyncClient](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/sqs/buffered/AmazonSQSBufferedAsyncClient.html)`类需要显式初始化才能进行请求批处理。
使用 AWS SDK for Java 2.x 简化并增强了缓冲功能。`[SqsAsyncBatchManager](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html)`该接口的实现提供了直接与标准 `[SqsAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/SqsAsyncClient.html)` 集成的自动请求批处理功能。要了解 v2 的 `SqsAsyncBatchManager`，请参阅本指南中的 [将 Amazon SQS 的自动请求批处理与 AWS SDK for Java 2.x](sqs-auto-batch.md) 主题。
| 更改 | v1 | v2 |
| --- | --- | --- |
| Maven 依赖项 |
com.amazonaws
aws-java-sdk-bom
1.12.7821
pom
import
com.amazonaws
aws-java-sdk-sqs
|
software.amazon.awssdk
bom
2.31.152
pom
import
software.amazon.awssdk
sqs
|
| 软件包名称 | com.amazonaws.services.sqs.buffered | software.amazon.awssdk.services.sqs.batchmanager |
| 类名 | `[AmazonSQSBufferedAsyncClient](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/sqs/buffered/AmazonSQSBufferedAsyncClient.html)` | [SqsAsyncBatchManager](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html) |
1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
## 使用 SQS 自动请求批处理
| 更改 | v1 | v2 |
| --- | --- | --- |
| 创建批量管理器 | AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient();
AmazonSQSAsync bufferedSqs = new
AmazonSQSBufferedAsyncClient(sqsAsync);
| SqsAsyncClient asyncClient = SqsAsyncClient.create();
SqsAsyncBatchManager sqsAsyncBatchManager =
asyncClient.batchManager();
|
| 使用自定义配置创建批量管理器 | AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient();
QueueBufferConfig queueBufferConfig = new QueueBufferConfig()
.withMaxBatchOpenMs(200)
.withMaxBatchSize(10)
.withMinReceiveWaitTimeMs(1000)
.withVisibilityTimeoutSeconds(20)
.withReceiveMessageAttributeNames(messageAttributeValues);
AmazonSQSAsync bufferedSqs =
new AmazonSQSBufferedAsyncClient(sqsAsync, queueBufferConfig);
| BatchOverrideConfiguration batchOverrideConfiguration =
BatchOverrideConfiguration.builder()
.sendRequestFrequency(Duration.ofMillis(200))
.maxBatchSize(10)
.receiveMessageMinWaitDuration(Duration.ofMillis(1000))
.receiveMessageVisibilityTimeout(Duration.ofSeconds(20))
.receiveMessageSystemAttributeNames(messageSystemAttributeNames)
.receiveMessageAttributeNames(messageAttributeValues)
.build();
SqsAsyncBatchManager sqsAsyncBatchManager = SqsAsyncBatchManager.builder()
.overrideConfiguration(batchOverrideConfiguration)
.client(SqsAsyncClient.create())
.scheduledExecutor(Executors.newScheduledThreadPool(8))
.build();
|
| 发送消息 | Future sendResultFuture =
bufferedSqs.sendMessageAsync(new SendMessageRequest()
.withQueueUrl(queueUrl)
.withMessageBody(body));
| CompletableFuture sendCompletableFuture =
sqsAsyncBatchManager.sendMessage(
SendMessageRequest.builder()
.queueUrl(queueUrl)
.messageBody(body)
.build());
|
| 删除消息 | Future deletResultFuture =
bufferedSqs.deleteMessageAsync(new DeleteMessageRequest()
.withQueueUrl(queueUrl));
| CompletableFuture deleteResultCompletableFuture
= sqsAsyncBatchManager.deleteMessage(
DeleteMessageRequest.builder()
.queueUrl(queueUrl)
.build());
|
| 更改消息的可见性 | Future changeVisibilityResultFuture =
bufferedSqs.changeMessageVisibilityAsync
(new ChangeMessageVisibilityRequest()
.withQueueUrl(queueUrl)
.withVisibilityTimeout(20));
| CompletableFuture changeResponseCompletableFuture
= sqsAsyncBatchManager.changeMessageVisibility(
ChangeMessageVisibilityRequest.builder()
.queueUrl(queueUrl)
.visibilityTimeout(20)
.build());
|
| 接收消息 | ReceiveMessageResult receiveResult =
bufferedSqs.receiveMessage(
new ReceiveMessageRequest()
.withQueueUrl(queueUrl));
| CompletableFuture
responseCompletableFuture = sqsAsyncBatchManager.receiveMessage(
ReceiveMessageRequest.builder()
.queueUrl(queueUrl)
.build());
|
## 异步返回类型差异
| 更改 | v1 | v2 |
| --- | --- | --- |
| 返回类型 | Future | CompletableFuture |
| 回调机制 | 使用单独的 onSuccess 和 onError 方法需要 AsyncHandler | JDK CompletableFuture APIs 提供的用途，例如whenComplete()、、thenCompose() thenApply() |
| 异常处理 | 使用 AsyncHandler\$1onError() 方法 | JDK CompletableFuture APIs 提供的用途，例如exceptionally()handle()、或 whenComplete() |
| 取消 | 通过 Future.cancel() 实现基本支持 | 取消父 CompletableFuture 会自动取消链中的所有相关 Future |
## 异步完成处理差异
| 更改 | v1 | v2 |
| --- | --- | --- |
| 响应处理程序实现 | Future future = bufferedSqs.receiveMessageAsync(
receiveRequest,
new AsyncHandler() {
@Override
public void onSuccess(ReceiveMessageRequest request,
ReceiveMessageResult result) {
List messages = result.getMessages();
System.out.println("Received " + messages.size() + " messages");
for (Message message : messages) {
System.out.println("Message ID: " + message.getMessageId());
System.out.println("Body: " + message.getBody());
}
}
@Override
public void onError(Exception e) {
System.err.println("Error receiving messages: " + e.getMessage());
e.printStackTrace();
}
}
);
| CompletableFuture completableFuture = sqsAsyncBatchManager
.receiveMessage(ReceiveMessageRequest.builder()
.queueUrl(queueUrl).build())
.whenComplete((receiveMessageResponse, throwable) -> {
if (throwable != null) {
System.err.println("Error receiving messages: " + throwable.getMessage());
throwable.printStackTrace();
} else {
List messages = receiveMessageResponse.messages();
System.out.println("Received " + messages.size() + " messages");
for (Message message : messages) {
System.out.println("Message ID: " + message.messageId());
System.out.println("Body: " + message.body());
}
}
});
|
## 关键配置参数
****
| 参数 | v1 | v2 |
| --- | --- | --- |
| 最大批次大小 | maxBatchSize（每批默认为 10 个请求） | maxBatchSize（每批默认为 10 个请求） |
| 批次等待时间 | maxBatchOpenMs（默认值为 200 毫秒） | sendRequestFrequency（默认值为 200 毫秒） |
| 可见性超时 | visibilityTimeoutSeconds（队列默认值为 -1） | receiveMessageVisibilityTimeout（队列默认值） |
| 最小等待时间 | longPollWaitTimeoutSeconds（如果 longPoll 为 true，则为 20 秒） | receiveMessageMinWaitDuration（默认值为 50 毫秒） |
| 消息属性 | 使用 ReceiveMessageRequest 进行设置 | receiveMessageAttributeNames（默认值为无） |
| 系统属性 | 使用 ReceiveMessageRequest 进行设置 | receiveMessageSystemAttributeNames（默认值为无） |
| 长轮询 | longPoll（默认值为 true） | 不支持，以便避免让已建立的连接一直处于等待状态，直到服务器发送消息 |
| 长时间轮询的最长等待时间 | longPollWaitTimeoutSeconds（默认值为 20 秒） | 不支持，以便避免让已建立的连接一直处于等待状态，直到服务器发送消息 |
| 在客户端预取和存储接收批次的最大数量 | maxDoneReceiveBatches（10 个批次） | 不支持，因为这在内部处理 |
| 同时处理的最大活动出站批次数量 | maxInflightOutboundBatches（默认为 5 个批次） | 不支持，因为这在内部处理 |
| 同时处理的最大活动接收批次数量 | maxInflightReceiveBatches（默认为 10 个批次） | 不支持，因为这在内部处理 |