本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將預先簽章的 URL 下載從適用於 Java 的 AWS SDK v1 遷移至 v2 遷移預先簽章的 URL 下載程式碼，以使用非同步處理並存取第 2 版中擴展的下載選項。本主題說明如何從 1.x 版 (v1) 遷移至的 2.x 版 (v2) 適用於 Java 的 AWS SDK。如需 v2 預先簽章 URL 下載功能的詳細資訊，請參閱 [使用 Amazon S3 預先簽章URLs](examples-s3-presign.md)。 ## 高階變更下列清單摘要說明 v1 和 v2 之間預先簽章 URL 下載的主要差異： + **套件**：`com.amazonaws.services.s3`→ `software.amazon.awssdk.services.s3`。 + **用戶端類別**： `AmazonS3` （同步） → `S3AsyncClient`（非同步）。 + **架構**：同步封鎖呼叫 → 使用進行非同步呼叫`CompletableFuture`。 + **分段**：僅透過 Transfer Manager 提供 → 可直接在用戶端上使用 `multipartEnabled(true)`。 + **Transfer Manager**：僅限檔案目的地 → 檔案、位元組或自訂轉換器。 ## 相依性、套件和類別名稱的變更下表顯示相依性和類別名稱從 v1 變更為 v2。 | 變更 | v1 | v2 | | --- | --- | --- | | Maven 相依性 |


    
        
            com.amazonaws
            aws-java-sdk-bom
            {{1.12.7971}}
            pom
            import
        
    


    
        com.amazonaws
        aws-java-sdk-s3


    
        
            software.amazon.awssdk
            bom
            {{2.48.02}}
            pom
            import
        
    


    
        software.amazon.awssdk
        s3
    
    
    
        software.amazon.awssdk
        s3-transfer-manager

| | 套件名稱 | com.amazonaws.services.s3 | software.amazon.awssdk.services.s3 | | 類別名稱 | AmazonS3, TransferManager | S3AsyncClient, S3TransferManager | 1 Maven Central 網站上的[最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。 2 Maven Central 網站上的[最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。 ## API 變更 ### S3 用戶端下載下表比較 S3 用戶端下載的 v1 和 v2 API 呼叫。 | 使用案例 | v1 | v2 | | --- | --- | --- | | 建立用戶端 |

AmazonS3 s3Client = 
        AmazonS3ClientBuilder.defaultClient();

S3AsyncClient s3AsyncClient = 
        S3AsyncClient.create();
AsyncPresignedUrlExtension extension = 
        s3AsyncClient.presignedUrlExtension();

| | 產生預先簽章的 URL |

Date expiration = new Date(
        System.currentTimeMillis() + 600_000);
URL presignedUrl = s3Client.generatePresignedUrl(
        new GeneratePresignedUrlRequest(
            "my-bucket", "my-key")
            .withMethod(HttpMethod.GET)
            .withExpiration(expiration));

S3Presigner presigner = S3Presigner.create();
PresignedGetObjectRequest presigned = 
        presigner.presignGetObject(r -> r
            .getObjectRequest(req -> req
                .bucket("my-bucket").key("my-key"))
            .signatureDuration(Duration.ofMinutes(10)));
URL presignedUrl = presigned.url();
presigner.close();

| | 建立下載請求 |

PresignedUrlDownloadRequest downloadRequest = 
        new PresignedUrlDownloadRequest(presignedUrl);

PresignedUrlDownloadRequest downloadRequest = 
        PresignedUrlDownloadRequest.builder()
            .presignedUrl(presignedUrl)
            .build();

| | 下載以串流 |

PresignedUrlDownloadResult result = 
        s3Client.download(downloadRequest);
InputStream content = result.getS3Object()
        .getObjectContent();

ResponseBytes bytes = 
        extension.getObject(downloadRequest,
            AsyncResponseTransformer.toBytes())
        .join();

| | 下載至檔案 |

s3Client.download(downloadRequest,
        new File("/tmp/file.bin"));

extension.getObject(downloadRequest,
            Paths.get("/tmp/file.bin"))
        .join();

| | 使用範圍下載 |

PresignedUrlDownloadRequest rangeRequest = 
        new PresignedUrlDownloadRequest(presignedUrl);
rangeRequest.setRange(0, 1023);
s3Client.download(rangeRequest);

PresignedUrlDownloadRequest rangeRequest = 
        PresignedUrlDownloadRequest.builder()
            .presignedUrl(presignedUrl)
            .range("bytes=0-1023")
            .build();
extension.getObject(rangeRequest,
            Paths.get("/tmp/partial.bin"))
        .join();

| ### Transfer Manager 下載下表比較 Transfer Manager 下載的 v1 和 v2 API 呼叫。 | 使用案例 | v1 | v2 | | --- | --- | --- | | 建立 Transfer Manager |

TransferManager tm = 
        TransferManagerBuilder.standard().build();

S3TransferManager tm = 
        S3TransferManager.create();

| | 下載 |

PresignedUrlDownload download = tm.download(
        new PresignedUrlDownloadRequest(presignedUrl),
        new File("/tmp/file.bin"));
download.waitForCompletion();

PresignedFileDownload download = 
        tm.downloadFileWithPresignedUrl(
            PresignedDownloadFileRequest.builder()
                .presignedUrlDownloadRequest(
                    downloadRequest)
                .destination(Paths.get("/tmp/file.bin"))
                .addTransferListener(
                    LoggingTransferListener.create())
                .build());
download.completionFuture().join();

| 如需詳細資訊，請參閱[使用預先簽章的 URL 下載](transfer-manager.md#transfer-manager-presigned-url-download)。 ## 組態變更 ### S3 用戶端下表說明從 v1 到 v2 的 S3 用戶端組態變更。 | 設定 | v1 | v2 | | --- | --- | --- | | 分段組態 | PresignedUrlDownloadConfig.withDownloadSizePerRequest(long) | S3AsyncClient.builder().multipartConfiguration(c -> c.minimumPartSizeInBytes(...)) | | 自訂標頭 | PresignedUrlDownloadRequest.putCustomRequestHeader(String, String) | 不支援。只有 Range和 If-Match可以在下載時設定。 | ### Transfer Manager 下表說明 Transfer Manager 組態從 v1 變更為 v2。 | 設定 | v1 | v2 | | --- | --- | --- | | 進度追蹤 | PresignedUrlDownloadConfig.withS3progressListener(...) | PresignedDownloadFileRequest.builder().addTransferListener(...) | | 重試時繼續 | PresignedUrlDownloadConfig.withResumeOnRetry(true) | 不支援 | | 暫停/繼續 | 不支援 | 不支援 | **注意** AWS CRT 型 S3 用戶端 (`S3AsyncClient.crtBuilder()`) 目前不支援預先簽章的 URL 延伸。請使用 `S3AsyncClient.builder()`。