Amazon S3 操作の TransferManager の使用 - AWS SDK for Java 1.x

AWS SDK for Java 1.x は 2024 年 7 月 31 日にメンテナンスモードに入り、2025 年 12 月 31 end-of-support日に に到達します。新しい機能AWS SDK for Java 2.x、可用性の向上、セキュリティ更新を引き続き受けるには、 に移行することをお勧めします。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon S3 操作の TransferManager の使用

AWS SDK for Java TransferManager クラスを使用して、ローカル環境から Amazon S3へファイルを確実に転送し、S3 の複数の場所間でオブジェクトをコピーします。TransferManager は、転送の進行状況を取得し、アップロードとダウンロードの一時停止/再開を行うことができます。

注記

ベストプラクティス

バケットで AbortIncompleteMultipartUploadAmazon S3 ライフサイクルルールを有効にすることをお勧めします。

このルールは、開始後、指定された日数内に完了しないマルチパートアップロードを中止するよう Amazon S3 に指示できます。設定した時間制限を超えると、Amazon S3 はアップロードを中止して、不完全なアップロードデータを削除します。

詳細については、Amazon S3 ユーザーガイドのバージョニングを使用したバケットのライフサイクル設定を参照してください。

注記

これらのコード例では、ユーザーが AWS SDK for Java の使用の内容を理解し、開発用の AWS 認証情報とリージョンのセットアップの情報を使用してデフォルトの AWS 認証情報を設定していることを前提としています。

ファイルとディレクトリのアップロード

TransferManager は、以前に作成した Amazon S3 バケットのいずれに対してもファイル、ファイルリスト、ディレクトリをアップロードできます。

1 つのファイルのアップロード

TransferManager の upload メソッドを呼び出し、Amazon S3 バケット名、キー (オブジェクト) 名、アップロードするファイルを表す標準 Java ファイルオブジェクトを指定します。

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.MultipleFileUpload; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder; import com.amazonaws.services.s3.transfer.Upload; import java.io.File; import java.util.ArrayList; import java.util.Arrays;

Code

