はじめにファイルのアップロードファイルをダウンロードするオブジェクトのコピーディレクトリのアップロードディレクトリへダウンロードする完全な例を見る

Amazon S3 Transfer Manager を使用してファイルとディレクトリを転送する

Amazon S3 転送マネージャは、AWS SDK for Java 2.x 用のオープンソースの高レベルファイル転送ユーティリティです。Amazon Simple Storage Service (Amazon S3) との間でファイルやディレクトリを転送するために使用します。

AWS CRT ベースの S3 クライアントまたはマルチパートが有効になっている標準の Java ベースの S3 非同期クライアント上に構築すると、S3 Transfer Manager ではマルチパートアップロード API やバイト範囲フェッチなどのパフォーマンスの向上を活用できます。

S3 Transfer Manager では、転送の進行状況をリアルタイムでモニタリングし、転送を一時停止して後で実行することもできます。

はじめに

ビルドファイルに依存関係を追加する

S3 Transfer Manager で強化されたマルチパートパフォーマンスを利用するには、必要な依存関係を使用してビルドファイルを設定します。

S3 Transfer Manager のインスタンスを作成する

並列転送を有効にするには、AWS CRT ベースの S3 クライアントまたはマルチパートが有効になっている Java ベースの S3 非同期クライアントを渡す必要があります。次の例は、S3 Transfer Manager をカスタム設定する方法を示しています。

S3 バケットにファイルをアップロードする

次の例は、ファイルのアップロード例と、アップロードの進行状況をログ記録する LoggingTransferListener をオプションで使用したものです。

S3 Transfer Manager を使用して Amazon S3 にファイルをアップロードするには、S3TransferManagerの uploadFile メソッドにUploadFileRequest オブジェクトを渡します。

uploadFile メソッドから返される FileUpload オブジェクトはアップロードプロセスを表します。リクエストが完了すると、CompletedFileUpload オブジェクトはアップロードに関する情報を含めます。


    public void trackUploadFile(S3TransferManager transferManager, String bucketName,
                             String key, URI filePathURI) {
        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
                .putObjectRequest(b -> b.bucket(bucketName).key(key))
                .addTransferListener(LoggingTransferListener.create())  // Add listener.
                .source(Paths.get(filePathURI))
                .build();

        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);

        fileUpload.completionFuture().join();
        /*
            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
            You can also implement the interface to provide your own logic.

            Configure log4J2 with settings such as the following.
                <Configuration status="WARN">
                    <Appenders>
                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
                            <PatternLayout pattern="%m%n"/>
                        </Console>
                    </Appenders>

                    <Loggers>
                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
                            <AppenderRef ref="AlignedConsoleAppender"/>
                        </logger>
                    </Loggers>
                </Configuration>

            Log4J2 logs the progress. The following is example output for a 21.3 MB file upload.
                Transfer initiated...
                |                    | 0.0%
                |====                | 21.1%
                |============        | 60.5%
                |====================| 100.0%
                Transfer complete!
        */
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileUpload;
import software.amazon.awssdk.transfer.s3.model.FileUpload;
import software.amazon.awssdk.transfer.s3.model.UploadFileRequest;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;

S3 バケットからのファイルのダウンロード

次の例には、ダウンロードの例と、ダウンロードの進行状況をログ記録する LoggingTransferListener をオプションで使用する方法も示されています。

S3 Transfer Manager を使用して S3 バケットからオブジェクトをダウンロードするには、DownloadFileRequest オブジェクトを構築してそれを downloadFile メソッドに渡します。

S3TransferManager の downloadFile メソッドによって返される FileDownload オブジェクトは、ファイル転送を表します。ダウンロードが完了すると、CompletedFileDownload はダウンロードに関する情報へのアクセスを含めます。


    public void trackDownloadFile(S3TransferManager transferManager, String bucketName,
                             String key, String downloadedFileWithPath) {
        DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
                .getObjectRequest(b -> b.bucket(bucketName).key(key))
                .addTransferListener(LoggingTransferListener.create())  // Add listener.
                .destination(Paths.get(downloadedFileWithPath))
                .build();

        FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);

        CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
        /*
            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
            You can also implement the interface to provide your own logic.

            Configure log4J2 with settings such as the following.
                <Configuration status="WARN">
                    <Appenders>
                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
                            <PatternLayout pattern="%m%n"/>
                        </Console>
                    </Appenders>

                    <Loggers>
                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
                            <AppenderRef ref="AlignedConsoleAppender"/>
                        </logger>
                    </Loggers>
                </Configuration>

            Log4J2 logs the progress. The following is example output for a 21.3 MB file download.
                Transfer initiated...
                |=======             | 39.4%
                |===============     | 78.8%
                |====================| 100.0%
                Transfer complete!
        */
    }



