使用 TransferManager 進行 Amazon S3 操作

您可以使用 AWS SDK for Java TransferManager 類別，可靠地將檔案從本機環境傳輸到另一個 S3 位置 Amazon S3 ，以及將物件複製到另一個位置。 TransferManager可以取得傳輸進度，並暫停或繼續上傳和下載。

注意

最佳實務

建議您在 Amazon S3 儲存貯體上啟用 AbortIncompleteMultipartUpload 生命週期規則。

此規則 Amazon S3 會指示中止在啟動後指定天數內未完成的分段上傳。超過設定的時間限制時，會 Amazon S3 中止上傳，然後刪除不完整的上傳資料。

如需詳細資訊，請參閱 Amazon S3 《使用者指南》中的使用版本控制的儲存貯體生命週期組態。

注意

這些程式碼範例假設您了解使用 AWS SDK for Java 中的資料，並使用設定 AWS 登入資料和開發區域中的資訊來設定預設 AWS 登入資料。

上傳檔案和目錄

TransferManager 可以將檔案、檔案清單和目錄上傳至您先前建立的任何儲存 Amazon S3 貯體。

上傳單一檔案

呼叫 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 物件以用來檢查傳輸狀態或等待它完成。

請參閱等待轉接完成，以取得在呼叫 TransferManager 的 shutdownNow方法之前waitForCompletion，使用成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱取得傳輸狀態和進度。

請參閱 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();

傳回的 MultipleFileUpload 物件uploadFileList可用來查詢傳輸狀態或進度。如需詳細資訊，請參閱使用 ProgressListener 輪詢傳輸的目前進度和取得傳輸進度。 ProgressListener

您也可以使用 MultipleFileUpload的 getSubTransfers方法，取得每個要傳輸檔案的個別Upload物件。如需詳細資訊，請參閱取得子轉移進度。

請參閱 GitHub 上的完整範例。

上傳目錄

您可以使用 TransferManager 的 uploadDirectory方法上傳整個檔案目錄，並可選擇以遞迴方式複製子目錄中的檔案。您提供儲存 Amazon S3 貯體名稱、S3 金鑰字首、代表要複製之本機目錄的檔案物件，以及指出是否要以遞迴方式 (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;

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();

您也可以使用 MultipleFileUpload的 getSubTransfers方法，取得每個要傳輸檔案的個別Upload物件。如需詳細資訊，請參閱取得子轉移進度。

請參閱 GitHub 上的完整範例。

下載檔案或目錄

使用 TransferManager 類別從中下載單一檔案 (Amazon S3 物件）或目錄 ( Amazon S3 儲存貯體名稱後接物件字首） Amazon S3。

主題

下載單一檔案
下載目錄

下載單一檔案

使用 TransferManager 的 download方法，提供儲存 Amazon S3 貯體名稱，其中包含您要下載的物件、金鑰（物件）名稱，以及代表要在本機系統上建立之檔案的檔案https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html物件。

匯入


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();

請參閱 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方法傳回的每個類別都會傳回下列其中一個類別的執行個體，視其為單一檔案或多檔案操作而定。


類別	傳回者
Copy (複製)	`copy`
下載	`download`
MultipleFileDownload	`downloadDirectory`
上傳	`upload`
MultipleFileUpload	`uploadFileList`, `uploadDirectory`

所有這些類別都會實作 Transfer 界面。 Transfer提供實用方法來取得傳輸進度、暫停或繼續傳輸，以及取得傳輸的目前或最終狀態。

主題

輪詢傳輸的目前進度
使用 ProgressListener 取得傳輸進度
取得子轉移進度

輪詢傳輸的目前進度

此迴圈會列印傳輸的進度、在執行時檢查其目前的進度，並在完成時列印其最終狀態。

匯入


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 上的完整範例。

詳細資訊

Amazon Simple Storage Service 《使用者指南》中的物件金鑰

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取

將 Amazon S3 儲存貯體設定為網站