aws-sdk-java-v2-s3

AWS SDK for Java 2.x - Amazon S3

概要

AWS SDK for Java 2.x を使用して、バケット管理、マルチパート対応のオブジェクトのアップロード／ダウンロード、署名付き URL、S3 Transfer Manager、S3 固有の設定など、S3 操作のパターンを提供します。

使用する場面

• 適切な設定で S3 バケットを作成、一覧表示、削除する
• メタデータと暗号化を使用して、S3 からオブジェクトをアップロードまたはダウンロードする
• エラー処理を行いながら、大容量ファイル（>100MB）のマルチパートアップロードを扱う
• S3 オブジェクトへの一時的なアクセス用に署名付き URL を生成する
• メタデータを保持しながら、S3 バケット間でオブジェクトをコピーまたは移動する
• オブジェクトのメタデータ、ストレージクラス、アクセス制御を設定する
• 最適化されたファイル転送のために S3 Transfer Manager を実装する
• クラウドストレージとして S3 を Spring Boot アプリケーションに統合する

クイックリファレンス

操作	メソッド	備考
バケットを作成	createBucket()	waiter().waitUntilBucketExists() で待機します
オブジェクトをアップロード	putObject()	RequestBody.fromFile() を使用します
オブジェクトをダウンロード	getObject()	ファイルまたはメモリにストリーミングします
オブジェクトを削除	deleteObjects()	最大 1000 個のキーを一括処理します
署名付き URL	presigner.presignGetObject()	有効期限は最大 7 日間です

ストレージクラス

クラス	用途
STANDARD	頻繁にアクセスするデータ
STANDARD_IA	アクセス頻度の低いデータ
GLACIER	長期アーカイブ
INTELLIGENT_TIERING	コストを自動的に最適化

手順

1. 依存関係を追加する

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.20.0</version>
</dependency>

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3-transfer-manager</artifactId>
    <version>2.20.0</version>
</dependency>

2. S3 クライアントを作成する

S3Client s3Client = S3Client.builder()
    .region(Region.US_EAST_1)
    .build();

// With retry logic
S3Client s3Client = S3Client.builder()
    .region(Region.US_EAST_1)
    .overrideConfiguration(b -> b
        .retryPolicy(RetryPolicy.builder()
            .numRetries(3)
            .build()))
    .build();

3. バケットを作成する

CreateBucketRequest request = CreateBucketRequest.builder()
    .bucket(bucketName)
    .build();

s3Client.createBucket(request);

// Wait until ready
s3Client.waiter().waitUntilBucketExists(
    HeadBucketRequest.builder().bucket(bucketName).build()
);

4. オブジェクトをアップロードする

PutObjectRequest request = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .contentType("application/pdf")
    .serverSideEncryption(ServerSideEncryption.AES256)
    .storageClass(StorageClass.STANDARD_IA)
    .build();

s3Client.putObject(request, RequestBody.fromFile(Paths.get(filePath)));

// Validate upload completion
HeadObjectResponse headResp = s3Client.headObject(HeadObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build());

5. オブジェクトをダウンロードする

GetObjectRequest request = GetObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

s3Client.getObject(request, Paths.get(destPath));

6. 署名付き URL を生成する

try (S3Presigner presigner = S3Presigner.create()) {
    GetObjectRequest getRequest = GetObjectRequest.builder()
        .bucket(bucketName)
        .key(key)
        .build();

    GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder()
        .signatureDuration(Duration.ofMinutes(10))
        .getObjectRequest(getRequest)
        .build();

    String url = presigner.presignGetObject(presignRequest).url().toString();
}

7. Transfer Manager を使用する（大容量ファイル）

try (S3TransferManager tm = S3TransferManager.create()) {
    UploadFileRequest request = UploadFileRequest.builder()
        .putObjectRequest(req -> req.bucket(bucketName).key(key))
        .source(Paths.get(filePath))
        .build();

    FileUpload upload = tm.uploadFile(request);
    CompletedFileUpload result = upload.completionFuture().join();
}

ベストプラクティス

パフォーマンス

• S3 Transfer Manager を使用する：100MB を超えるファイルを自動的にマルチパートアップロードします
• S3 クライアントを再利用する：クライアントはスレッドセーフなので、アプリケーション全体で再利用します
• 非同期操作を有効にする：I/O 待ちが発生する操作には S3AsyncClient を使用します
• タイムアウトを設定する：大容量ファイルの操作に適切なタイムアウトを設定します

セキュリティ

