AWS SDK for Java 2.x - Amazon S3

概要

AWS SDK for Java 2.x を使用した S3 操作のパターンを提供します。バケット管理、マルチパートアップロード対応のオブジェクトアップロード/ダウンロード、署名付き URL、S3 Transfer Manager、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();

// リトライロジック付き
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);

// 準備完了まで待機
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)));

// アップロード完了を検証
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. 検証付きでアップロード
PutObjectRequest putRequest = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .contentType(contentType)
    .build();

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

// 2. headObject で検証
HeadObjectResponse headResp = s3Client.headObject(HeadObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build());

// 3. メタデータを確認
long fileSize = Files.size(Paths.get(filePath));
if (headResp.contentLength() != fileSize) {
    throw new IllegalStateException("Upload size mismatch");
}

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

// 1. マルチパートアップロードを開始
CreateMultipartUploadRequest createRequest = CreateMultipartUploadRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

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

try {
    // 2. パートをアップロード
    List<CompletedPart> parts = new ArrayList<>();
    int partNumber = 1;
    byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
    int chunkSize = 5 * 1024 * 1024; // 5MB 最小値

    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. マルチパートアップロードを完了
    CompleteMultipartUploadRequest completeRequest = CompleteMultipartUploadRequest.builder()
        .bucket(bucketName)
        .key(key)
        .uploadId(uploadId)
        .multipartUpload(CompletedMultipartUpload.builder().parts(parts).build())
        .build();
    s3Client.completeMultipartUpload(completeRequest);

} catch (Exception e) {
    // 4. 失敗時に中止
    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 Developer Guide
• AWS SDK for Java 2.x S3 API

関連スキル

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