S3 API로 Object Storage 사용
카카오클라우드의 Object Storage는 AWS 오브젝트 스토리지 'S3'와 호환되는 일부 API를 제공하며, 기존 S3를 사용하는 워크로드에서 카카오클라우드의 Object Storage를 사용할 수 있습니다. 이 문서에서는 Bucket, Object를 사용하는 일부 API의 사용 예제를 설명합니다. 카카오클라우드의 Object Storage에서 제공하는 API 기능별 설명은 API Reference 문서를 확인하시기 바랍니다.
- 예상 소요 시간: 30분
- 사용자 권장 환경
- 운영 체제: macOS, ubuntu
- Region:
kr-central-2
- 운영 체제: macOS, ubuntu
- 사전 준비 사항
- 액세스 키
사전 준비
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 사용을 위한 Credential 발급
-
S3 API 사용을 위한 Credential 발급을 위해서는
사용자 고유 ID
가 필요합니다. [콘솔] > [계정 정보]에서사용자 고유 ID
를 확인합니다. -
발급 받은
유저 고유 ID
,API_TOKEN
그리고프로젝트 ID
를 아래 환경 변수 부분에 작성합니다. 그 다음 해당 스크립트를 실행하여 S3 API 사용을 위한 Credential 정보를 받아옵니다.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}"
}')Project ID 획득하기Project ID는 해당 프로젝트의 콘솔 주소창에 표시되는 URI(
project_id
의 값)에서 확인하실 수 있습니다.
예를 들어https://console.kakaocloud.com/transit-gateway/transit-gateways?project_id=073fc84cbd86412ef9f6d269780ef89bb®ion=kr-central-2
의 경우, Project ID 값은&
이전까지 해당되는073fc84cbd86412ef9f6d269780ef89bb
이 됩니다. -
출력된 결과 중에서
access
,secret
값을 확인합니다.결과 키 환경 변수 “access” S3_ACCESS_KEY “secret” S3_SECRET_ACCESS_KEY
Type 1. AWS CLI 예제
AWS 명령줄 인터페이스(CLI)를 이용하여 카카오클라우드 오브젝트 스토리지를 이용하는 예시입니다.
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 사용 Credentials 값을 확인합니다.
-
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
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)를 이용하여 카카오클라우드 오브젝트 스토리지를 이용하는 예시입니다.
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(bucekt_name, file_name) :
try :
return client.delete_object(Bucket=bucekt_name, Key=file_name)
except Exception as e :
raise
Type 3. Java SDK 예제
AWS Java SDK를 이용하여 카카오클라우드 오브젝트 스토리지를 이용하는 예시입니다. 해당 문서는 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를 이용하여 카카오클라우드 오브젝트 스토리지를 이용하는 예시입니다.
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)
}