| 直接可繼續物件 | 不支援 |
### 結果物件
| 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 Transfer Manager 設定的組態變更取決於您使用的 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 用戶端的 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.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 用戶端傳遞給傳輸管理員，以停用平行下載。 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 用戶端傳遞至傳輸管理員，以停用平行下載。 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 就無法使用子請求加速下載程序。
# 從第 1 版剖析 Amazon S3 URIs 到第 2 版的變更
本主題詳細說明剖析 Amazon S3 URIs 從第 1 版 (v1) 到第 2 版 (v2.) 的變更。
## 高階變更
若要開始剖析 v1 中的 S3 URI，您可以使用建構函數來執行個體化 `AmazonS3URI` 。在 v2 中，您在 執行個體`parseUri()`上呼叫 `S3Utilities`，以傳回 `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 變更
| Behavior (行為) | 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");
|
| 擷取查詢參數。 | N/A | Map> queryParams =
s3Uri.rawQueryParameters();
|
### 行為變更
#### URL 編碼
v1 提供傳入旗標的選項，以指定 URI 是否應該以 URL 編碼。預設值為 `true`。
在 v2 中，不支援 URL 編碼。如果您使用具有預留或不安全字元的物件金鑰或查詢參數，則必須進行 URL 編碼。例如，您需要`" "`將空格取代為 `%20`。
# S3 事件通知 API 從第 1 版變更為第 2 版
本主題詳細說明 S3 事件通知 API 從 版本 1.x (v1) 到 版本 2 .x (v2) 的變更 適用於 Java 的 AWS SDK。
## 高階變更
### 結構變更
V1 對`EventNotificationRecord`類型及其屬性使用靜態內部類別，而 v2 對`EventNotificationRecord`類型使用單獨的公有類別。
### 命名慣例變更
在 v1 中，屬性類別名稱包含尾碼*實體*，而 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) [S3EventNotification.S3EventNotificationRecord](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3EventNotificationRecord.html) [ S3EventNotification.GlacierEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.GlacierEventDataEntity.html) [S3EventNotification.IntelligentTieringEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.IntelligentTieringEventDataEntity.html) [S3EventNotification.LifecycleEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.LifecycleEventDataEntity.html) [S3EventNotification.ReplicationEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ReplicationEventDataEntity.html) [S3EventNotification.RequestParametersEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RequestParametersEntity.html) [S3EventNotification.ResponseElementsEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ResponseElementsEntity.html) [S3EventNotification.RestoreEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RestoreEventDataEntity.html) [S3EventNotification.S3BucketEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3BucketEntity.html) [ S3EventNotification.S3Entity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3Entity.html) [S3EventNotification.S3ObjectEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3ObjectEntity.html) [S3EventNotification.TransitionEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.TransitionEventDataEntity.html) [S3EventNotification.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) [S3 儲存貯體](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 |
| --- | --- | --- |
| S3EventNotification 從 JSON 字串建立 | 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`庫版本
如果您使用 [aws-lambda-java-events](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events) 在 Lambda 函數中使用 S3 通知事件，我們建議您升級至最新的 3.x.x 版本。最近的版本會從 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]` 如果在組態檔案中同時找到 `[profile foo]`和 `[foo]` ，則使用 中的設定。
+ 使用相同檔案和設定檔中上次複製設定的值。
+ 識別 `;`和 `#`以定義註解。
+ 識別設定檔定義`#`中的 `;`和 以定義註解，即使字元與結尾括號相鄰。
+ 只有在值前面加上空格時，才能辨識`;`並`#`定義註解。
+ 如果值前面沒有空格，則識別值中的 `#` `;`和 以及所有下列內容。
+ 將角色型登入資料視為最高優先順序登入資料。如果使用者指定 `role_arn` 屬性，則 2.x SDK 一律使用角色型登入資料。
+ 將工作階段型登入資料視為second-highest-priority登入資料。如果未使用角色型登入資料，且使用者指定 `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)) |
# 等待程式從第 1 版變更為第 2 版
本主題詳細說明等待程式功能從第 1 版 (v1) 到第 2 版 (v2) 的變更。
下表特別示範 DynamoDB 等待程式的差異。其他服務的等待程式遵循相同的模式。
## 高階變更
等待程式類別與 服務位於相同的 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_tw/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 |
| --- | --- | --- |
| 建立等待程式 | 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 版
本主題詳細說明適用於 Java 的 SDK 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`界面。 EC2 [在 中設定 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`系統屬性和組態檔案`ec2_metadata_service_endpoint`設定會在存在時予以忽略。
```
Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpoint(URI.create("endpoint.to.use"))
.build();
```
#### 端點模式
透過 v2，您可以指定端點模式，將中繼資料用戶端設定為使用 IPv4 或 IPv6 的預設端點值。端點模式不適用於 v1。用於 IPv4 的預設值為 `http://[fd00:ec2::254]` IPv6 的 `http://169.254.169.254`和 。 IPv6
下表顯示您可以依遞減優先順序設定端點模式的不同方式。
****
| | | 可能的值 |
| --- | --- | --- |
| 用戶端建置器組態方法： endpointMode(...) | Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpointMode(EndpointMode.IPV4)
.build();
| EndpointMode.IPV4, EndpointMode.IPV6 |
| 系統屬性 | aws.ec2MetadataServiceEndpointMode | IPv4、 IPv6（大小寫無關緊要） |
| 組態檔案： \$1.aws/config | ec2\$1metadata\$1service\$1endpoint 設定 | IPv4、 IPv6（大小寫無關緊要） |
| 先前未指定 | 使用 IPv4 | |
#### 開發套件如何在 v2 `endpoint-mode`中解析 `endpoint`或
1. SDK 會使用您在用戶端建置器程式碼中設定的值，並忽略任何外部設定。由於軟體開發套件會在用戶端建置器上`endpointMode`同時呼叫 `endpoint`和 時擲回例外狀況，因此軟體開發套件會使用您使用任何方法的端點值。
1. 如果您未在程式碼中設定值，軟體開發套件會先尋找外部組態，然後再尋找組態檔案中的設定。
1. 開發套件會先檢查端點值。如果找到值，則會使用該值。
1. 如果軟體開發套件仍然找不到值，軟體開發套件會尋找端點模式設定。
1. 最後，如果軟體開發套件找不到外部設定，而且您尚未在程式碼中設定中繼資料用戶端，則軟體開發套件會使用 的 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。
## 組態差異
下表列出不同的組態選項。
****
| Configuration | 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();
```
# 從第 1 版到第 2 版的 Amazon CloudFront 預先簽章變更
本主題詳細說明 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 變更
| Behavior (行為) | 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 開發套件會以 形式提供 Cookie 標頭`Map.Entry`。
```
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 |
| 類別名稱 | [政策](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_tw/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_tw/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 具有代表政策陳述式中`[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`類型](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/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)`
下列範例顯示 的`SendMessage`常數`SQSActions`。
```
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");
```
您可以`[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 的陳述式指定 ，如下列程式碼所示。
```
IamAction action = IamAction.create("sqs:SendMessage");
IamStatement.builder().addNotAction(action);
```
### 條件
#### 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");
```
### Resources
#### 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)
+ [SQSQueueResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/SQSQueueResource.html)
在 v1 中，您可以`[Resource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Resource.html)`呼叫 `withIsNotType`方法來指定 的 `[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`代表所有主體：
若要代表其他類型委託人中的所有成員，請在建立 時使用 `[IamPrincipalType](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamPrincipalType.html)`類別`IamPrincipal`。
+ `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**
+ [
# 第 1 版與第 2 版之間的 DynamoDB 映射 API 差異 適用於 Java 的 AWS SDK
](ddb-mapping.md)
+ [
# 記錄 第 1 版和第 2 版之間的 API 差異 適用於 Java 的 AWS SDK
](dynamodb-mapping-document-api.md)
+ [
# 加密程式庫遷移
](ddb-encryption-lib-migrate.md)
# 第 1 版與第 2 版之間的 DynamoDB 映射 API 差異 適用於 Java 的 AWS SDK
DynamoDB 映射 APIs 第 1 版和第 2 版之間發生重大變更 適用於 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)
+ [
## Configuration
](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 版之間的流暢設定器差異
](dynamodb-migrate-fluent-setters.md)
# 從適用於 Java 的 SDK 第 1 版到第 2 版映射程式庫的高階變更
每個程式庫中的映射用戶端名稱在 V1 和 V2 中不同：
+ V1 - DynamoDBMapper
+ V2 - DynamoDB 增強型用戶端
您以大致相同的方式與兩個程式庫互動：您執行個體化映射器/用戶端，然後將 Java POJO 提供給讀取和寫入這些項目至 DynamoDB 資料表APIs。這兩個程式庫也提供 POJO 類別的註釋，以指示用戶端如何處理 POJO。
移至 V2 時的顯著差異包括：
+ V2 和 V1 對低階 DynamoDB 操作使用不同的方法名稱。例如：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 提供多種方法來定義資料表結構描述，並將 POJOs對應至資料表。您可以選擇使用註釋，或使用建置器從程式碼產生的結構描述。V2 還提供結構描述的可變和不可變版本。
+ 使用 V2 時，您會特別將資料表結構描述建立為第一個步驟之一，而在 V1 中，則會視需要從註釋的類別推斷資料表結構描述。
+ V2 在增強型[用戶端 API 中包含文件 ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) API 用戶端，而 V1 使用[單獨的 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html)。
+ 所有 APIs V2 中提供同步和非同步版本。
如需 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 中，您可以使用`dynamodb-enhanced`成品相依性來存取映射/文件 API。`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()`會產生`DynamoDbTable`代表遠端 DynamoDB 資料表的 執行個體。`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_tw/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_tw/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`。
請注意，即使未顯示，大多數 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 方法。一般而言， `UpdateItem` 會在使用 `SaveBehavior.CLOBBER`和 時呼叫 `SaveBehavior.PUT`。自動產生的金鑰是特殊的使用案例，偶爾同時使用 `UpdateItem` `PutItem`和 。 | 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 操作：**`Query`使用 `Select.COUNT` | 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 操作：**`Scan`使用 `Select.COUNT` | 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();
|
| 在對應至 POJO 類別的 DynamoDB 中建立資料表 **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 操作：**`Scan`使用 `Segment`和 `TotalSegments` 參數 | 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") |
| 指定類別成員是雜湊/分割區索引鍵 | @DynamoDBHashKey
| @DynamoDbPartitionKey
|
| 指定類別成員是範圍/排序索引鍵 | @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_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
### V2 其他註釋
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 如果 Java 值為 null，則指定類別成員不要儲存為 NULL 屬性 | N/A | @DynamoDbIgnoreNulls
|
| 如果所有屬性都是 null，請將類別成員指定為空白物件 | N/A | @DynamoDbPreserveEmptyObject
|
| 為類別成員指定特殊更新動作 | N/A | @DynamoDbUpdateBehavior
|
| 指定不可變類別 | N/A | @DynamoDbImmutable
|
| 將類別成員指定為自動遞增的計數器屬性 | N/A | @DynamoDbAtomicCounter
自動載入提供此功能的延伸模組。 |
## Configuration
在 V1 中，您通常會使用 執行個體來控制特定行為`DynamoDBMapperConfig`。您可以在建立映射器或提出請求時提供組態物件。在 V2 中，組態專屬於 操作的請求物件。
| 使用案例 | V1 | V1 中的預設值 | V2 |
| --- | --- | --- | --- |
| | DynamoDBMapperConfig.builder()
| | |
| 批次載入/寫入重試策略 | .withBatchLoadRetryStrategy(loadRetryStrategy)
.withBatchWriteRetryStrategy(writeRetryStrategy)
| 重試失敗的項目 | 在基礎 上設定重試策略DynamoDBClient。請參閱本指南[在 中設定重試行為 AWS SDK for Java 2.x](retry-strategy.md)中的 。 |
| 一致的讀取 | .withConsistentReads(CONSISTENT)
| EVENTUAL | 根據預設，讀取操作的一致性讀取為 false。在請求物件.consistentRead(true)上使用 覆寫 。 |
| 具有 marshallers/unmarshallers 集的轉換結構描述 | .withConversionSchema(conversionSchema)
靜態實作提供與舊版的回溯相容性。 | V2\$1COMPATIBLE | 不適用。這是舊版功能，指 DynamoDB (V1) 儲存資料類型的最早版本，而且此行為不會保留在增強型用戶端中。DynamoDB V1 中的行為範例是將布林值儲存為數字而非布林值。 |
| 資料表名稱 | .withObjectTableNameResolver()
.withTableNameOverride()
.withTableNameResolver()
靜態實作提供與舊版的回溯相容性 | 使用 類別的註釋或猜測 | 呼叫 `DynamoDbEnhancedClient#table()`方法時會定義資料表名稱。 |
| 分頁載入策略 | .withPaginationLoadingStrategy(strategy)
選項為：LAZY\$1`EAGER_LOADING`、 `LOADING`或 `ITERATION_ONLY` | LAZY\$1LOADING | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| 請求指標集合 | .withRequestMetricCollector(collector)
| null | 在建置標準 DynamoDB 用戶端metricPublisher()ClientOverrideConfiguration時使用 。 |
| 儲存行為 | .withSaveBehavior(SaveBehavior.CLOBBER)
選項為 `UPDATE`、`CLOBBER`、`APPEND_SET`、 `PUT`或 `UPDATE_SKIP_NULL_ATTRIBUTES`。 | UPDATE | 在 V2 中，您可以明確呼叫 `putItem()`或 `updateItem()` 。 `CLOBBER or PUT`：v 2 中的對應動作正在呼叫 `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 中，您可以使用 註釋 getter 方法`@DynamoDBTypeConverted`，以指定在 Java 屬性類型和 DynamoDB 屬性類型之間轉換的類別。例如，可在 Java `Currency`類型和 DynamoDB 字串之間`CurrencyFormatConverter`轉換的 可套用，如下列程式碼片段所示。
```
@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**：將空字串轉換為 null 值，再傳送至 DynamoDB （無屬性）
+ **V2**：將空字串作為實際空字串值傳送至 DynamoDB
**重要**
遷移至 V2 之後，如果您不希望在 DynamoDB 中存放空字串，則必須實作自訂轉換器。如果沒有自訂轉換器，V2 會將空字串儲存為 DynamoDB 項目中的實際空字串屬性，這與 V1 完全省略這些屬性的行為不同。
**Example 將空字串屬性轉換為 null 的 V2 自訂轉換器**
```
/**
* 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。 | 如果條件式檢查驗證要更新的物件版本編號符合資料庫中的編號，則版本編號屬性會遞增。 使用 設定`incrementBy`的選項遞增的版本編號屬性`@DynamoDbVersionAttribute(incrementBy = X)`。預設值為 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 類別。 | 您可以在transactWriteItems請求的addConditionCheck建置器方法中使用具有 @DynamoDbVersionAttribute註釋的 Bean 類別。 |
| 停用 | 透過將 DynamoDBMapperConfig.SaveBehavior列舉值從 變更為 UPDATE來停用樂觀鎖定CLOBBER。 | 請勿使用 `@DynamoDbVersionAttribute`註釋。 |
# 適用於 Java 的 SDK 第 1 版和第 2 版之間的流暢設定器差異
您可以在適用於 V1 POJOs 搭配流暢的設定器，以及搭配自 2.30.29 版以來的 V2。 DynamoDB
例如，下列 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`傳回`name`值為 的`Customer`執行個體`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.
}
}
```
# 記錄 第 1 版和第 2 版之間的 API 差異 適用於 Java 的 AWS SDK
文件 API 支援使用 JSON 樣式的文件做為 DynamoDB 資料表中的單一項目。V1 文件 API 在 V2 中具有對應的 API，但 V1, V2 中一樣針對文件 API 使用單獨的用戶端。 DynamoDB
在 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 |
| --- |--- |--- |
| Create a document client | 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.
|
| Reference a table | 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** |
| --- |
| Put item | 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);
|
| Get item | 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** |
| --- |
| Convert a JSON structure to use it with the Document 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());
|
| Put JSON | documentTable.putItem(item)
| documentTable.putItem(document);
|
| Read 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](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，可協助建立表達式以使用 V2 中的文件導向資料。V2 使用表達式 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-) 和[掃描](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html#scan-com.amazonaws.services.dynamodbv2.xspec.ScanExpressionSpec-) | DynamoDB 增強型用戶端APIs： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) 當您建立請求物件時，您會在 `DynamoDbTable` 方法中使用表達式。例如，在 的 `filterExpression`方法中 [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) |
| Resources | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) | 本 Java 開發人員指南中的[表達式資訊](ddb-en-client-expressions.md) |
# 加密程式庫遷移
如需遷移 DynamoDB 加密程式庫以使用 Java 開發套件 V2 的相關資訊，請參閱 [Amazon DynamoDB 加密用戶端開發人員指南](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/ddb-java-migrate.html)。
# 從第 1 版到第 2 版的自動 Amazon SQS 請求批次變更
本主題詳細說明 第 1 版和第 2 版之間的 Amazon SQS 自動請求批次處理變更 適用於 Java 的 AWS SDK。
## 高階變更
適用於 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 |
| 回呼機制 | 需要AsyncHandler具有個別 onSuccess和 onError方法的 | 使用 JDK 提供的 CompletableFuture APIs，例如 whenComplete()、thenCompose()、 thenApply() |
| 例外狀況處理 | 使用 AsyncHandler\$1onError() 方法 | 使用 JDK 提供的 CompletableFuture APIs，例如 exceptionally()、 handle()或 whenComplete() |
| Cancellation | 透過 的基本支援 Future.cancel() | 取消父系CompletableFuture會自動取消鏈結中的所有相依未來 |
## 非同步完成處理差異
| 變更 | 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 (20 秒，若 longPoll為 true) | receiveMessageMinWaitDuration （預設 50 毫秒） |
| 訊息屬性 | 使用 設定 ReceiveMessageRequest | receiveMessageAttributeNames （預設為無） |
| 系統屬性 | 使用 設定 ReceiveMessageRequest | receiveMessageSystemAttributeNames （預設為無） |
| 長輪詢 | longPoll （預設值為 true) | 不支援以避免開放連線等待伺服器傳送訊息 |
| 長輪詢的等待時間上限 | longPollWaitTimeoutSeconds （預設 20 秒） | 不支援以避免開放連線等待伺服器傳送訊息 |
| 儲存用戶端的預先擷取接收批次數目上限 | maxDoneReceiveBatches (10 個批次） | 不支援，因為它是在內部處理 |
| 同時處理的作用中傳出批次數量上限 | maxInflightOutboundBatches （預設 5 個批次） | 不支援，因為它是在內部處理 |
| 同時處理的作用中接收批次數量上限 | maxInflightReceiveBatches （預設 10 個批次） | 不支援，因為它是在內部處理 |
# side-by-side使用適用於 Java 的 開發套件 1.x 和 2.x
您可以在專案 適用於 Java 的 AWS SDK 中使用 的兩個版本。
以下顯示 Amazon S3 使用 1.x 版和 1.x 版 的 專案`pom.xml`檔案範例 ，以及 DynamoDB 使用 的 版本 - 2.27.21 1.2 版 - 的 。
**Example 範例 POM**
此範例顯示同時使用 SDK 1.x 和 2.x 版本的專案`pom.xml`的檔案項目。
```
com.amazonaws
aws-java-sdk-bom
1.12.1
pom
import
software.amazon.awssdk
bom
2.27.21
pom
import
com.amazonaws
aws-java-sdk-s3
software.amazon.awssdk
dynamodb
```