• 一時的な認証情報を使用する：有効期間の短いトークンには IAM ロールまたは AWS STS を使用します
• 暗号化を有効にする：機密データには AES-256 または AWS KMS を使用します
• 署名付き URL を使用する：一時的なアクセスを利用して認証情報の公開を避けます
• メタデータを検証する：ユーザーが指定したメタデータをサニタイズします

エラー処理

• 再試行ロジックを実装する：ネットワーク操作には指数バックオフを使用します
• スロットリングに対処する：429 応答を適切に処理します
• 失敗時にクリーンアップする：失敗したマルチパートアップロードを中止します

コストの最適化

• 適切なストレージクラスを使用する：STANDARD、STANDARD_IA、INTELLIGENT_TIERING
• ライフサイクルポリシーを実装する：移行／有効期限切れを自動化します
• API 呼び出しを最小限にする：可能な場合は一括操作を使用します

制約と警告

• オブジェクトサイズ：単一の PUT は 5GB に制限されます。これを超えるファイルにはマルチパートを使用してください
• バケット名：すべての AWS アカウントでグローバルに一意である必要があります
• オブジェクトの不変性：オブジェクトは変更できません。全体を置き換える必要があります
• 結果整合性：アップロード後、一覧表示操作にわずかな遅延が発生する場合があります
• 署名付き URL：有効期限は最大 7 日間です
• マルチパートアップロード：最後のパートを除き、各パートは 5MB 以上である必要があります

例

検証を含む完全なアップロードワークフロー

// 1. Upload with validation
PutObjectRequest putRequest = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .contentType(contentType)
    .build();

s3Client.putObject(putRequest, RequestBody.fromFile(Paths.get(filePath)));

// 2. Validate with headObject
HeadObjectResponse headResp = s3Client.headObject(HeadObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build());

// 3. Verify metadata
long fileSize = Files.size(Paths.get(filePath));
if (headResp.contentLength() != fileSize) {
    throw new IllegalStateException("Upload size mismatch");
}

失敗時に中止するマルチパートアップロード

// 1. Initiate multipart upload
CreateMultipartUploadRequest createRequest = CreateMultipartUploadRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

CreateMultipartUploadResponse multipartUpload = s3Client.createMultipartUpload(createRequest);
String uploadId = multipartUpload.uploadId();

try {
    // 2. Upload parts
    List<CompletedPart> parts = new ArrayList<>();
    int partNumber = 1;
    byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
    int chunkSize = 5 * 1024 * 1024; // 5MB minimum

    for (int offset = 0; offset < fileBytes.length; offset += chunkSize) {
        int length = Math.min(chunkSize, fileBytes.length - offset);
        UploadPartRequest uploadPartRequest = UploadPartRequest.builder()
            .bucket(bucketName)
            .key(key)
            .uploadId(uploadId)
            .partNumber(partNumber)
            .build();

        UploadPartResponse partResponse = s3Client.uploadPart(uploadPartRequest,
            RequestBody.fromBytes(Arrays.copyOfRange(fileBytes, offset, offset + length)));

        parts.add(CompletedPart.builder()
            .partNumber(partNumber)
            .eTag(partResponse.eTag())
            .build());
        partNumber++;
    }

    // 3. Complete multipart upload
    CompleteMultipartUploadRequest completeRequest = CompleteMultipartUploadRequest.builder()
        .bucket(bucketName)
        .key(key)
        .uploadId(uploadId)
        .multipartUpload(CompletedMultipartUpload.builder().parts(parts).build())
        .build();
    s3Client.completeMultipartUpload(completeRequest);

} catch (Exception e) {
    // 4. Abort on failure
    AbortMultipartUploadRequest abortRequest = AbortMultipartUploadRequest.builder()
        .bucket(bucketName)
        .key(key)
        .uploadId(uploadId)
        .build();
    s3Client.abortMultipartUpload(abortRequest);
    throw new RuntimeException("Upload failed, cleanup performed", e);
}

参考資料

• references/s3-client-setup.md — クライアントの設定と基本操作
• references/s3-object-operations.md — 高度なオブジェクト操作
• references/s3-transfer-patterns.md — Transfer Manager とマルチパートアップロード
• references/s3-spring-boot-integration.md — Spring Boot の統合パターン
• AWS S3 開発者ガイド
• AWS SDK for Java 2.x S3 API

関連スキル

• aws-sdk-java-v2-core - AWS SDK のコアパターンと設定
• spring-boot-dependency-injection - Spring の依存性注入パターン