View a markdown version of this page

將預先簽章的 URL 下載從 適用於 Java 的 AWS SDK v1 遷移至 v2 - AWS SDK for Java 2.x
高階變更相依性、套件和類別名稱的變更API 變更組態變更

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

將預先簽章的 URL 下載從 適用於 Java 的 AWS SDK v1 遷移至 v2

遷移預先簽章的 URL 下載程式碼，以使用非同步處理並存取第 2 版中擴展的下載選項。本主題說明如何從 1.x 版 (v1) 遷移至 的 2.x 版 (v2) 適用於 Java 的 AWS SDK。如需 v2 預先簽章 URL 下載功能的詳細資訊，請參閱 使用 Amazon S3 預先簽章URLs。

高階變更

下列清單摘要說明 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 相依性

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.7971</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.48.02</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
    </dependency>
    <!-- Optional: for Transfer Manager -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3-transfer-manager</artifactId>
    </dependency>
</dependencies>
套件名稱 com.amazonaws.services.s3 software.amazon.awssdk.services.s3
類別名稱 AmazonS3, TransferManager S3AsyncClient, S3TransferManager

1 Maven Central 網站上的最新版本。 2 Maven Central 網站上的最新版本。

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<GetObjectResponse> 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 下載。

組態變更

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