기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# v1에서 AWS SDK for Java v2로 미리 서명된 URL 다운로드 마이그레이션
<a name="migration-s3-presign-download"></a>

미리 서명된 URL 다운로드 코드를 마이그레이션하여 비동기 처리를 사용하고 버전 2의 확장된 다운로드 옵션에 액세스합니다. 이 주제에서는 버전 1.x(v1)에서 버전 2.x(v2)로 마이그레이션하는 방법을 보여줍니다 AWS SDK for Java. v2 미리 서명된 URL 다운로드 기능에 대한 자세한 내용은 섹션을 참조하세요[Amazon S3 미리 서명된 URLs 작업](examples-s3-presign.md).

## 높은 수준의 변경 사항
<a name="migration-s3-presign-high-level"></a>

다음 목록에는 미리 서명된 URL 다운로드에 대한 v1과 v2의 주요 차이점이 요약되어 있습니다.
+ **패키지**: `com.amazonaws.services.s3` → `software.amazon.awssdk.services.s3`.
+ **클라이언트 클래스**: `AmazonS3` (동기식) → `S3AsyncClient` (비동기식).
+ **아키텍처**: 동기식 차단 호출 →를 사용한 비동기식 호출`CompletableFuture`.
+ **멀티파트**: Transfer Manager를 통해서만 사용 가능 →를 사용하는 클라이언트에서 직접 사용 가능`multipartEnabled(true)`.
+ **Transfer Manager**: 파일 대상만 → 파일, 바이트 또는 사용자 지정 변환기.

## 종속성, 패키지 및 클래스 이름의 변경 사항
<a name="migration-s3-presign-deps"></a>

다음 표에는 v1에서 v2로 변경된 종속성 및 클래스 이름이 나와 있습니다.