import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.exception.SdkException;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadFileRequest;
import software.amazon.awssdk.transfer.s3.model.FileDownload;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;

import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.UUID;

Amazon S3 バケットを他のバケットにコピーする

次の例は、S3 Transfer Manager を使用してオブジェクトをコピーする方法を示しています。

S3 バケットから別のバケットへのオブジェクトのコピーを開始するには、基本 CopyObjectRequest インスタンスを作成します。

次に、その基本 CopyObjectRequest を S3 Transfer Manager が使用できる CopyRequest にラップします。

S3TransferManager の copy メソッドによって返される Copy オブジェクトはコピープロセスを表します。コピープロセスが完了すると、CompletedCopy オブジェクトはレスポンスに関する詳細を含めます。


    public String copyObject(S3TransferManager transferManager, String bucketName,
            String key, String destinationBucket, String destinationKey) {
        CopyObjectRequest copyObjectRequest = CopyObjectRequest.builder()
                .sourceBucket(bucketName)
                .sourceKey(key)
                .destinationBucket(destinationBucket)
                .destinationKey(destinationKey)
                .build();

        CopyRequest copyRequest = CopyRequest.builder()
                .copyObjectRequest(copyObjectRequest)
                .build();

        Copy copy = transferManager.copy(copyRequest);

        CompletedCopy completedCopy = copy.completionFuture().join();
        return completedCopy.response().copyObjectResult().eTag();
    }

注記

S3 Transfer Manager を使用してクロスリージョンコピーを実行するには、次のスニペットに示すように、AWS CRT ベースの S3 クライアントビルダーで crossRegionAccessEnabled を有効にします。


S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
                .crossRegionAccessEnabled(true)
                .build();

S3TransferManager transferManager = S3TransferManager.builder()
                .s3Client(s3AsyncClient)
                .build();


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.CopyObjectRequest;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedCopy;
import software.amazon.awssdk.transfer.s3.model.Copy;
import software.amazon.awssdk.transfer.s3.model.CopyRequest;

import java.util.UUID;

ローカルディレクトリを S3 バケットにアップロードする

次の例は、ローカルディレクトリを S3 にアップロードする方法を示しています。

まず、S3TransferManager インスタンスの uploadDirectory メソッドを呼び出し、UploadDirectoryRequest を渡します。

DirectoryUpload オブジェクトはアップロードプロセスを表し、リクエストが完了すると CompletedDirectoryUpload を生成します。CompleteDirectoryUpload オブジェクトは、どのファイルが転送に失敗したかなど、転送の結果に関する情報を含めます。


    public Integer uploadDirectory(S3TransferManager transferManager,
            URI sourceDirectory, String bucketName) {
        DirectoryUpload directoryUpload = transferManager.uploadDirectory(UploadDirectoryRequest.builder()
                .source(Paths.get(sourceDirectory))
                .bucket(bucketName)
                .build());

        CompletedDirectoryUpload completedDirectoryUpload = directoryUpload.completionFuture().join();
        completedDirectoryUpload.failedTransfers()
                .forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
        return completedDirectoryUpload.failedTransfers().size();
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.DirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest;

import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;

ローカルディレクトリへの S3 バケットオブジェクトのダウンロード

次の例に示すように、S3 バケットのオブジェクトをローカルディレクトリにダウンロードできます。

S3 バケット内のオブジェクトをローカルディレクトリにダウンロードするには、まず Transfer Manager の downloadDirectory メソッドを呼び出し、DownloadDirectoryRequest を渡します。

DirectoryDownload オブジェクトはダウンロードプロセスを表し、リクエストが完了すると CompletedDirectoryDownload を生成します。CompleteDirectoryDownload オブジェクトは、どのファイルが転送に失敗したかなど、転送の結果に関する情報を含めます。


    public Integer downloadObjectsToDirectory(S3TransferManager transferManager,
            URI destinationPathURI, String bucketName) {
        DirectoryDownload directoryDownload = transferManager.downloadDirectory(DownloadDirectoryRequest.builder()
                .destination(Paths.get(destinationPathURI))
                .bucket(bucketName)
                .build());
        CompletedDirectoryDownload completedDirectoryDownload = directoryDownload.completionFuture().join();

        completedDirectoryDownload.failedTransfers()
                .forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
        return completedDirectoryDownload.failedTransfers().size();
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadDirectoryRequest;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;
import java.util.stream.Collectors;

完全な例を見る

GitHub には、このページのすべての例の完全なコードが含まれています。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

並列転送のサポートを設定する

S3 イベント通知