使用 Amazon S3 傳輸管理員傳輸檔案和目錄 - AWS SDK for Java 2.x
開始使用上傳檔案下載檔案複製物件上傳目錄下載至目錄查看完整範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Amazon S3 傳輸管理員傳輸檔案和目錄

Amazon S3 傳輸管理器是一個開放原始碼、高階檔案傳輸公用程式，適用於 AWS SDK for Java 2.x. 使用它來在 Amazon Simple Storage Service (Amazon S3) 之間傳輸檔案和目錄。

當 S3 用戶端建置在AWS CRT基礎上時，S3 Transfer Manager 可以利用效能改進，例如多部分上傳API和位元組範圍擷取。

使用 S3 傳輸管理器，您還可以實時監控傳輸進度，並暫停轉移以備以後執行。

開始使用

將依賴項添加到構建文件

若要以 S3 用戶端 AWS CRT為基礎的增強效能使用 S3 Transfer Manager，請使用下列相依性設定您的建置檔案。

  • 使用版本 2.19.1 或更高版本SDK的 Java 2.x。

  • 將成s3-transfer-manager品新增為相依性。

  • 在版本中將aws-crt成品添加為依賴項 0.20.3 或更高。

下列程式碼範例會示範如何設定 Maven 的專案相依性。

<project>
   <properties>
     <aws.sdk.version>2.19.1</aws.sdk.version>
  </properties>  
  <dependencyManagement>
   <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>${aws.sdk.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
   </dependencies>
  </dependencyManagement>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>s3-transfer-manager</artifactId>
   </dependency>
   <dependency>
      <groupId>software.amazon.awssdk.crt</groupId>
      <artifactId>aws-crt</artifactId>
      <version>0.20.3</version>
   </dependency>
  </dependencies>
</project>

搜索 Maven 中央存儲庫中的 S3 傳輸管理器和 aws-crt 工件的最新版本。

建立 S3 傳輸管理程式的執行個體

下列程式碼片段說明如何使用預設設定建立 S3 TransferManager 執行個體。

        S3TransferManager transferManager = S3TransferManager.create();

下列範例顯示如何使用自訂設定來設定 S3 傳輸管理員。在此範例中，S3 AsyncClient 執行個AWS CRT體會用作 S3 傳輸管理員的基礎用戶端。

        S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
                .credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.US_EAST_1)
                .targetThroughputInGbps(20.0)
                .minimumPartSizeInBytes(8 * MB)
                .build();

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

如果建置檔案中未包含aws-crt相依性，S3 傳輸管理員會建立在 Java 2.x 中使用的標準 S3 非同步用戶端之上。SDK

將檔案上傳到 S3 儲存貯體

下列範例會顯示檔案上傳範例，以及 a 的選擇性使用方式 LoggingTransferListener，以記錄上傳進度。

若要使用 S3 傳輸管理員將檔案上傳到 Amazon S3，請將UploadFileRequest物件傳遞至S3TransferManager的uploadFile方法。

從uploadFile方法傳回的FileUpload物件代表上載程序。請求完成後，CompletedFileUpload物件會包含有關上載的資訊。

    public String uploadFile(S3TransferManager transferManager, String bucketName,
                             String key, URI filePathURI) {
        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
            .putObjectRequest(b -> b.bucket(bucketName).key(key))
            .source(Paths.get(filePathURI))
            .build();

        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);

        CompletedFileUpload uploadResult = fileUpload.completionFuture().join();
        return uploadResult.response().eTag();
    }

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 儲存貯體下載檔案

下列範例會顯示下載範例，以及 a 的選擇性使用方式 LoggingTransferListener，以記錄下載進度。

若要使用 S3 傳輸管理員從 S3 儲存貯體下載物件，請建立DownloadFileRequest物件並將其傳遞給該downloadFile方法。

S3TransferManager的downloadFile方法傳回的FileDownload物件代表檔案傳輸。下載完成後，會CompletedFileDownload包含下載相關資訊的存取權。

    public Long downloadFile(S3TransferManager transferManager, String bucketName,
                             String key, String downloadedFileWithPath) {
        DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
                .getObjectRequest(b -> b.bucket(bucketName).key(key))
                .destination(Paths.get(downloadedFileWithPath))
                .build();

        FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);

        CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
        logger.info("Content length [{}]", downloadResult.response().contentLength());
        return downloadResult.response().contentLength();
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
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.Path;
import java.nio.file.Paths;
import java.util.UUID;

將 Amazon S3 對象複製到另一個存儲桶

下列範例顯示如何使用 S3 傳輸管理員複製物件。

若要開始將物件從 S3 儲存貯體複製到另一個儲存貯體，請建立基本CopyObjectRequest執行個體。

接下來，將基本包裝CopyObjectRequestCopyRequest在 S3 傳輸管理器可以使用的。

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 執行跨區域副本，請在以下程式碼片段所示的 S3 用戶端產生器crossRegionAccessEnabled上啟用。 AWS CRT

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 儲存貯體中的物件下載到本機目錄，請先呼叫傳輸管理員的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 包含此頁面上所有範例的完整程式碼。