使用 TransferManager 执行 Amazon S3 操作 - AWS SDK for Java 1.x
上传文件和目录下载文件或目录复制对象请等待传输完成。获取传输状态和进度更多信息

自2024年7月31日起， AWS SDK for Java 1.x已进入维护模式，并将于2025年12月31日end-of-support上线。我们建议您迁移到AWS SDK for Java 2.x以继续接收新功能、可用性改进和安全更新。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 TransferManager 执行 Amazon S3 操作

您可以使用 AWS SDK for Java TransferManager 类可靠地将文件从本地环境传输到 Amazon S3 并将对象从一个 S3 位置复制到另一个 S3 位置。TransferManager 可获取传输进度，以及暂停或恢复上传和下载。

注意

最佳实践

建议您对 存储桶启用 AbortIncompleteMultipartUploadAmazon S3 生命周期规则。

该规则指示 Amazon S3 中止在启动后没有在指定天数内完成的分段上传。当超过设置的时间限制时，Amazon S3 将中止上传，然后删除未完成的上传数据。

有关更多信息，请参阅《Amazon S3 用户指南》中的使用版本控制的桶生命周期配置。

注意

这些代码示例假定您了解使用AWS SDK for Java 中的内容，并且已使用设置用于开发的 AWS 凭证和区域中的信息配置默认 AWS 凭证。

上传文件和目录

TransferManager 可将文件、文件列表和目录上传到您之前创建的任何 Amazon S3 桶。

上传单个文件

调用 TransferManager 的 upload 方法，提供 Amazon S3 桶名称、键（对象）名称和代表要上传的文件的标准 Java File 对象。

导入 

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 对象，用于检查传输状态或等待传输完成。

请参阅等待传输完成以了解有关在调用 TransferManager 的 shutdownNow 方法之前使用 waitForCompletion 成功完成传输的信息。在等待传输完成时，您可以轮询或侦听有关其状态和进度的更新。有关更多信息，请参阅获取传输状态和进度。

请参阅 GitHub 上的完整示例。

上传文件列表

要通过一次操作上传多个文件，请调用 TransferManager uploadFileList 方法，并为其提供：

  • Amazon S3 存储桶名称

  • 一个键前缀，它将添加到创建的对象名称的前面 (将对象放置到的存储桶中的路径)

  • 一个 File 对象，此对象表示将从中创建文件路径的相对目录

  • 一个 List 对象，包含一组要上传的 File 对象

导入 

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

请参阅等待传输完成以了解有关在调用 TransferManager 的 shutdownNow 方法之前使用 waitForCompletion 成功完成传输的信息。在等待传输完成时，您可以轮询或侦听有关其状态和进度的更新。有关更多信息，请参阅获取传输状态和进度。

可使用由 uploadFileList 返回的 MultipleFileUpload 对象来查询传输状态或进度。有关更多信息，请参阅轮询传输的当前进度和使用 ProgressListener 获取传输进度。

您也可以使用 MultipleFileUpload 的 getSubTransfers 方法为要传输的每个文件获取单个 Upload 对象。有关更多信息，请参阅获取子传输的进度。

请参阅 GitHub 上的完整示例。

上传目录

可使用 TransferManager 的 uploadDirectory 方法通过用于以递归方式复制子目录中的文件的选项来上传整个文件目录。您提供一个 Amazon S3 存储桶名称、一个 S3 键前缀、一个表示要复制的本地目录的 File 对象和一个 boolean 值，该值指示您是否需要以递归方式复制子目录（true 或 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;

代码 

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

请参阅等待传输完成以了解有关在调用 TransferManager 的 shutdownNow 方法之前使用 waitForCompletion 成功完成传输的信息。在等待传输完成时，您可以轮询或侦听有关其状态和进度的更新。有关更多信息，请参阅获取传输状态和进度。

可使用由 uploadFileList 返回的 MultipleFileUpload 对象来查询传输状态或进度。有关更多信息，请参阅轮询传输的当前进度和使用 ProgressListener 获取传输进度。

您也可以使用 MultipleFileUpload 的 getSubTransfers 方法为要传输的每个文件获取单个 Upload 对象。有关更多信息，请参阅获取子传输的进度。

请参阅 GitHub 上的完整示例。

下载文件或目录

使用 TransferManager 类从 Amazon S3 下载单个文件（Amazon S3 对象）或目录（一个 Amazon S3 桶名称，后跟对象前缀）。

下载单个文件

使用 TransferManager 的 download 方法，并为其提供包含要下载的对象的 Amazon S3 桶名称、键（对象）名称和一个 File 对象（该对象表示要在本地系统上创建的文件）。

导入 

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

请参阅等待传输完成以了解有关在调用 TransferManager 的 shutdownNow 方法之前使用 waitForCompletion 成功完成传输的信息。在等待传输完成时，您可以轮询或侦听有关其状态和进度的更新。有关更多信息，请参阅获取传输状态和进度。

请参阅 GitHub 上的完整示例。

下载目录

要从 Amazon S3 下载一组共享一个公共键前缀的文件（类似于文件系统上的目录），可使用 TransferManager downloadDirectory 方法。该方法需要包含要下载的对象的 Amazon S3 存储桶名称、所有对象共享的对象前缀和一个 File 对象（此对象表示要将文件下载到的本地系统目录）。如果指定目录尚不存在，将创建此目录。

导入 

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

请参阅等待传输完成以了解有关在调用 TransferManager 的 shutdownNow 方法之前使用 waitForCompletion 成功完成传输的信息。在等待传输完成时，您可以轮询或侦听有关其状态和进度的更新。有关更多信息，请参阅获取传输状态和进度。

请参阅 GitHub 上的完整示例。

复制对象

要将对象从一个 S3 桶复制到另一个 S3 桶，可使用 TransferManager copy 方法。

导入 

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

获取传输状态和进度

TransferManager upload*、download* 和 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;

代码 

// 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 方法来返回有关其子传输的信息。它将返回 Upload 对象的不可修改的 Collection，并单独提供每个子传输的传输状态和进度。

导入 

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

更多信息

  • 《Amazon Simple Storage Service 用户指南》中的对象键