Amazon S3 傳輸管理器從版本 1 更改為版本 2 - AWS SDK for Java 2.x
高階變更設定 API 變更行為改變

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

Amazon S3 傳輸管理器從版本 1 更改為版本 2

本主題詳述 Amazon S3 傳輸管理員從版本 1 (v1) 到第 2 版 (v2) 的變更。

高階變更

變更 v1 v2

Maven 的依賴

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.5871</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-s3</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.21.212</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.28.73</version>
    </dependency>
</dependencies>
套件名稱 com.amazonaws.services.s3.transfer software.amazon.awssdk.transfer.s3
類別名稱

TransferManager

S3TransferManager

1 最新版本。 2 最新版本。 3 最新版本。

設定 API 變更

設定 v1 v2

（獲得建設者）

 
TransferManagerBuilder tmBuilder = 
   TransferManagerBuilder.standard();
 
S3TransferManager.Builder tmBuilder  = 
  S3TransferManager.builder();

S3 客戶端

 
tmBuilder.withS3Client(...);
tmBuilder.setS3Client(...);
 
tmBuilder.s3Client(...);

遺囑執行人

 
tmBuilder.withExecutorFactory(...);
tmBuilder.setExecutorFactory(...);
 
tmBuilder.executor(...);

關閉執行緒集區

 
tmBuilder.withShutDownThreadPools(...);
tmBuilder.setShutdownThreadPools(...);
 不支援。S3 TransferManager 關閉時，提供的執行人不會關閉

最小上傳零件大小

 
tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
 
S3AsyncClient s3 =
   S3AsyncClient.crtBuilder().
      minimumPartSizeInBytes(...).build();

tmBuilder.s3Client(s3);

分段上傳閾值

 
tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
 
S3AsyncClient s3 =
   S3AsyncClient.crtBuilder().
      thresholdInBytes(...).build();

tmBuilder.s3Client(s3);

最小複製零件大小

 
tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
 
S3AsyncClient s3 =
   S3AsyncClient.crtBuilder().
      minimumPartSizeInBytes(...).build();

tmBuilder.s3Client(s3);

多部分複製閾值

 
tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
 
S3AsyncClient s3 =
   S3AsyncClient.crtBuilder().
      thresholdInBytes(...).build();

tmBuilder.s3Client(s3);

停用 parallel 下載

 
tmBuilder.withDisableParallelDownloads(...);
tmBuilder.setDisableParallelDownloads(...);
 將標準 Java 型 S3 用戶端傳送至傳輸管理員，以停用 parallel 下載。
S3AsyncClient s3 =
   S3AsyncClient.builder().build();

tmBuilder.s3Client(s3);

總是計算多部分 md5

 
tmBuilder.withAlwaysCalculateMultipartMd5(...);
tmBuilder.setAlwaysCalculateMultipartMd5(...);
 不支援。

行為改變

並行傳輸需要 AWS 基於 CRT 的 S3 客戶端

在適用於 Java 2.x 的 SDK 中，可透過 CRT 型 S3 用戶端使用自動 parallel 傳輸功能 (多部分上傳/下載)。AWS若要啟用 parallel 傳輸功能，您必須明確新增「一AWS 般執行階段」(CRT) 程式庫相依性，才能發揮最大效能。

單獨使用 AWS CRT 型 S3 用戶端可S3TransferManager提供最大的 parallel 傳輸效能。 S3TransferManagerv2 提供了額外的 API，使其更容易傳輸文件和目錄。

執行 parallel 傳輸的S3TransferManager能力取決於起始方式，以及S3TransferManager是否已宣告為相依性的「 AWS 共用執行階段」(CRT) 程式庫。

下表說明具有和不具有 AWS CRT 宣告為相依性之 S3TransferManager v2 的三種初始化案例。

S3 TransferManager v2 初始化方法 AWS CRT 是否聲明為依賴關係？
是 否

初始化S3TransferManager而不傳遞實S3AsyncClient例

靜態創建方法：

S3TransferManager.create();

- 或 -

生成器方法：

S3TransferManager.builder().build();
綠色核取記號表示已啟用自動 parallel 傳輸。

啟用自動 parallel 傳輸
紅色 X 表示自動 parallel 傳輸已停用。

自動 parallel 傳輸已停用

傳遞使用 crt* () 構建器方法之一構建的S3AsyncClient實例

S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder().build();
S3TransferManager.builder().s3AsyncClient(s3AsyncClient).build();

- 或 -

S3AsyncClient s3AsyncClient = S3AsyncClient.crtCreate();
S3TransferManager.builder().s3AsyncClient(s3AsyncClient).build();
綠色核取記號表示已啟用自動 parallel 傳輸。

啟用自動 parallel 傳輸
紅色 X 表示自動 parallel 傳輸已停用。

運行時錯誤

傳遞使用其中一個標準構建器方法構建的S3AsyncClient實例，以便傳輸管理器沒有引用 CRT

S3AsyncClient s3AsyncClient = S3AsyncClient.builder().build();
S3TransferManager.builder().s3AsyncClient(s3AsyncClient).build();

- 或 -

S3AsyncClient s3AsyncClient = S3AsyncClient.create();
S3TransferManager.builder().s3AsyncClient(s3AsyncClient).build();
紅色 X 表示自動 parallel 傳輸已停用。

自動 parallel 傳輸已停用
紅色 X 表示自動 parallel 傳輸已停用。

自動 parallel 傳輸已停用

通過字節範圍獲取並行下載

啟用自動 parallel 傳輸功能時，S3 Transfer Manager v2 會使用位元組範圍擷取，以 parallel 方式擷取物件的特定部分 (多部分下載)。使用 v2 下載對象的方式不取決於最初上傳對象的方式。所有下載都可以受益於高吞吐量和並發性。

相反地，使用 S3 傳輸管理員 v1，物件最初上傳的方式確實很重要。S3 傳輸管理員 v1 會以上傳零件的相同方式擷取物件的各個部分。如果物件原本是以單一物件的形式上傳，則 S3 Transfer Manager v1 無法使用子要求加速下載程序。

失敗行為

使用 S3 傳輸管理員 v1 時，如果有任何子請求失敗，目錄傳輸請求就會失敗。與 v1 不同，即使某些子請求失敗，從 S3 傳輸管理器 v2 返回的 future 也會成功完成。

因此，即使 future 成功完成，您也應該使用CompletedDirectoryDownload.failedTransfers()方法或方CompletedDirectoryUpload.failedTransfers()法來檢查響應中的錯誤。