|
com.amazonaws
aws-java-sdk-bom
>1.12.7871
pom
import
com.amazonaws
aws-java-sdk-s3
| 1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。 2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。 3[最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk.crt/aws-crt)。 ## 用戶端建構函數遷移 ### 支援的建構函數 （自動遷移） | V1 建構函數 | V2 對等 | 遷移狀態 | | --- | --- | --- | | new TransferManager() | S3TransferManager.create() | 支援 | | TransferManagerBuilder. defaultTransferManager() | S3TransferManager.create() | 支援 | | TransferManagerBuilder. standard().build() | S3TransferManager.builder().build() | 支援 | | new TransferManager(AWSCredentials) | S3TransferManager.builder() .s3Client(S3AsyncClient.builder() .credentialsProvider(...).build()) .build() | 支援 | | new TransferManager( AWSCredentialsProvider) | S3TransferManager.builder() .s3Client(S3AsyncClient.builder() .credentialsProvider(...).build()) .build() | 支援 | ### 不支援的建構函數 （需要手動遷移） | V1 建構函數 | V2 對等 | 遷移備註 | | --- | --- | --- | | new TransferManager(AmazonS3) | 需要手動遷移 | S3AsyncClient 分別建立 | | new TransferManager(AmazonS3, ExecutorService) | 需要手動遷移 | 建立 S3AsyncClient並設定執行器 | | new TransferManager(AmazonS3, ExecutorService, boolean) | 需要手動遷移 | shutDownThreadPools 不支援 參數 | ### 手動遷移範例 **V1 程式碼：** ``` AmazonS3 s3Client = AmazonS3ClientBuilder.defaultClient(); TransferManager transferManager = new TransferManager(s3Client); ``` **V2 程式碼：** ``` // Create an `S3AsyncClient` with similar configuration S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .credentialsProvider(DefaultCredentialsProvider.create()) .build(); // Provide the configured `S3AsyncClient` to the S3 transfer manager builder. S3TransferManager transferManager = S3TransferManager.builder() .s3Client(s3AsyncClient) .build(); ``` ## 用戶端方法遷移 目前，遷移工具支援基本 `copy`、`download`、、`upload``uploadDirectory`、`downloadDirectory`、 `resumeDownload`和 `resumeUpload`方法。 ### 核心傳輸方法 | V1 方法 | V2 方法 | 傳回類型變更 | 遷移狀態 | | --- | --- | --- | --- | | upload(String, String, File) | uploadFile(UploadFileRequest) | Upload → FileUpload | 支援 | | upload(PutObjectRequest) | upload(UploadRequest) | Upload → Upload | 支援 | | download(String, String, File) | downloadFile(DownloadFileRequest) | Download → FileDownload | 支援 | | download(GetObjectRequest, File) | downloadFile(DownloadFileRequest) | Download → FileDownload | 支援 | | copy(String, String, String, String) | copy(CopyRequest) | Copy → Copy | 支援 | | copy(CopyObjectRequest) | copy(CopyRequest) | Copy → Copy | 支援 | | uploadDirectory(String, String, File, boolean) | uploadDirectory( UploadDirectoryRequest) | MultipleFileUpload → DirectoryUpload | 支援 | | downloadDirectory(String, String, File) | downloadDirectory( DownloadDirectoryRequest) | MultipleFileDownload → DirectoryDownload | 支援 | ### 可繼續傳輸方法 | V1 方法 | V2 方法 | 遷移狀態 | | --- | --- | --- | | resumeUpload(PersistableUpload) | resumeUploadFile(ResumableFileUpload) | 支援 | | resumeDownload(PersistableDownload) | resumeDownloadFile(ResumableFileDownload) | 支援 | ### 生命週期方法 | V1 方法 | V2 方法 | 遷移狀態 | | --- | --- | --- | | shutdownNow() | close() | 支援 | | shutdownNow(boolean) | 使用 close()方法手動調整程式碼 | 不支援 | ### 不支援的 V1 用戶端方法 | V1 方法 | V2 替代方案 | 備註 | | --- | --- | --- | | abortMultipartUploads(String, Date) | 使用低階 Amazon S3 用戶端 | 不支援 | | getAmazonS3Client() | 分別儲存參考 | 不支援；v2 中沒有 getter | | getConfiguration() | 分別儲存參考 | 不支援；v2 中沒有 getter | | uploadFileList(...) | 進行多次uploadFile()呼叫 | 不支援 | | copy 具有 TransferStateChangeListener 參數的方法 | 使用 TransferListener | [請參閱手動遷移範例](#tm-unsupported-client-methods-copy) | | download 方法搭配 S3ProgressListener 參數 | 使用 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/progress/TransferListener.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/progress/TransferListener.html) | [請參閱手動遷移範例](#tm-unsupported-client-methods-download) | | `downloadDirectory` 具有 4 個或更多參數的方法 | | [請參閱手動遷移範例](#tm-unsupported-client-methods-download-dir) | | upload 方法與 ObjectMetadataProvider 參數 | 在請求中設定中繼資料 | [請參閱手動遷移範例](#tm-unsupported-client-methods-upload) | | uploadDirectory 方法與 \$1Provider 參數 | 在請求中設定標籤 | [請參閱手動遷移範例](#tm-unsupported-client-methods-uploadDirectory) | #### `copy` 具有 `TransferStateChangeListener` 參數的方法 + `copy(CopyObjectRequest copyObjectRequest, AmazonS3 srcS3, TransferStateChangeListener stateChangeListener)` + `copy(CopyObjectRequest copyObjectRequest, TransferStateChangeListener stateChangeListener)` ``` // V1 ---------------------------------------------------------------------------------------------- // Initialize source S3 client AmazonS3 s3client = AmazonS3ClientBuilder.standard() .withRegion("us-west-2") .build(); // Initialize Transfer Manager TransferManager tm = TransferManagerBuilder.standard() .withS3Client(srcS3) .build(); CopyObjectRequest copyObjectRequest = new CopyObjectRequest( "amzn-s3-demo-source-bucket", "source-key", "amzn-s3-demo-destination-bucket", "destination-key" ); TransferStateChangeListener stateChangeListener = new TransferStateChangeListener() { @Override public void transferStateChanged(Transfer transfer, TransferState state) { //Implementation of the TransferStateChangeListener } }; Copy copy = tm.copy(copyObjectRequest, srcS3, stateChangeListener); // V2 ---------------------------------------------------------------------------------------------- S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .region(Region.US_WEST_2) .build(); S3TransferManager transferManager = S3TransferManager.builder() .s3Client(s3AsyncClient) .build(); // Create transfer listener (equivalent to TransferStateChangeListener in v1) TransferListener transferListener = new TransferListener() { @Override public void transferInitiated(Context.TransferInitiated context) { //Implementation System.out.println("Transfer initiated"); } @Override public void bytesTransferred(Context.BytesTransferred context) { //Implementation System.out.println("Bytes transferred"); } @Override public void transferComplete(Context.TransferComplete context) { //Implementation System.out.println("Transfer completed!"); } @Override public void transferFailed(Context.TransferFailed context) { //Implementation System.out.println("Transfer failed"); } }; CopyRequest copyRequest = CopyRequest.builder() .copyObjectRequest(req -> req .sourceBucket("amzn-s3-demo-source-bucket") .sourceKey("source-key") .destinationBucket("amzn-s3-demo-destination-bucket") .destinationKey("destination-key") ) .addTransferListener(transferListener) // Configure the transferListener into the request .build(); Copy copy = transferManager.copy(copyRequest); ``` #### `download` 方法搭配 `S3ProgressListener` 參數 + `download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener)` + `download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener, long timeoutMillis)` + `download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener, long timeoutMillis, boolean resumeOnRetry)` ``` // V1 ---------------------------------------------------------------------------------------------- S3ProgressListener progressListener = new S3ProgressListener() { @Override public void progressChanged(com.amazonaws.event.ProgressEvent progressEvent) { long bytes = progressEvent.getBytesTransferred(); ProgressEventType eventType = progressEvent.getEventType(); // Use bytes and eventType as needed } @Override public void onPersistableTransfer(PersistableTransfer persistableTransfer) { } }; Download download1 = tm.download(getObjectRequest, file, progressListener); Download download2 = tm.download(getObjectRequest, file, progressListener, timeoutMillis) Download download3 = tm.download(getObjectRequest, file, progressListener, timeoutMillis, true) // V2 ---------------------------------------------------------------------------------------------- TransferListener transferListener = new TransferListener() { @Override public void transferInitiated(Context.InitializedContext context) { // Equivalent to ProgressEventType.TRANSFER_STARTED_EVENT System.out.println("Transfer initiated"); } @Override public void bytesTransferred(Context.BytesTransferred context) { // Equivalent to ProgressEventType.REQUEST_BYTE_TRANSFER_EVENT long bytes = context.bytesTransferred(); System.out.println("Bytes transferred: " + bytes); } @Override public void transferComplete(Context.TransferComplete context) { // Equivalent to ProgressEventType.TRANSFER_COMPLETED_EVENT System.out.println("Transfer completed"); } @Override public void transferFailed(Context.TransferFailed context) { // Equivalent to ProgressEventType.TRANSFER_FAILED_EVENT System.out.println("Transfer failed: " + context.exception().getMessage()); } }; DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder() .getObjectRequest(getObjectRequest) .destination(file.toPath()) .addTransferListener(transferListener) .build(); // For download1 FileDownload download = transferManager.downloadFile(downloadFileRequest); // For download2 CompletedFileDownload completedFileDownload = download.completionFuture() .get(timeoutMillis, TimeUnit.MILLISECONDS); // For download3, the v2 SDK does not have a direct equiavalent to the `resumeOnRetry` method of v1. // If a download is interrupted, you need to start a new download request. ``` #### `downloadDirectory` 具有 4 個或更多參數的方法 + `downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, boolean resumeOnRetry)` + `downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, boolean resumeOnRetry, KeyFilter filter)` + `downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, KeyFilter filter)` ``` // V1 ---------------------------------------------------------------------------------------------- KeyFilter filter = new KeyFilter() { @Override public boolean shouldInclude(S3ObjectSummary objectSummary) { //Filter implementation } }; MultipleFileDownload multipleFileDownload = tm.downloadDirectory(bucketName, keyPrefix, destinationDirectory, filter); // V2 ---------------------------------------------------------------------------------------------- // The v2 SDK does not have a direct equiavalent to the `resumeOnRetry` method of v1. // If a download is interrupted, you need to start a new download request. DownloadFilter filter = new DownloadFilter() { @Override public boolean test(S3Object s3Object) { // Filter implementation. } }; DownloadDirectoryRequest downloadDirectoryRequest = DownloadDirectoryRequest.builder() .bucket(bucketName) .filter(filter) .listObjectsV2RequestTransformer(builder -> builder.prefix(keyPrefix)) .destination(destinationDirectory.toPath()) .build(); DirectoryDownload directoryDownload = transferManager.downloadDirectory(downloadDirectoryRequest); ``` #### `upload` 方法與 `ObjectMetadata` 參數 + `upload(String bucketName, String key, InputStream input, ObjectMetadata objectMetadata)` ``` // V1 ----------------------------------------------------------------------------------------------ObjectMetadata metadata = new ObjectMetadata(); ObjectMetadata metadata = new ObjectMetadata(); metadata.setContentType("text/plain"); // System-defined metadata metadata.setContentLength(22L); // System-defined metadata metadata.addUserMetadata("myKey", "myValue"); // User-defined metadata PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, metadata); Upload upload = transferManager.upload("amzn-s3-demo-bucket", "my-key", inputStream, metadata); // V2 ---------------------------------------------------------------------------------------------- /* When you use an InputStream to upload in V2, you should specify the content length and use `RequestBody.fromInputStream()`. If you don't provide the content length, the entire stream will be buffered in memory. If you can't determine the content length, we recommend using the CRT-based S3 client. */ Map
software.amazon.awssdk
bom
2.31.682
pom
import
software.amazon.awssdk
s3-transfer-manager
software.amazon.awssdk.crt
aws-crt
0.38.53
TransferManagerBuilder tmBuilder =|
TransferManagerBuilder.standard();
S3TransferManager.Builder tmBuilder =| | S3 用戶端 |
S3TransferManager.builder();
tmBuilder.withS3Client(...);|
tmBuilder.setS3Client(...);
tmBuilder.s3Client(...);| | 執行器 |
tmBuilder.withExecutorFactory(...);|
tmBuilder.setExecutorFactory(...);
tmBuilder.executor(...);| | 關閉執行緒集區 |
tmBuilder.withShutDownThreadPools(...);| 不支援。關閉 時，不會關閉提供的執行器 S3TransferManager | | 最小上傳部分大小 |
tmBuilder.setShutdownThreadPools(...);
tmBuilder.withMinimumUploadPartSize(...);|
tmBuilder.setMinimumUploadPartSize(...);
S3AsyncClient s3 = S3AsyncClient.crtBuilder().| | 分段上傳閾值 |
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartUploadThreshold(...);|
tmBuilder.setMultipartUploadThreshold(...);
S3AsyncClient s3 = S3AsyncClient.crtBuilder().| | 最小複製部分大小 |
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartCopyPartSize(...);|
tmBuilder.setMultipartCopyPartSize(...);
S3AsyncClient s3 = S3AsyncClient.crtBuilder().| | 分段複製閾值 |
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartCopyThreshold(...);|
tmBuilder.setMultipartCopyThreshold(...);
S3AsyncClient s3 = S3AsyncClient.crtBuilder().| | 停用平行下載 |
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
tmBuilder.withDisableParallelDownloads(...);| 將停用分段 （預設） 的標準 Java 型 S3 用戶端傳遞給傳輸管理員，以停用平行下載。
tmBuilder.setDisableParallelDownloads(...);
S3AsyncClient s3 =| | 一律計算分段 md5 |
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
tmBuilder.withAlwaysCalculateMultipartMd5(...);| 不支援。 | ------ #### [ Use Java-based S3 async client ] **** | 設定 | v1 | v2 - 使用 Java 型 S3 非同步用戶端的 Transfer Manager | | --- | --- | --- | | （取得建置器） |
tmBuilder.setAlwaysCalculateMultipartMd5(...);
TransferManagerBuilder tmBuilder =|
TransferManagerBuilder.standard();
S3TransferManager.Builder tmBuilder =| | S3 用戶端 |
S3TransferManager.builder();
tmBuilder.withS3Client(...);|
tmBuilder.setS3Client(...);
tmBuilder.s3Client(...);| | 執行器 |
tmBuilder.withExecutorFactory(...);|
tmBuilder.setExecutorFactory(...);
tmBuilder.executor(...);| | 關閉執行緒集區 |
tmBuilder.withShutDownThreadPools(...);| 不支援。關閉 時，不會關閉提供的執行器 S3TransferManager | | 最小上傳部分大小 |
tmBuilder.setShutdownThreadPools(...);
tmBuilder.withMinimumUploadPartSize(...);|
tmBuilder.setMinimumUploadPartSize(...);
S3AsyncClient s3 = S3AsyncClient.builder()| | 分段上傳閾值 |
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartUploadThreshold(...);|
tmBuilder.setMultipartUploadThreshold(...);
S3AsyncClient s3 = S3AsyncClient.builder()| | 最小複製部分大小 |
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartCopyPartSize(...);|
tmBuilder.setMultipartCopyPartSize(...);
S3AsyncClient s3 = S3AsyncClient.builder()| | 分段複製閾值 |
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
tmBuilder.withMultipartCopyThreshold(...);|
tmBuilder.setMultipartCopyThreshold(...);
S3AsyncClient s3 = S3AsyncClient.builder()| | 停用平行下載 |
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
tmBuilder.withDisableParallelDownloads(...);| 將停用分段 （預設） 的標準 Java 型 S3 用戶端傳遞至傳輸管理員，以停用平行下載。
tmBuilder.setDisableParallelDownloads(...);
S3AsyncClient s3 =| | 一律計算分段 md5 |
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
tmBuilder.withAlwaysCalculateMultipartMd5(...);| 不支援。 | ------ ## 行為變更 ### 非同步操作 **V1 （封鎖）：** ``` Upload upload = transferManager.upload("amzn-s3-demo-bucket", "key", file); upload.waitForCompletion(); // Blocks until complete ``` **V2 （非同步）：** ``` FileUpload upload = transferManager.uploadFile(UploadFileRequest.builder() .putObjectRequest(PutObjectRequest.builder() .bucket("amzn-s3-demo-bucket") .key("key") .build()) .source(file) .build()); CompletedFileUpload result = upload.completionFuture().join(); // Blocks until complete // Or handle asynchronously: upload.completionFuture().thenAccept(result -> { System.out.println("Upload completed: " + result.response().eTag()); }); ``` ### 錯誤處理 **V1：**如果任何子請求失敗，目錄傳輸會完全失敗。 **V2：**即使某些子請求失敗，目錄傳輸也會成功完成。明確檢查錯誤： ``` DirectoryUpload directoryUpload = transferManager.uploadDirectory(request); CompletedDirectoryUpload result = directoryUpload.completionFuture().join(); // Check for failed transfers if (!result.failedTransfers().isEmpty()) { System.out.println("Some uploads failed:"); result.failedTransfers().forEach(failed -> System.out.println("Failed: " + failed.exception().getMessage())); } ``` ### 透過位元組範圍擷取平行下載 在 v2 SDK 中啟用自動平行傳輸功能時，S3 Transfer Manager 會使用[位元組範圍擷取](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance-guidelines.html#optimizing-performance-guidelines-get-range)來平行擷取物件的特定部分 （分段下載）。使用 v2 下載物件的方式，不取決於最初上傳物件的方式。所有下載都可以受益於高輸送量和並行。 相反地，與 v1 的 Transfer Manager 相比，最初上傳物件的方式並不重要。v1 Transfer Manager 擷取物件組件的方式與上傳組件的方式相同。如果物件最初是以單一物件上傳，v1 Transfer Manager 就無法使用子請求加速下載程序。
tmBuilder.setAlwaysCalculateMultipartMd5(...);