S3 API로 Object Storage 사용

카카오클라우드의 Object Storage는 AWS Object Storage 'S3'와 호환되는 일부 API를 제공하며, 기존 S3를 사용하는 워크로드에서 카카오클라우드의 Object Storage를 사용할 수 있습니다. 이 문서에서는 Bucket, Object를 사용하는 일부 API의 사용 예제를 설명합니다. 카카오클라우드의 Object Storage에서 제공하는 API 기능별 설명은 API Reference 문서를 확인하시기 바랍니다.

안내

예상 소요 시간: 30분
사용자 환경
- 권장 운영 체제: MacOS, Ubuntu
- Region: kr-central-2
사전 준비 사항
- 액세스 키

시작하기 전에

API 인증 토큰 발급

사용자 로컬 머신의 터미널에 접속합니다. 아래 명령에서 ACCESS_KEY와 ACCESS_SECRET_KEY를 각각 '액세스 키'와 '보안 액세스 키' 값으로 수정합니다. 그 다음 아래 API 인증 토큰을 발급받는 명령을 실행합니다.

API 사용 준비 문서를 참고하여 API 인증 토큰을 발급하시기 바랍니다.

export API_TOKEN=$(curl -s -X POST -i https://iam.kakaocloud.com/identity/v3/auth/tokens -H "Content-Type: application/json" -d \
'{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "id": "{ACCESS_KEY}",
                "secret": "{ACCESS_SECRET_KEY}"
            }
        }
    }
}' | grep x-subject-token | awk -v RS='\r\n' '{print $2}')

발급받은 API 인증 토큰을 확인합니다.
```
echo $API_TOKEN
```

S3 API 사용을 위한 크리덴셜 발급

S3 API 사용을 위한 크리덴셜 발급을 위해서는 사용자 고유 ID가 필요합니다. [콘솔] > [계정 정보]에서 사용자 고유 ID를 확인합니다.
발급 받은 유저 고유 ID, API_TOKEN 그리고 프로젝트 ID를 아래 환경 변수 부분에 작성합니다. 그 다음 해당 스크립트를 실행하여 S3 API 사용을 위한 크리덴셜 정보를 받아옵니다.
```
echo $(curl -s -X POST -i https://iam.kakaocloud.com/identity/v3/users/{USER_ID}/credentials/OS-EC2 \
 -H "Content-Type: application/json" \
 -H "X-Auth-Token: ${API_TOKEN}" -d \
 '{
     "tenant_id": "{PROJECT_ID}"
 }')
```
프로젝트 ID 획득하기
프로젝트 ID는 카카오클라우드 콘솔 메인 화면 상단의 작업 중인 프로젝트에서 확인할 수 있습니다.
출력된 결과 중에서 access, secret 값을 확인합니다.

결과 키 환경 변수
“access” S3_ACCESS_KEY
“secret” S3_SECRET_ACCESS_KEY

결과 키	환경 변수
“access”	S3_ACCESS_KEY
“secret”	S3_SECRET_ACCESS_KEY

Type 1. AWS CLI 예제

AWS 명령줄 인터페이스(CLI)를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

AWS CLI 설정

AWS CLI 실행을 위한 자격 증명과 환경을 설정합니다. 만약 AWS CLI가 설치되어 있지 않다면, 먼저 AWS CLI를 설치합니다.

Mac
Linux(Ubuntu)

Homebrew 패키지 매니저를 이용하거나, curl 명령어를 이용하여 설치합니다.

Homebrew 이용
$ brew install awscli

curl 명령어 이용
$ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
$ sudo installer -pkg AWSCLIV2.pkg -target /

설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.

AWS CLI 설치 확인
# 경로 확인
$ which aws
/usr/local/bin/aws

# 버전 확인
$ aws --version
aws-cli/2.10.0 Python/3.11.2 Darwin/18.7.0 botocore/2.4.5

curl 명령어를 이용하여 설치합니다.

curl 명령어 이용
$ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
$ sudo installer -pkg AWSCLIV2.pkg -target /

설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.

AWS CLI 설치 확인
# 경로 확인
$ which aws
/usr/local/bin/aws

# 버전 확인
$ aws --version
aws-cli/2.10.0 Python/3.11.2 Darwin/18.7.0 botocore/2.4.5

이어서 진행하기 위해 S3 사용에 필요한 크리덴셜 값을 확인합니다.

configure 명령을 이용하여 설정을 진행합니다.
```
aws configure
```

다음을 참고하여 사용자의 자격 증명을 입력합니다.

AWS Access Key ID: {S3_ACCESS_KEY}
AWS Secret Access Key: {S3_SECRET_ACCESS_KEY}
Default region name: kr-central-2
Default output format:

설정이 끝나면 다음과 같은 방법으로 s3 명령을 사용할 수 있습니다.
```
aws --endpoint-url={endpoint} s3 {command} s3://{bucket}
```
```
# Example
# aws --endpoint-url=https://objectstorage.kr-central-2.kakaocloud.com s3 ls
```
리전 엔드포인트
kr-central-2 https://objectstorage.kr-central-2.kakaocloud.com

