Amazon S3 オペレーションでの TransferManager の使用 - AWS SDK for Java

Amazon S3 オペレーションでの TransferManager の使用

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

注記

ベストプラクティス

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

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

詳細については、Amazon S3 User Guide の「バージョニングが有効なバケットのライフサイクル設定」を参照してください。

注記

これらのコード例では、ユーザーが「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;

コード

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;

コード

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 オブジェクト、およびサブディレクトリに再帰的にコピーするかどうか (true または false) を示す boolean 値を渡します。

インポート

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;

コード

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;

コード

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;

コード

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;

コード

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 つのファイルまたは複数のファイルのオペレーションであるかどうかに応じて、以下のクラスのいずれかのインスタンスを返します。

クラス 返すクラス

コピー

copy

ダウンロード

download

MultipleFileDownload

downloadDirectory

アップロード

upload

MultipleFileUpload

uploadFileListuploadDirectory

これらすべてのクラスは、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;

コード

// 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;

コード

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;

コード

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 で完全な例をご覧ください。

詳細