[AWS] S3 Client

 

S3Client

S3Client는 AWS SDK에서 제공하는 클래스 중 하나이며, S3와 상호작용하는 기능을 제공한다.

주로 파일 업로드, 다운로드, 삭제, 리스트 조회 등의 기능을 수행할 때 사용된다.

---

1. S3Client 개요

S3Client는 앞서 언급한 바와 같이 AWS SDK에서 제공하는 S3 서비스의 클라이언트 객체이다.

기본적으로 싱크방식(Blocking I/O)으로 동작한다.

필요에 따라, 비동기로 구현해야 한다면 S3AsyncClient를 사용할 수 있다.

 

현재 제공하는 버전은 V1, V2가 있지만, V2에서는 S3Client.builder()를 활용하여 클라이언트를 생성할 수있기에

V2를 권장하고 있다.

---

2. S3Client 의존성 주입

Maven

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.20.100</version>
</dependency>

 

Gradle

dependencies {
    implementation("software.amazon.awssdk:s3:2.20.100")
}

 

버전은 주입하기 전, 확인하고 사용하여야 한다.

 

---

3. S3Client 주요 기능

• S3 버킷 목록 조회

// 사용자의 모든 S3 버킷을 조회
ListBucketsResponse listBucketsResponse = s3Client.listBuckets();

 

 

• 파일 업로드

String bucketName = "one-and-only-my-bucket"; // S3 내에 업로드할 버킷 이름
String key = "uploads/sample1.txt"; // S3 내에서 저장될 경로
String filePath = "/local/path/to/sample.txt"; // 로컬 파일 경로

//버킷과 키를 설정
s3Client.putObject(
    PutObjectRequest.builder()
        .bucket(bucketName)
        .key(key)
        .build(),
    RequestBody.fromFile(Paths.get(filePath)) //로컬 파일을 읽어 업로드

 

• 파일 다운로드

String bucketName = "one-and-only-my-bucket"; // S3 내의 버킷 이름
String key = "uploads/sample1.txt"; // S3 내에 저장된 파일의 경로(key)
String downloadPath = "/local/path/to/downloaded.txt"; // 파일 다운로드할 로컬 경로

s3Client.getObject(
    GetObjectRequest.builder().bucket(bucketName).key(key).build(), // 다운로드 할 S3객체 지정
    Paths.get(downloadPath)
);

 

• 파일 삭제

s3Client.deleteObject(
    DeleteObjectRequest.builder()
        .bucket("one-and-only-my-bucket") // 삭제할 버킷 이름
        .key("uploads/sample1.txt") // 삭제할 S3 객체의 경로(key)
        .build()
);

 

---

4. S3 Presigned URL 사용

S3에 파일을 업로드 시, Presigned URL을 사용하면, 클라이언트가 직접 S3에 업로드할 수 있다.

 

Presigned URL 생성

import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.presigner.S3Presigner;
import software.amazon.awssdk.services.s3.presigner.model.GetObjectPresignRequest;
import java.time.Duration;

S3Presigner presigner = S3Presigner.create();

GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder()
    .signatureDuration(Duration.ofMinutes(10)) // 10분 동안 유효
    .getObjectRequest(GetObjectRequest.builder()
        .bucket("my-bucket")
        .key("uploads/sample.txt")
        .build())
    .build();

String presignedUrl = presigner.presignGetObject(presignRequest).url().toString();
System.out.println("Presigned URL: " + presignedUrl);

 

생성된 Presigned URL을 클라이언트가 사용하면, 서버를 거치지 않고 직접 S3에 접근 가능.

단, Presigned URL은 특정 시간 동안만 활성화되며, 정해진 시간이 지나면 권한이 만료된다.

 

5. S3 Client vs S3AsyncClient

비교 항목	S3Client(동기)	S3AsyncClient(비동기)
요청 처리 방식	블로킹(Blocking)	논블로킹(Non-Blocking)
API 응답 방식	Response 객체 반환	CompletableFuture<Response> 반환
추천 사용 케이스	작은 규모의 애플리케이션	대규모 트래픽 또는 비동기 병렬 처리 필요 시

 

• S3AsyncClient는 Netty 기반으로 동작하며, 대량의 파일 업로드 및 다운로드 처리 시 성능 최적화 가능
• 일반적인 Spring boot 어플리케이션은 S3Client를 사용하는 것이 보편적