리전	엔드포인트
kr-central-2	`https://objectstorage.kr-central-2.kakaocloud.com`

AWS CLI 사용 예시

버킷 생성
aws --endpoint-url={endpoint} s3 mb s3://{bucket_name}

전체 버킷 목록 조회
aws --endpoint-url={endpoint} s3 ls

특정 버킷 내부 조회
aws --endpoint-url={endpoint} s3 ls s3://{bucket_name}

버킷 삭제
aws --endpoint-url={endpoint} s3 rb s3://{bucket_name}

파일 업로드
aws --endpoint-url={endpoint} s3 cp {local_path} s3://{bucket_name}/{upload_path}

파일 다운로드
aws --endpoint-url={endpoint} s3 cp s3://{bucket_name}/{file_path} {local_path}

파일 삭제
aws --endpoint-url={endpoint} s3 rm s3://{bucket_name}/{file_path}

Type 2. Python SDK(Boto3) 예제

AWS Python SDK(Boto3)를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

S3 클라이언트 생성 및 설정

pip를 이용하여 boto3을 설치합니다.
```
$ pip install boto3
```
안내
현재 boto3은 Python 3.8 이상 버전에서만 지원됩니다.

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

import boto3

client = boto3.client(
    region_name="kr-central-2",
    endpoint_url="{ENDPOINT}",
    aws_access_key_id="{S3_ACCESS_KEY}",
    aws_secret_access_key="{S3_SECRET_ACCESS_KEY}",
    service_name="s3"
)

SDK 사용 예시

버킷 생성
def create_bucket(bucket_name):
    try:
        return client.create_bucket(Bucket=bucket_name)
    except Exception as e:
        raise #...

전체 버킷 목록 조회
def get_list_buckets() :
    try:
        response = client.list_buckets()
        return [bucket.get('Name') for bucket in response.get('Buckets', [])]
    except Exception as e:
        raise #...

특정 버킷 내부 조회
def get_list_objects(bucket_name):
    try:
        response = client.list_objects(Bucket=bucket_name)
        return [obj.get('Key') for obj in response.get('Contents', [])]
    except Exception as e:
        raise #...

버킷 삭제
def delete_bucket(bucket_name):
    try:
        return client.delete_bucket(Bucket=bucket_name)
    except Exception as e:
        raise #...

파일 업로드
# local_path : 업로드할 파일이 위치한 로컬 경로
# file_name : 업로드할 파일명
def upload_file(local_path, bucket_name, file_name) :
    try :
        # client.upload_file('/Documents/hello.jpeg', 'bucket', 'hello.jpeg')
        return client.upload_file(local_path, bucket_name, file_name)
    except Exception as e:
        raise

파일 다운로드
# file_name : 다운로드할 파일명
# local_path : 파일을 내려받을 로컬 경로 및 파일명
def download_file(bucket_name, file_name, local_path) :
    try :
        # client.download_file('bucket', 'hello.jpeg', '/Downloads/hello.jpeg')
        return client.download_file(bucket_name, file_name, local_path)
    except Exception as e:
        raise

파일 삭제
def delete_object(bucket_name, file_name) :
    try :
        return client.delete_object(Bucket=bucket_name, Key=file_name)
    except Exception as e :
        raise

Type 3. Java SDK 예제

AWS Java SDK를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다. 해당 문서는 aws-java-sdk-v2를 기준으로 작성되었습니다.

S3 클라이언트 생성 및 설정

Maven
Gradle

pom.xml에 다음과 같이 의존성을 추가합니다.

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

    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>1.7.32</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.12</version>
    </dependency>
</dependencies>

추가한 의존성을 반영하기 위해 Maven을 새로 빌드합니다.

build.gradle에 다음과 같이 의존성을 추가합니다.

implementation platform('software.amazon.awssdk:bom:2.23.7')
implementation 'software.amazon.awssdk:s3'
implementation 'ch.qos.logback:logback-classic:1.4.12'

추가한 의존성을 반영하기 위해 Gradle을 새로 빌드합니다.

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

String s3Endpoint = "https://objectstorage.kr-central-2.kakaocloud.com";
String accessKey = "{S3_ACCESS_KEY}";
String secretAccessKey = "{S3_SECRET_ACCESS_KEY}";
String region = "kr-central-2";


final S3Client client = S3Client.builder()
    .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretAccessKey)))
    .endpointOverride(URI.create(s3Endpoint))
    .forcePathStyle(true)
    .region(Region.of(region))
    .build();

SDK 사용 예시

