기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon S3 Transfer Manager로 파일 및 디렉터리 전송
Amazon S3 Transfer Manager는 AWS SDK for Java 2.x를 위한 오픈 소스의 고급 파일 전송 유틸리티입니다. 이를 사용하여 Amazon Simple Storage Service(Amazon S3)와 파일 및 디렉터리를 주고받을 수 있습니다.
[AWS CRT 기반 S3 클라이언트](crt-based-s3-client.md) 또는 [표준 Java 기반 S3 비동기식 클라이언트(멀티파트 사용 설정)](s3-async-client-multipart.md)를 기반으로 구축된 S3 Transfer Manager는 [멀티파트 업로드](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 및 [바이트 범위 가져오기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance-guidelines.html#optimizing-performance-guidelines-get-range)와 같은 성능 개선의 이점을 활용할 수 있습니다.
S3 Transfer Manager를 사용하면 전송 진행 상황을 실시간으로 모니터링하고 나중에 실행하기 위해 전송을 일시 중지할 수도 있습니다.
## 시작하기
### 빌드 파일에 종속성을 추가
향상된 멀티파트 성능으로 S3 Transfer Manager를 사용하려면 필요한 종속성으로 빌드 파일을 구성합니다.
------
#### [ Use the AWS CRT-based S3 client ]
```
software.amazon.awssdk
bom
2.27.211
pom
import
software.amazon.awssdk
s3-transfer-manager
software.amazon.awssdk.crt
aws-crt
0.29.1432
```
1 [최신 버전](https://central.sonatype.com/artifact/software.amazon.awssdk/bom). 2[최신 버전](https://central.sonatype.com/artifact/software.amazon.awssdk.crt/aws-crt).
------
#### [ Use the Java-based S3 async client ]
```
software.amazon.awssdk
bom
2.27.211
pom
import
software.amazon.awssdk
s3-transfer-manager
```
1 [최신 버전](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
------
### S3 Transfer Manager 인스턴스를 생성
병렬 전송을 활성화하려면 AWS CRT 기반 S3 클라이언트 또는 멀티파트가 활성화된 Java 기반 S3 비동기 클라이언트를 전달해야 합니다. 다음 예제에서는 사용자 지정 설정으로 S3 Transfer Manager를 구성하는 방법을 보여줍니다.
------
#### [ Use the AWS CRT-based S3 client ]
```
S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
.credentialsProvider(DefaultCredentialsProvider.create())
.region(Region.US_EAST_1)
.targetThroughputInGbps(20.0)
.minimumPartSizeInBytes(8 * MB)
.build();
S3TransferManager transferManager = S3TransferManager.builder()
.s3Client(s3AsyncClient)
.build();
```
------
#### [ Use the Java-based S3 async client ]
`aws-crt` 종속성이 빌드 파일에 포함되지 않은 경우 S3 Transfer Manager는 SDK for Java 2.x에서 사용되는 표준 S3 비동기식 클라이언트를 기반으로 구축됩니다.
**S3 클라이언트의 사용자 지정 구성 - 멀티파트 사용 필요**
```
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.multipartEnabled(true)
.credentialsProvider(DefaultCredentialsProvider.create())
.region(Region.US_EAST_1)
.build();
S3TransferManager transferManager = S3TransferManager.builder()
.s3Client(s3AsyncClient)
.build();
```
**S3 클라이언트 구성 없음 - 멀티파트 지원이 자동으로 사용 설정됨**
```
S3TransferManager transferManager = S3TransferManager.create();
```
------
## S3 버킷으로 파일을 업로드하려면
다음 예제는 업로드 진행 상황을 기록하는 [LoggingTransferListener](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/progress/LoggingTransferListener.html)의 선택적 사용과 함께 파일 업로드 예제를 보여줍니다.
S3 Transfer Manager를 사용하여 Amazon S3에 파일을 업로드하려면 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/UploadFileRequest.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/UploadFileRequest.html)객체를 `S3TransferManager`의 [uploadFile](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/S3TransferManager.html#uploadFile(software.amazon.awssdk.transfer.s3.model.UploadFileRequest)) 메서드에 전달하세요.
`uploadFile` 메서드에서 반환된 [FileUpload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/FileUpload.html) 객체는 업로드 프로세스를 나타냅니다. 요청이 완료되면 [CompletedFileUpload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CompletedFileUpload.html) 객체에는 업로드에 대한 정보가 포함됩니다.
```
public void trackUploadFile(S3TransferManager transferManager, String bucketName,
String key, URI filePathURI) {
UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
.putObjectRequest(b -> b.bucket(bucketName).key(key))
.addTransferListener(LoggingTransferListener.create()) // Add listener.
.source(Paths.get(filePathURI))
.build();
FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);
fileUpload.completionFuture().join();
/*
The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
You can also implement the interface to provide your own logic.
Configure log4J2 with settings such as the following.
Log4J2 logs the progress. The following is example output for a 21.3 MB file upload.
Transfer initiated...
| | 0.0%
|==== | 21.1%
|============ | 60.5%
|====================| 100.0%
Transfer complete!
*/
}
```
### 가져오기
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileUpload;
import software.amazon.awssdk.transfer.s3.model.FileUpload;
import software.amazon.awssdk.transfer.s3.model.UploadFileRequest;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;
```
## S3 버킷에서 파일 다운로드
다음 예시는 다운로드 예시와 함께 다운로드 진행 상황을 기록하는 [LoggingTransferListener](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/progress/LoggingTransferListener.html)의 선택적 사용을 보여줍니다.
S3 Transfer Manager를 사용하여 S3 버킷에서 객체를 다운로드하려면 [DownloadFileRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/DownloadFileRequest.html) 객체를 만들어 [downloadFile](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/S3TransferManager.html#downloadFile(software.amazon.awssdk.transfer.s3.model.DownloadFileRequest)) 메서드에 전달합니다.
`S3TransferManager`의 `downloadFile` 메서드에서 반환된 [FileDownload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/FileDownload.html) 객체는 파일 전송을 나타냅니다. 다운로드가 완료되면 [CompletedFileDownload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CompletedFileDownload.html)에는 다운로드에 대한 정보에 대한 액세스 권한이 포함됩니다.
```
public void trackDownloadFile(S3TransferManager transferManager, String bucketName,
String key, String downloadedFileWithPath) {
DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
.getObjectRequest(b -> b.bucket(bucketName).key(key))
.addTransferListener(LoggingTransferListener.create()) // Add listener.
.destination(Paths.get(downloadedFileWithPath))
.build();
FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);
CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
/*
The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
You can also implement the interface to provide your own logic.
Configure log4J2 with settings such as the following.
Log4J2 logs the progress. The following is example output for a 21.3 MB file download.
Transfer initiated...
|======= | 39.4%
|=============== | 78.8%
|====================| 100.0%
Transfer complete!
*/
}
```
### 가져오기
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.exception.SdkException;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadFileRequest;
import software.amazon.awssdk.transfer.s3.model.FileDownload;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;
import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.UUID;
```
## 다른 버킷에 Amazon S3 객체를 추가
다음 예는 S3 Transfer Manager로 객체를 복사하는 방법을 보여줍니다.
S3 버킷에서 다른 버킷으로 객체 복사를 시작하려면 기본 [CopyObjectRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/model/CopyObjectRequest.html) 인스턴스를 생성하세요.
다음으로, 기본 `CopyObjectRequest` 항목을 S3 Transfer Manager가사용할 수 있는 [CopyRequest로](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CopyRequest.html) 래핑합니다.
`S3TransferManager`의 `copy` 메서드에서 반환된 `Copy` 객체는 복사 프로세스를 나타냅니다. 복사 프로세스가 완료되면 [CompletedCopy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CompletedCopy.html) 객체에는 응답에 대한 세부 정보가 포함됩니다.
```
public String copyObject(S3TransferManager transferManager, String bucketName,
String key, String destinationBucket, String destinationKey) {
CopyObjectRequest copyObjectRequest = CopyObjectRequest.builder()
.sourceBucket(bucketName)
.sourceKey(key)
.destinationBucket(destinationBucket)
.destinationKey(destinationKey)
.build();
CopyRequest copyRequest = CopyRequest.builder()
.copyObjectRequest(copyObjectRequest)
.build();
Copy copy = transferManager.copy(copyRequest);
CompletedCopy completedCopy = copy.completionFuture().join();
return completedCopy.response().copyObjectResult().eTag();
}
```
**참고**
S3 Transfer Manager를 사용하여 리전 간 복사를 수행하려면 다음 코드 조각`crossRegionAccessEnabled`과 같이 AWS CRT 기반 S3 클라이언트 빌더에서를 활성화합니다.
```
S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
.crossRegionAccessEnabled(true)
.build();
S3TransferManager transferManager = S3TransferManager.builder()
.s3Client(s3AsyncClient)
.build();
```
### 가져오기
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.CopyObjectRequest;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedCopy;
import software.amazon.awssdk.transfer.s3.model.Copy;
import software.amazon.awssdk.transfer.s3.model.CopyRequest;
import java.util.UUID;
```
## S3 버킷에 로컬 디렉토리 업로드
다음 예는 로컬 디렉터리를 S3에 업로드하는 방법을 보여줍니다.
먼저 `S3TransferManager` 인스턴스의 [uploadDirectory](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/S3TransferManager.html#uploadDirectory(software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest)) 메서드를 호출하여 [UploadDirectoryRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/UploadDirectoryRequest.html)를 전달합니다.
[DirectoryUpload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/DirectoryUpload.html) 객체는 업로드 프로세스를 나타내며, 요청이 완료되면 [CompletedDirectoryUpload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CompletedDirectoryUpload.html)를 생성합니다. `CompleteDirectoryUpload` 객체에는 전송에 실패한 파일을 포함하여 전송 결과에 대한 정보가 들어 있습니다.
```
public Integer uploadDirectory(S3TransferManager transferManager,
URI sourceDirectory, String bucketName) {
DirectoryUpload directoryUpload = transferManager.uploadDirectory(UploadDirectoryRequest.builder()
.source(Paths.get(sourceDirectory))
.bucket(bucketName)
.build());
CompletedDirectoryUpload completedDirectoryUpload = directoryUpload.completionFuture().join();
completedDirectoryUpload.failedTransfers()
.forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
return completedDirectoryUpload.failedTransfers().size();
}
```
### 가져오기
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.DirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;
```
## 로컬 디렉터리로 S3 버킷 객체 다운로드
다음 예시와 같이 S3 버킷에 있는 객체를 로컬 디렉터리로 다운로드할 수 있습니다.
S3 버킷의 객체를 로컬 디렉토리로 다운로드하려면 먼저 Transfer Manager의 [DownloadDirectory](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/S3TransferManager.html#downloadDirectory(software.amazon.awssdk.transfer.s3.model.DownloadDirectoryRequest)) 메서드를 호출하고 [DownloadDirectoryRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/DownloadDirectoryRequest.html)를 전달하세요.
[DirectoryDownload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/DirectoryDownload.html) 객체는 업로드 프로세스를 나타내며, 요청이 완료되면 [CompletedDirectoryDownload](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/transfer/s3/model/CompletedDirectoryDownload.html)를 생성합니다. `CompleteDirectoryDownload` 객체에는 전송에 실패한 파일을 포함하여 전송 결과에 대한 정보가 들어 있습니다.
```
public Integer downloadObjectsToDirectory(S3TransferManager transferManager,
URI destinationPathURI, String bucketName) {
DirectoryDownload directoryDownload = transferManager.downloadDirectory(DownloadDirectoryRequest.builder()
.destination(Paths.get(destinationPathURI))
.bucket(bucketName)
.build());
CompletedDirectoryDownload completedDirectoryDownload = directoryDownload.completionFuture().join();
completedDirectoryDownload.failedTransfers()
.forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
return completedDirectoryDownload.failedTransfers().size();
}
```
### 가져오기
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadDirectoryRequest;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;
import java.util.stream.Collectors;
```
## 전체 예제 보기
이 페이지의 모든 예제에 대한 [전체 코드는 GitHub에 포함](https://github.com/awsdocs/aws-doc-sdk-examples/tree/d73001daea05266eaa9e074ccb71b9383832369a/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager)되어 있습니다.