| 변경 | v1 |  v2 | 
| --- | --- | --- | 
| Maven 종속성 |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>com.amazonaws</groupId><br />            <artifactId>aws-java-sdk-bom</artifactId><br />            <version>{{1.12.7971}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>com.amazonaws</groupId><br />        <artifactId>aws-java-sdk-s3</artifactId><br />    </dependency><br /></dependencies></pre>  |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>software.amazon.awssdk</groupId><br />            <artifactId>bom</artifactId><br />            <version>{{2.48.02}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>s3</artifactId><br />    </dependency><br />    <!-- Optional: for Transfer Manager --><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>s3-transfer-manager</artifactId><br />    </dependency><br /></dependencies></pre>  | 
| 패키지 이름 | 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 변경 사항
<a name="migration-s3-presign-api-changes"></a>

### S3 클라이언트 다운로드
<a name="migration-s3-presign-api-s3client"></a>

다음 표에서는 S3 클라이언트 다운로드에 대한 v1 및 v2 API 호출을 비교합니다.


| 사용 사례: | v1 |  v2 | 
| --- | --- | --- | 
| 클라이언트 생성 |  <pre>AmazonS3 s3Client = <br />        AmazonS3ClientBuilder.defaultClient();</pre>  |  <pre>S3AsyncClient s3AsyncClient = <br />        S3AsyncClient.create();<br />AsyncPresignedUrlExtension extension = <br />        s3AsyncClient.presignedUrlExtension();</pre>  | 
| 미리 서명된 URL 생성 |  <pre>Date expiration = new Date(<br />        System.currentTimeMillis() + 600_000);<br />URL presignedUrl = s3Client.generatePresignedUrl(<br />        new GeneratePresignedUrlRequest(<br />            "my-bucket", "my-key")<br />            .withMethod(HttpMethod.GET)<br />            .withExpiration(expiration));</pre>  |  <pre>S3Presigner presigner = S3Presigner.create();<br />PresignedGetObjectRequest presigned = <br />        presigner.presignGetObject(r -> r<br />            .getObjectRequest(req -> req<br />                .bucket("my-bucket").key("my-key"))<br />            .signatureDuration(Duration.ofMinutes(10)));<br />URL presignedUrl = presigned.url();<br />presigner.close();</pre>  | 
| 다운로드 요청 생성 |  <pre>PresignedUrlDownloadRequest downloadRequest = <br />        new PresignedUrlDownloadRequest(presignedUrl);</pre>  |  <pre>PresignedUrlDownloadRequest downloadRequest = <br />        PresignedUrlDownloadRequest.builder()<br />            .presignedUrl(presignedUrl)<br />            .build();</pre>  | 
| 스트림에 다운로드 |  <pre>PresignedUrlDownloadResult result = <br />        s3Client.download(downloadRequest);<br />InputStream content = result.getS3Object()<br />        .getObjectContent();</pre>  |  <pre>ResponseBytes<GetObjectResponse> bytes = <br />        extension.getObject(downloadRequest,<br />            AsyncResponseTransformer.toBytes())<br />        .join();</pre>  | 
| 파일로 다운로드 |  <pre>s3Client.download(downloadRequest,<br />        new File("/tmp/file.bin"));</pre>  |  <pre>extension.getObject(downloadRequest,<br />            Paths.get("/tmp/file.bin"))<br />        .join();</pre>  | 
| 범위와 함께 다운로드 |  <pre>PresignedUrlDownloadRequest rangeRequest = <br />        new PresignedUrlDownloadRequest(presignedUrl);<br />rangeRequest.setRange(0, 1023);<br />s3Client.download(rangeRequest);</pre>  |  <pre>PresignedUrlDownloadRequest rangeRequest = <br />        PresignedUrlDownloadRequest.builder()<br />            .presignedUrl(presignedUrl)<br />            .range("bytes=0-1023")<br />            .build();<br />extension.getObject(rangeRequest,<br />            Paths.get("/tmp/partial.bin"))<br />        .join();</pre>  | 

### Transfer Manager 다운로드
<a name="migration-s3-presign-api-tm"></a>

다음 표에서는 Transfer Manager 다운로드에 대한 v1 및 v2 API 호출을 비교합니다.


| 사용 사례: | v1 |  v2 | 
| --- | --- | --- | 
| Transfer Manager 생성 |  <pre>TransferManager tm = <br />        TransferManagerBuilder.standard().build();</pre>  |  <pre>S3TransferManager tm = <br />        S3TransferManager.create();</pre>  | 
| 다운로드 |  <pre>PresignedUrlDownload download = tm.download(<br />        new PresignedUrlDownloadRequest(presignedUrl),<br />        new File("/tmp/file.bin"));<br />download.waitForCompletion();</pre>  |  <pre>PresignedFileDownload download = <br />        tm.downloadFileWithPresignedUrl(<br />            PresignedDownloadFileRequest.builder()<br />                .presignedUrlDownloadRequest(<br />                    downloadRequest)<br />                .destination(Paths.get("/tmp/file.bin"))<br />                .addTransferListener(<br />                    LoggingTransferListener.create())<br />                .build());<br />download.completionFuture().join();</pre>  | 

자세한 내용은 [미리 서명된 URL을 사용하여 다운로드](transfer-manager.md#transfer-manager-presigned-url-download) 단원을 참조하십시오.

## 구성 변경
<a name="migration-s3-presign-config"></a>

### S3 클라이언트
<a name="migration-s3-presign-config-s3"></a>

다음 표에서는 v1에서 v2로의 S3 클라이언트 구성 변경 사항을 설명합니다.


| 설정 | v1 |  v2 | 
| --- | --- | --- | 
| 멀티파트 구성 | PresignedUrlDownloadConfig.withDownloadSizePerRequest(long) | S3AsyncClient.builder().multipartConfiguration(c -> c.minimumPartSizeInBytes(...)) | 
| 사용자 지정 헤더 | PresignedUrlDownloadRequest.putCustomRequestHeader(String, String) | 지원되지 않음. 다운로드 시 Range 및 만 설정할 If-Match 수 있습니다. | 

### Transfer Manager
<a name="migration-s3-presign-config-tm"></a>

다음 표에서는 Transfer Manager 구성 변경 사항을 v1에서 v2로 설명합니다.


| 설정 | v1 |  v2 | 
| --- | --- | --- | 
| 진행 상황 추적 | PresignedUrlDownloadConfig.withS3progressListener(...) | PresignedDownloadFileRequest.builder().addTransferListener(...) | 
| 재시도 시 재개 | PresignedUrlDownloadConfig.withResumeOnRetry(true) | 지원되지 않음 | 
| 일시 중지/재개 | 지원되지 않음 | 지원되지 않음 | 

**참고**  
 AWS CRT 기반 S3 클라이언트(`S3AsyncClient.crtBuilder()`)는 현재 미리 서명된 URL 확장을 지원하지 않습니다. `S3AsyncClient.builder()`를 사용합니다.