버킷 생성
private void createBucket(S3Client client, String bucketName) {
    try {
        CreateBucketResponse res = client.createBucket(
            CreateBucketRequest.builder()
                .bucket(bucketName)
                .build());
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

전체 버킷 목록 조회
private void listBuckets(S3Client client) {
    try {
        ListBucketsResponse res = client.listBuckets();
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

특정 버킷 내부 조회
private void listObjects(S3Client client, String bucketName) {
    try {
        ListObjectsResponse res = client.listObjects(
            ListObjectsRequest.builder()
                .bucket(bucketName)
                .build());
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

버킷 삭제
private void deleteBucket(S3Client client, String bucketName) {
    try {
        DeleteBucketResponse res = client.deleteBucket(
            DeleteBucketRequest.builder()
                .bucket(bucketName)
                .build());
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

파일 업로드
// objectKey : 업로드할 파일명
// filePath : 업로드할 파일이 위치한 로컬 경로
private void uploadObject(S3Client client, String bucketName, String objectKey, String filePath){
    try {
        Path path = Paths.get(filePath);
        PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        client.putObject(putObjectRequest, path);
    } catch (Exception e){
        e.printStackTrace();
    }
}

파일 다운로드
// objectKey : 다운로드할 파일명
// filePath : 파일을 내려받을 로컬 경로 및 파일명
private void downloadObject(S3Client client, String bucketName, String objectKey, String filePath){
    try {
        Path path = Paths.get(filePath);
        GetObjectRequest getObjectRequest = GetObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        ResponseBytes<GetObjectResponse> responseBytes = client.getObjectAsBytes(getObjectRequest);

        byte[] data = responseBytes.asByteArray();

        File myFile = new File(filePath);
        OutputStream os = new FileOutputStream(myFile);
        os.write(data);
        os.close();
    } catch (IOException ex) {
        ex.printStackTrace();
    } catch (S3Exception e){
        e.printStackTrace();
    }
}

파일 삭제
// objectKey : 삭제할 파일명
private void deleteObject(S3Client client, String bucketName, String objectKey){
    try {
        DeleteObjectRequest deleteObjectRequest = DeleteObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        client.deleteObject(deleteObjectRequest);

    } catch (Exception e){
        e.printStackTrace();
    }
}

Type 4. Go SDK 예제

AWS Go SDK를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

S3 클라이언트 생성 및 설정

다음 명령어를 이용하여 로컬 프로젝트를 초기화합니다.
```
$ go mod init {project_name}
```

Go 모듈을 이용하여 Go V2용 AWS SDK 패키지들을 가져옵니다.

$ go get github.com/aws/aws-sdk-go-v2/config
$ go get github.com/aws/aws-sdk-go-v2/credentials
$ go get github.com/aws/aws-sdk-go-v2/service/s3

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

var accessKeyId = "{S3_ACCESS_KEY}"
var accessKeySecret = "{S3_SECRET_ACCESS_KEY}"
var endpoint = "{ENDPOINT}"
var region = "kr-central-2"
resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
    return aws.Endpoint{
        URL: endpoint,
    }, nil
})

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion(region),
    config.WithEndpointResolverWithOptions(resolver),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyId, accessKeySecret, "")),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg, func(options *s3.Options) {
    options.UsePathStyle = true
})

SDK 사용 예시

버킷 생성
bucketname := "{BUCKET_NAME}"
_, err = client.CreateBucket(context.TODO(), &s3.CreateBucketInput{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

전체 버킷 목록 조회
_, err = client.ListBuckets(context.TODO(), &s3.ListBucketsInput{})
if err != nil {
    log.Fatal(err)
}

특정 버킷 내부 조회
bucketname := "{BUCKET_NAME}"
_, err = client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

버킷 삭제
bucketname := "{BUCKET_NAME}"
_, err = client.DeleteBucket(context.TODO(), &s3.DeleteBucketInput{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

파일 업로드
bucketname := "{BUCKET_NAME}"
filePath := "{LOCAL_PATH}" // 업로드할 파일이 위치한 로컬 경로
objectKey := "{FILE_NAME}" // 업로드할 파일명

file, err := os.Open(filePath)
if err != nil {
	log.Fatal(err)
}
defer file.Close()

_, err = client.PutObject(context.TODO(), &s3.PutObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
	Body:   file,
})
if err != nil {
    log.Fatal(err)
}

파일 다운로드
bucketname := "{BUCKET_NAME}"
filePath := "{LOCAL_PATH}" // 파일을 내려받을 로컬 경로 및 파일 이름
objectKey := "{FILE_NAME}" // 다운로드할 파일명

file, err := os.Create(filePath)
if err != nil {
	panic(err)
}
defer file.Close()

result, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
})
if err != nil {
	log.Fatal(err)
}

_, err = io.Copy(file, result.Body)
if err != nil {
	panic(err)
}

파일 삭제
bucketname := "{BUCKET_NAME}"
objectKey := "{FILE_NAME}" // 삭제할 파일명

_, err = client.DeleteObject(context.TODO(), &s3.DeleteObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
})
if err != nil {
	log.Fatal(err)
}

시작하기 전에​

API 인증 토큰 발급​

S3 API 사용을 위한 크리덴셜 발급​

Type 1. AWS CLI 예제​

AWS CLI 설정​

AWS CLI 사용 예시​

Type 2. Python SDK(Boto3) 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

Type 3. Java SDK 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

Type 4. Go SDK 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

시작하기 전에

API 인증 토큰 발급

S3 API 사용을 위한 크리덴셜 발급

Type 1. AWS CLI 예제

AWS CLI 설정

AWS CLI 사용 예시

Type 2. Python SDK(Boto3) 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시

Type 3. Java SDK 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시

Type 4. Go SDK 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시