| 直接再開可能なオブジェクト | サポート外 |
### 結果オブジェクト
| 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 クライアントによって異なります。CRT AWS ベースの S3 クライアントまたは標準の Java ベースの S3 非同期クライアントを選択できます。違いの詳細については、[の S3 クライアント AWS SDK for Java 2.x](examples-s3.md#s3-clients) トピックを参照してください。
------
#### [ Use the AWS CRT-based S3 client ]
****
| 設定 | v1 | v2 - CRT AWS ベースの 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 からバージョン 2 での Amazon S3 URI の解析の変更
このトピックでは、バージョン 1 (v1) からバージョン 2 (v2) での Amazon S3 URI の解析に関する変更点について詳しく説明します。
## 高レベル変更
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` を `" "` に置き換える必要があります。
# バージョン 1 からバージョン 2 での S3 イベント通知 API の変更
このトピックでは、 AWS SDK for Javaのバージョン 1.x (v1) からバージョン 2 .x (v2) での S3 イベント通知 API の変更について詳しく説明します。
## 高レベル変更
### 構造の変更
V1 は `EventNotificationRecord` 型とその属性に静的内部クラスを使用しますが、v2 は `EventNotificationRecord` 型に個別のパブリッククラスを使用します。
### 命名規則の変更
v1 では、属性クラス名にはサフィックス「Entity」**が含まれますが、v2 では、より単純な命名のためにこのサフィックスを省略します。例えば、「eventDataEntity」**ではなく「eventData」**となります。
## 依存関係、パッケージ、クラス名の変更
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 |
| --- | --- | --- |
| 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();
|
| Intelligent Tiering イベントデータを取得する | 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();
|
| ユーザー ID 情報を取得する | 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 から AWS SDK for Java 1.x 上のすべての依存関係が削除されます。
`aws-lambda-java-events` ライブラリと SDK for Java 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 がファイルを解析する方法をより厳密にエミュレートします。
SDK for Java 2.x:
+ `$HOME`、`$USERPROFILE` (Windows のみ）、`$HOMEDRIVE`、 `$HOMEPATH` (Windows のみ）、`user.home` システムプロパティの順にチェックして、パスの開始時にファイルシステムのデフォルトパス区切り文字の前の `~/` または `~` を解決します。
+ `AWS_CREDENTIAL_PROFILES_FILE` ではなく `AWS_SHARED_CREDENTIALS_FILE` 環境変数を探します。
+ プロファイル名の先頭に `profile` という単語を付けずに、設定ファイル内のプロファイル定義を警告なくドロップします。
+ 英数字、アンダースコア、ダッシュ文字で構成されていないプロファイル定義を警告なく削除します (設定ファイルで先頭の `profile` 単語が削除された後）。
+ 同じファイル内で重複したプロファイル定義の設定をマージします。
+ 設定ファイルと認証情報ファイルの両方で重複したプロファイル定義の設定をマージします。
+ `[profile foo]` と `[foo]` の両方が同じファイルで見つかった場合、設定をマージしません。
+ 設定ファイルで `[profile foo]` と `[foo]` の両方が見つかった場合、`[profile foo]` の設定を使用します。
+ 同じファイルとプロファイルで最後に重複した設定の値を使用します。
+ コメントを定義するために `;` と `#` の両方を認識します。
+ 文字が閉じ括弧に隣接する場合でも、プロファイル定義で `;` と `#` を認識してコメントを定義します。
+ 空白が前にある場合にのみ `;` および `#` を認識し、値の設定でコメントのみを定義します。
+ 空白が前にない場合、`;` および `#` と以下の値の設定内のすべてのコンテンツを認識します。
+ ロールベースの認証情報を最も優先度の高い認証情報と見なします。ユーザーが `role_arn` プロパティを指定した場合、2.x SDK は常にロールベースの認証情報を使用します。
+ セッションベースの認証情報を 2 番目に優先度の高い認証情報と見なします。ロールベースの認証情報が使用されておらず、ユーザーが `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 | サポートされません | サポートされません |
| | com.amazonaws.sdk.enableThrottledRetry | サポートされません | サポートされません |
| | 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/ja_jp/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 への変更
このトピックでは、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 形式の文字列として返します。その一例が、[インスタンス ID ドキュメント](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html)の動的メタデータです。
v1 API にはインスタンス ID メタデータごとに個別のメソッドが含まれていますが、v2 API は JSON 文字列を直接返します。JSON 文字列を処理するには、[ドキュメント API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) を使用して応答を解析し、JSON 構造に移動します。
次の表は、v1 と v2 でインスタンス ID ドキュメントのメタデータを取得する方法を比較したものです。
****
| ユースケース | 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();
|
### エンドポイント解決の違い
次の表は、エンドポイントを IMDS に対して解決するために SDK がチェックする場所を示しています。場所は優先度の高い順にリストされています。
****
| 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://169.254.169.254` で、IPv6 では `http://[fd00:ec2::254]` です。
次の表に、エンドポイントモードを設定するさまざまな方法を優先順位の高い順に示します。
****
| | | 使用できる値 |
| --- | --- | --- |
| クライアントビルダーの設定方法: 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 での SDK による `endpoint` または `endpoint-mode` の解決方法
1. SDK は、クライアントビルダーのコードで設定した値を使用し、外部設定は無視します。`endpoint` および `endpointMode` が両方ともクライアントビルダーで呼び出されると SDK は例外をスローするため、SDK はユーザーが使用するメソッドのエンドポイント値を使用します。
1. コードで値を設定しない場合、SDK は外部設定を調べます。最初にシステムプロパティを検索し、次に設定ファイル内の設定を検索します。
1. SDK は最初にエンドポイント値をチェックします。値が見つかると、その値が使用されます。
1. 値が見つからない場合は、SDK はエンドポイントモード設定を探します。
1. 最後に、SDK が外部設定を見つけられず、コードでメタデータクライアントを設定していない場合は、SDK は IPv4 の値の `http://169.254.169.254` を使用します。
### IMDSv2
Amazon EC2 では、インスタンスメタデータにアクセスするための 2 つのアプローチを定義しています。
+ インスタンスメタデータサービスバージョン 1 (IMDSv1) – リクエスト/レスポンスアプローチ
+ インスタンスメタデータサービスバージョン 2 (IMDSv2) – セッション指向アプローチ
次の表は、Java SDK が IMDS をどのように使用するかを比較したものです。
****
| v1 | v2 |
| --- | --- |
| IMDSv2 がデフォルトで使用される | IMDSv2 を常に使用する |
| リクエストごとにセッショントークンの取得を試み、セッショントークンの取得に失敗した場合は IMDSv1 にフォールバックする | セッショントークンを内部キャッシュに保持し、複数のリクエストで再利用する |
SDK for Java 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 は 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 Policy Builder API のバージョン 1 からバージョン 2 での変更
このトピックでは、バージョン 1 (v1) からバージョン 2 (v2) での IAM Policy Builder API の変更点について詳しく説明します。
## 高レベル変更
****
| 変更 | 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/ja_jp/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/ja_jp/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)`
次の例では、`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);
```
### 条件
#### 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` タイプを定義します。たとえば、次の例は条件に対する*Not Like* [文字列比較](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)` を使用してポリシーステートメントの条件を構築し、すべてのタイプに `enums` を含む `[IamConditionOperator](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamConditionOperator.html)` を指定します。
```
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)
+ [SQSQueueResource](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,"*")`。
+ すべての正規ユーザーの `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 への変更 AWS SDK for Java
**Topics**
+ [のバージョン 1 とバージョン 2 の DynamoDB マッピング API の違い AWS SDK for Java](ddb-mapping.md)
+ [のバージョン 1 とバージョン 2 の API の違いを文書化する AWS SDK for Java](dynamodb-mapping-document-api.md)
+ [暗号化ライブラリの移行](ddb-encryption-lib-migrate.md)
# のバージョン 1 とバージョン 2 の DynamoDB マッピング API の違い AWS SDK for Java
AWS SDK for Javaのバージョン 1 とバージョン 2 で、DynamoDB マッピング API が大幅に変更されました。バージョン 1 では、 `DynamoDBMapper` を使用して Java POJO を操作します。バージョン 2 では、更新されたメソッド名、拡張されたスキーマ定義オプション、より安全な型を利用できる `DynamoDbEnhancedClient` を使用します。
主な変更点は次のとおりです。
+ 新しいメソッド名 (`getItem` の代わりに `load` など)
+ 明示的なテーブルスキーマの作成
+ 同期オペレーションと非同期オペレーション両方の組み込みサポート
+ 空の文字列と設定の処理方法の変更
このセクションでは、マッピング API の変更、注釈の違い、設定の更新について説明し、v1 `DynamoDBMapper` から v2 `DynamoDbEnhancedClient` への移行に役立つ移行ガイダンスを提供します。
**Contents**
+ [SDK for Java のバージョン 1 からバージョン 2 での、マッピングライブラリ高レベル変更](dynamodb-mapping-high-level.md)
+ [依存関係の差異をインポートする](dynamodb-mapping-high-level.md#dynamodb-mapping-deps)
+ [SDK for Java のバージョン 1 とバージョン 2 での DynamoDB マッピング API の変更](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)
+ [Table operations](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)
+ [SDK for Java のバージョン 1 とバージョン 2 の文字列処理の違い](dynamodb-migration-string-handling.md)
+ [SDK for Java のバージョン 1 とバージョン 2 の楽観的ロックの違い](dynamodb-migrate-optimstic-locking.md)
+ [SDK for Java のバージョン 1 とバージョン 2 の Fluent セッターの違い](dynamodb-migrate-fluent-setters.md)
# SDK for Java のバージョン 1 からバージョン 2 での、マッピングライブラリ高レベル変更
各ライブラリのマッピングクライアントの名前は、V1 と V2 で異なります。
+ V1 - DynamoDBMapper
+ V2 - DynamoDB Enhanced Client
2 つのライブラリの使用方法はほぼ同じです。マッパー/クライアントをインスタンス化し、これらの項目を DynamoDB テーブルに対して読み書きする API に Java POJO を渡します。どちらのライブラリも POJO のクラスに注釈を提供し、クライアントが POJO をどのように処理するかを指示します。
V2 に移行する場合の顕著な違いは次のとおりです。
+ V2 と V1 は、低レベルの DynamoDB オペレーションに異なるメソッド名を使用します。例えば、次のようになります。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 には、テーブルスキーマを定義し、POJO をテーブルにマッピングする複数の方法があります。注釈を使用することも、ビルダーを使用してコードから生成されたスキーマを使用することもできます。V2 は、変更可能なバージョンと変更不可能なバージョンのスキーマも提供します。
+ V2 では、最初のステップの 1 つとしてテーブルスキーマを具体的に作成しますが、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 では、すべての API が同期バージョンと非同期バージョンで使用できます。
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 では、1 つの依存関係に低レベルの DynamoDB API とマッピング/ドキュメント API の両方が含まれますが、V2 では、`dynamodb-enhanced` アーティファクト依存関係を使用してマッピング/ドキュメント API にアクセスします。`dynamodb-enhanced` モジュールには、低レベル `dynamodb` モジュールへの推移的な依存関係が含まれています。
# SDK for Java のバージョン 1 とバージョン 2 での DynamoDB マッピング API の変更
## クライアントの作成
****
| ユースケース | 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/ja_jp/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) [V1 の `query` メソッド](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html#DynamoDBMapper.Methods.query)について説明する DynamoDB デベロッパーガイドのセクションでは、完全な例を示しています。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) 詳細については、このガイドの「[セカンダリインデックスを使用する](ddb-en-client-use-secindex.md)」セクションを参照してください。 |
## Table operations
このセクションでは、ほとんどの標準的なユースケースにおいて V1 と V2 で異なるオペレーション API について説明します。
V2 では、単一のテーブルを含むすべてのオペレーションが、拡張クライアントではなく `DynamoDbTable` インスタンスで呼び出されます。拡張クライアントには、複数のテーブルをターゲットにできるメソッドが含まれています。
以下の「*テーブルオペレーション*」という表では、POJO インスタンスは `item` または `customer1` などの特定のタイプとして記載されています。V2 の例の場合、`table` という名前のインスタンスは、`DynamoDbTable` インスタンスへの参照を返す `enhancedClient.table()` を以前に呼び出した結果です。
ほとんどの V2 オペレーションは、表示されていない場合で fluent コンシューマーパターンで呼び出すことができます。例えば、
```
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)
```
**Table operations**
| ユースケース | 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();
|
| 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 オペレーション:** `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") |
| クラスメンバーをハッシュ/パーティションキーとして指定する | @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/ja_jp/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()
| | |
| バッチロード/書き込みの再試行戦略 | .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/ja_jp/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| リクエストメトリクスの収集 | .withRequestMetricCollector(collector)
| null | 標準 DynamoDB クライアントを構築するときは、metricPublisher() で ClientOverrideConfiguration を使用します。 |
| 保存動作 | .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` を使用してゲッターメソッドに注釈を付けて、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 では、ゲッターにのみ注釈を適用できます。
### タイプコンバータファクトリまたはプロバイダーを追加する
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 の完全な例が含まれています。
# SDK for Java のバージョン 1 とバージョン 2 の文字列処理の違い
V1 と V2 では、DynamoDB にデータを送信するときの空の文字列の処理方法が異なります。
+ **V1**: DynamoDB に送信する前に空の文字列を null 値に変換します (属性なしになります)。
+ **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;
}
}
```
# SDK for Java のバージョン 1 とバージョン 2 の楽観的ロックの違い
V1 と V2 の両方で、Bean クラス内の 1 つのプロパティにバージョン番号を保存するための属性アノテーションを付与することで、楽観的ロックが実装されています。
**楽観的ロック動作の違い**
| | V1 | V2 |
| --- | --- | --- |
| Bean クラスの注釈 | @DynamoDBVersionAttribute | @DynamoDbVersionAttribute (V2 は小文字の「b」を使用することに注意してください) |
| 初期保存 | 1 に設定されたバージョン番号属性。 | `@DynamoDbVersionAttribute(startAt = X)` で設定されたバージョン属性の開始値。デフォルト値は 0 です。 |
| 更新 | 更新されるオブジェクトのバージョン番号がデータベース内の番号と一致することが条件チェックで検証されると、バージョン番号属性が 1 ずつ増加します。 | 更新されるオブジェクトのバージョン番号がデータベース内の番号と一致することが条件チェックで検証されると、バージョン番号属性が増加します。 `@DynamoDbVersionAttribute(incrementBy = X)` で設定された `incrementBy` オプションによって増加するバージョン番号属性。デフォルト値は 1 です。 |
| Delete | 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` 注釈を使用しないでください。 |
# SDK for Java のバージョン 1 とバージョン 2 の Fluent セッターの違い
V1 の DynamoDB マッピング API では Fluent セッターを持つ POJO を使用でき、V2 でもバージョン 2.30.29 以降で使用できます。
たとえば、次の 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` は `null` の `name` 値を持つ `Customer` インスタンスを返します。
```
// 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 の違いを文書化する AWS SDK for Java
ドキュメント API は、DynamoDB テーブルでの単一項目としての JSON 形式ドキュメントの使用をサポートしています。V1 の ドキュメント API に対応する API が V2 にありますが、V1 のようにドキュメント API に別のクライアントを使用するのではなく、V2 には 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 のドキュメント API の違いを比較したものです。
| ユースケース | 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 の API リファレンスとガイド
| | 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 の式仕様 API から V2 の式 API
ドキュメント指向データを操作するための式の作成に役立つ、V1 で利用可能な式仕様 (Xspec) API は、V2 では使用できません。V2 は 式 API を使用します。この API は、ドキュメント指向データと、オブジェクトから項目にマッピングされたデータの両方で動作します。
****
| | V1 | V2 |
| --- | --- | --- |
| API 名 | 式仕様 (Xspec) API | 式 API |
| 動作可能 | [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-) などのドキュメント API [テーブル](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html)クラスのメソッド | DynamoDB 拡張クライアントの両方の API [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) どちらのタイプの API でも、[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/ja_jp/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/ja_jp/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) | この Java デベロッパーガイドの[式の情報](ddb-en-client-expressions.md) |
# 暗号化ライブラリの移行
Java SDK の V2 で動作するように DynamoDB の暗号化ライブラリを移行する方法については、「[Amazon DynamoDB 暗号化クライアントデベロッパーガイド](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/ddb-java-migrate.html)」を参照してください。
# バージョン 1 からバージョン 2 での Amazon SQS リクエストの自動バッチ処理の変更
このトピックでは、 AWS SDK for Javaのバージョン 1 とバージョン 2 での Amazon SQS の自動リクエストバッチ処理の変更について詳しく説明します。
## 高レベル変更
AWS SDK for Java 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 が必要です | whenComplete()、thenCompose()、thenApply() など、JDK が提供する CompletableFuture API を使用します。 |
| 例外処理 | AsyncHandler\$1onError() メソッドを使用する | exceptionally()、handle()、whenComplete() など、JDK が提供する CompletableFuture API を使用します。 |
| Cancellation | 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 バッチ) | 内部で処理されるため、サポートされていません |
# SDK for Java 1.x と 2.x を並行して使用する
プロジェクトで AWS SDK for Java の両方のバージョンを使用できます。
バージョン 1.x から Amazon S3 を使用し、バージョン 2.27.21 から DynamoDB を使用するプロジェクト用の `pom.xml` ファイルの例を以下に示します。
**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
```