File f = new File(file_path); TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { Upload xfer = xfer_mgr.upload(bucket_name, key_name, f); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

upload メソッドは、即座に返され、転送の状態を確認する、または、転送が完了するまで待機するための Upload オブジェクトが提供されます。

waitForCompletion を使用して、転送が正常に完了した後に TransferManager の shutdownNow メソッドを呼び出すことの詳細については、転送の完了の待機を参照してください。転送の完了を待ちながら、転送の状態や進行状況に関する更新情報をポーリングまたはリスンできます。詳細については、「転送の状態と進行状況の取得」を参照してください。

GitHub で完全な例をご覧ください。

ファイルのリストのアップロード

複数のファイルを一括してアップロードするには、TransferManageruploadFileList メソッドを呼び出して、以下を指定します。

  • Amazon S3 バケット名

  • 作成したオブジェクトの名前の前に付加されるキープレフィックス (オブジェクトを置くバケット内のパス)

  • ファイルパスの作成元の相対ディレクトリを表すファイルオブジェクト

  • リストオブジェクト (アップロードする一連のファイルオブジェクトを含む)

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.MultipleFileUpload; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder; import com.amazonaws.services.s3.transfer.Upload; import java.io.File; import java.util.ArrayList; import java.util.Arrays;

Code

ArrayList<File> files = new ArrayList<File>(); for (String path : file_paths) { files.add(new File(path)); } TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { MultipleFileUpload xfer = xfer_mgr.uploadFileList(bucket_name, key_prefix, new File("."), files); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

waitForCompletion を使用して、転送が正常に完了した後に TransferManager の shutdownNow メソッドを呼び出すことの詳細については、転送の完了の待機を参照してください。転送の完了を待ちながら、転送の状態や進行状況に関する更新情報をポーリングまたはリスンできます。詳細については、「転送の状態と進行状況の取得」を参照してください。

uploadFileList から返される MultipleFileUpload オブジェクトを使用して、転送の状態や進行状況をクエリできます。詳細については、「転送の現在の進行状況のポーリング」と「ProgressListener による転送の進行状況の取得」を参照してください。

MultipleFileUploadgetSubTransfers メソッドを使用して、転送中の各ファイルについて個別の Upload オブジェクトを取得することもできます。詳細については、「サブ転送の進行状況の取得」を参照してください。

GitHub で完全な例をご覧ください。

ディレクトリのアップロード

TransferManager の uploadDirectory メソッドを使用して、ファイルのディレクトリ全体をアップロードし、オプションとしてファイルをサブディレクトリに再帰的にコピーできます。このメソッドに、Amazon S3 バケット名、S3 キープレフィックス、コピーするローカルディレクトリを表す File オブジェクト、およびサブディレクトリに再帰的にコピーするかどうか (booleantrue または false) を示す 値を渡します。

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.MultipleFileUpload; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder; import com.amazonaws.services.s3.transfer.Upload; import java.io.File; import java.util.ArrayList; import java.util.Arrays;

Code

TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { MultipleFileUpload xfer = xfer_mgr.uploadDirectory(bucket_name, key_prefix, new File(dir_path), recursive); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

waitForCompletion を使用して、転送が正常に完了した後に TransferManager の shutdownNow メソッドを呼び出すことの詳細については、転送の完了の待機を参照してください。転送の完了を待ちながら、転送の状態や進行状況に関する更新情報をポーリングまたはリスンできます。詳細については、「転送の状態と進行状況の取得」を参照してください。

uploadFileList から返される MultipleFileUpload オブジェクトを使用して、転送の状態や進行状況をクエリできます。詳細については、「転送の現在の進行状況のポーリング」と「ProgressListener による転送の進行状況の取得」を参照してください。

MultipleFileUploadgetSubTransfers メソッドを使用して、転送中の各ファイルについて個別の Upload オブジェクトを取得することもできます。詳細については、「サブ転送の進行状況の取得」を参照してください。

GitHub で完全な例をご覧ください。

ファイルまたはディレクトリのダウンロード

TransferManager クラスを使用して、1 つのファイル (Amazon S3 オブジェクト) またはディレクトリ (Amazon S3 バケット名とオブジェクトプレフィックス) を Amazon S3 からダウンロードできます。

1 つのファイルのダウンロード

TransferManager の download メソッドを使用して、ダウンロードするオブジェクトが含まれている Amazon S3 バケット名、キー (オブジェクト) 名、およびローカルシステムで作成するファイルを表すファイルオブジェクトを渡します。

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.Download; import com.amazonaws.services.s3.transfer.MultipleFileDownload; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder; import java.io.File;

Code

File f = new File(file_path); TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { Download xfer = xfer_mgr.download(bucket_name, key_name, f); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

waitForCompletion を使用して、転送が正常に完了した後に TransferManager の shutdownNow メソッドを呼び出すことの詳細については、転送の完了の待機を参照してください。転送の完了を待ちながら、転送の状態や進行状況に関する更新情報をポーリングまたはリスンできます。詳細については、「転送の状態と進行状況の取得」を参照してください。

GitHub で完全な例をご覧ください。

ディレクトリのダウンロード

同じキープレフィックス (ファイルシステムのディレクトリに相当) を共有するファイルのセットを Amazon S3 からダウンロードするには、TransferManagerdownloadDirectory メソッドを呼び出します。このメソッドに、ダウンロードするオブジェクトが含まれている Amazon S3 バケットの名前、すべてのオブジェクトに共有されているオブジェクトプレフィックス、およびローカルシステムにファイルをダウンロードする先のディレクトリを表す ファイル オブジェクトを渡します。指定したディレクトリがまだない場合は、自動的に作成されます。

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.Download; import com.amazonaws.services.s3.transfer.MultipleFileDownload; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder; import java.io.File;

Code

TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { MultipleFileDownload xfer = xfer_mgr.downloadDirectory( bucket_name, key_prefix, new File(dir_path)); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

waitForCompletion を使用して、転送が正常に完了した後に TransferManager の shutdownNow メソッドを呼び出すことの詳細については、転送の完了の待機を参照してください。転送の完了を待ちながら、転送の状態や進行状況に関する更新情報をポーリングまたはリスンできます。詳細については、「転送の状態と進行状況の取得」を参照してください。

GitHub で完全な例をご覧ください。

オブジェクトのコピー

S3 バケット間でオブジェクトをコピーするには、TransferManagercopy メソッドを使用します。

インポート

import com.amazonaws.AmazonServiceException; import com.amazonaws.services.s3.transfer.Copy; import com.amazonaws.services.s3.transfer.TransferManager; import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

Code

System.out.println("Copying s3 object: " + from_key); System.out.println(" from bucket: " + from_bucket); System.out.println(" to s3 object: " + to_key); System.out.println(" in bucket: " + to_bucket); TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { Copy xfer = xfer_mgr.copy(from_bucket, from_key, to_bucket, to_key); // loop with Transfer.isDone() XferMgrProgress.showTransferProgress(xfer); // or block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(xfer); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

GitHub で完全な例をご覧ください。

転送が完了するまで待つ

転送が完了するまでアプリケーション (またはスレッド) がブロックできる場合、Transfer インターフェイスの waitForCompletion メソッドを使用して転送が完了するまでブロックします。ブロックしないと、例外が発生します。

try { xfer.waitForCompletion(); } catch (AmazonServiceException e) { System.err.println("Amazon service error: " + e.getMessage()); System.exit(1); } catch (AmazonClientException e) { System.err.println("Amazon client error: " + e.getMessage()); System.exit(1); } catch (InterruptedException e) { System.err.println("Transfer interrupted: " + e.getMessage()); System.exit(1); }

を呼び出す前にwaitForCompletionイベントをポーリングする場合、別個のスレッドにポーリング機構を実装する場合、または ProgressListener を使用して非同期的に進行状況の更新を受け取る場合は、転送の進行状況が取得されます。

GitHub で完全な例をご覧ください。

転送の状態および進行状況の取得

TransferManagerupload*download*copy メソッドから返される各クラスは、1 つのファイルまたは複数のファイルの操作であるかどうかに応じて、以下のクラスのいずれかのインスタンスを返します。

Class 返すクラス

[Copy] (コピー)

copy

ダウンロード

download

MultipleFileDownload

downloadDirectory

アップロード

upload

MultipleFileUpload

uploadFileList, uploadDirectory

これらすべてのクラスは、Transfer インターフェイスを実装します。Transfer は、転送の進行状況の取得や転送の一時停止/再開、および、転送の現在や最終ステータスを取得するのに役立つメソッドを提供します。

転送の現在の進行状況のポーリング

このループでは、転送の進行状況を出力し、実行時は現在の進行状況を確認し、完了時は最終の状態を出力します。

インポート

import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.event.ProgressEvent; import com.amazonaws.event.ProgressListener; import com.amazonaws.services.s3.transfer.*; import com.amazonaws.services.s3.transfer.Transfer.TransferState; import java.io.File; import java.util.ArrayList; import java.util.Collection;

Code

// print the transfer's human-readable description System.out.println(xfer.getDescription()); // print an empty progress bar... printProgressBar(0.0); // update the progress bar while the xfer is ongoing. do { try { Thread.sleep(100); } catch (InterruptedException e) { return; } // Note: so_far and total aren't used, they're just for // documentation purposes. TransferProgress progress = xfer.getProgress(); long so_far = progress.getBytesTransferred(); long total = progress.getTotalBytesToTransfer(); double pct = progress.getPercentTransferred(); eraseProgressBar(); printProgressBar(pct); } while (xfer.isDone() == false); // print the final state of the transfer. TransferState xfer_state = xfer.getState(); System.out.println(": " + xfer_state);

GitHub で完全な例をご覧ください。

ProgressListener による転送の進行状況の取得

Transfer インターフェイスの addProgressListener メソッドを使用して、ProgressListener を任意の転送にアタッチできます。

ProgressListener は、メソッドとして progressChanged だけを必要とし、このメソッドに ProgressEvent オブジェクトを渡します。このオブジェクトでは、その getBytes メソッドを呼び出してオペレーションの総バイト数を取得できます。また、getBytesTransferred を呼び出してそれまでに転送されたバイト数を取得できます。

インポート

import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.event.ProgressEvent; import com.amazonaws.event.ProgressListener; import com.amazonaws.services.s3.transfer.*; import com.amazonaws.services.s3.transfer.Transfer.TransferState; import java.io.File; import java.util.ArrayList; import java.util.Collection;

Code

File f = new File(file_path); TransferManager xfer_mgr = TransferManagerBuilder.standard().build(); try { Upload u = xfer_mgr.upload(bucket_name, key_name, f); // print an empty progress bar... printProgressBar(0.0); u.addProgressListener(new ProgressListener() { public void progressChanged(ProgressEvent e) { double pct = e.getBytesTransferred() * 100.0 / e.getBytes(); eraseProgressBar(); printProgressBar(pct); } }); // block with Transfer.waitForCompletion() XferMgrProgress.waitForCompletion(u); // print the final state of the transfer. TransferState xfer_state = u.getState(); System.out.println(": " + xfer_state); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } xfer_mgr.shutdownNow();

GitHub で完全な例をご覧ください。

サブ転送の進行状況の取得

MultipleFileUpload クラスは、その getSubTransfers メソッドを呼び出してサブ転送に関する情報を返すことができます。アップロードオブジェクトの変更不能なコレクションを返して、サブ転送ごとの転送の状態と進行状況を提供します。

インポート

import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.event.ProgressEvent; import com.amazonaws.event.ProgressListener; import com.amazonaws.services.s3.transfer.*; import com.amazonaws.services.s3.transfer.Transfer.TransferState; import java.io.File; import java.util.ArrayList; import java.util.Collection;

Code

Collection<? extends Upload> sub_xfers = new ArrayList<Upload>(); sub_xfers = multi_upload.getSubTransfers(); do { System.out.println("\nSubtransfer progress:\n"); for (Upload u : sub_xfers) { System.out.println(" " + u.getDescription()); if (u.isDone()) { TransferState xfer_state = u.getState(); System.out.println(" " + xfer_state); } else { TransferProgress progress = u.getProgress(); double pct = progress.getPercentTransferred(); printProgressBar(pct); System.out.println(); } } // wait a bit before the next update. try { Thread.sleep(200); } catch (InterruptedException e) { return; } } while (multi_upload.isDone() == false); // print the final state of the transfer. TransferState xfer_state = multi_upload.getState(); System.out.println("\nMultipleFileUpload " + xfer_state);

GitHub で完全な例をご覧ください。

詳細