S3
카카오클라우드의 Object Storage는 S3 API와 호환성을 제공합니다.
API 사용 준비
API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.
Authentication
임시 자격 증명
현재는 AssumeRoleWithWebIdentity
만 지원합니다.
Openstack Token을 이용하여 token 사용자의 권한으로 임시 자격 증명을 만들 수 있습니다.
생성된 임시 자격 증명은 사용자 token이 발급된 project의 role을 동일하게 부여받습니다.
Request Syntax
curl -X POST \ 'https://objectstorage.kr-central-2.kakaocloud.com/' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--data-raw '{
"Action" : "AssumeRoleWithWebIdentity",
"DurationSeconds" : 1800,
"ProviderId" : "iam.kakaocloud.com",
"WebIdentityToken" : "{x-auth-token}"
}'
메서드 | 요청 URL |
---|---|
POST | https://objectstorage.kr-central-2.kakaocloud.com/ |
Request Elements
Query | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Action | String | 필수 | 수행하려는 Action의 종류 - AssumeRoleWithWebIdentity 만 지원됨 |
DurationSeconds | Int | 선택 | 임시 자격 증명이 유효한 지속 기간 |
ProviderId | String | 선택 | WebIdentity를 제공하는 주체 현재는 iam.kakaocloud.com 만 제공함 |
WebIdentityToken | String | 필수 | Openstack에서 발급한 토큰 |
Response Syntax
<AssumeRoleWithWebIdentityResponse>
<AssumeRoleWithWebIdentityResult>
<SubjectFromWebIdentityToken>{user_id}</SubjectFromWebIdentityToken>
<Credentials>
<SessionToken>{session_token}</SessionToken>
<SecretAccessKey>{session_secret_key}</SecretAccessKey>
<Expiration>{expiration}</Expiration>
<AccessKeyId>{session_access_key}</AccessKeyId>
</Credentials>
<Provider>iam.kakaocloud.com</Provider>
</AssumeRoleWithWebIdentityResult>
<ResponseMetadata>
<RequestId>{request_id}</RequestId>
</ResponseMetadata>
</AssumeRoleWithWebIdentityResponse>
Response Elements
Response | 유형 | 설명 |
---|---|---|
user_id | String | 임시자격 증명이 사용할 사용자 ID |
session_token | String | 임시 자격 증명의 시크릿 토큰 |
session_secret_key | String | 임시 자격 증명의 시크릿 액세스 키 |
session_access_key | String | 임시 자격 증명의 시크릿 액세스 키 ID |
expiration | Timestamp | 임시 자격증명의 만료 시간 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | BadRequest | 요청 정보 오류 |
403 | Forbidden | 권한 없음 |
임시 자격 증명을 이용한 S3 요청
S3의 임시자격 증명을 이용한 요청과 동일합니다.
Credential 발급
현재는 Openstack에서 ec2 credential 발급을 하여 사용합니다.
Request Syntax
openstack ec2 credentials create --project {project-id}
Argument | 유형 | 필수 여부 | 설명 |
---|---|---|---|
project_id | String | 필수 | 발급하고자 하는 프로젝트의 아이디 |
Response Syntax
+------------+-----------------+
| Field | Value |
+------------+-----------------+
| access | {access_key_id} |
| project_id | {project_id} |
| secret | {secret_key} |
| user_id | {user_id} |
+------------+-----------------+
Response Elements
Response | 유형 | 설명 |
---|---|---|
access_key_id | String | 생성된 액세스 키 아이디 (aws_access_key_id )로 사용 |
user_id | String | 요청한 사용자 아이디 |
project_id | String | 크리덴셜이 유효한 project_id |
secret_key | String | 생성된 액세스 키(aws_secret_access_key ) 로 사용 |
응답에서 발급되는 access와 secret은 AWS credential로 사용하게 됩니다.
제공되는 기능 목록
Expected owner 기능은 현재 지원하지 않습니다.
S3 API 리전 별 지원 여부
- kr-central-1
- kr-central-2
현재 kr-central-1리전은 S3 API를 지원하지 않습니다.
카카오클라우드 오브젝트 스토리지의 bucket CORS 기능을 사용 하거나 public access 설정된 bucket에 s3 엔드포인트 url로 접근 하려면 project id를 다음과 같이 함께 명기해야 한다.
https://objectstorage.kr-central-2.kakaocloud.com/{project-id}:{bucket-name}/{object-path}
Feature | API 지원 현황 | 설명 |
---|---|---|
ListBuckets | Supported | |
SecurityTokenService | Partially supported | AssumeRoleWithWebIdentity 만 지원 |
HeadBucket | Supported | |
GetBucketAccelerateConfiguration | ||
GetBucketAcl | Supported | |
GetBucketAnalyticsConfiguration | ||
ListBucketAnalyticsConfigurations | ||
GetBucketCors | ||
GetBucketEncryption | Supported | |
GetBucketIntelligentTieringConfiguration | ||
ListBucketIntelligentTieringConfigurations | ||
GetBucketInventoryConfiguration | ||
ListBucketInventoryConfigurations | ||
GetBucketLifecycle | Supported | |
GetBucketLifecycleConfiguration | Supported | |
GetBucketLocation | Supported | |
GetBucketLogging | Supported | |
GetBucketMetricsConfiguration | ||
ListBucketMetricsConfigurations | ||
GetBucketNotification | ||
GetBucketNotificationConfiguration | ||
GetBucketOwnershipControls | ||
GetBucketPolicy | ||
GetBucketPolicyStatus | ||
GetBucketReplication | ||
GetBucketRequestPayment | ||
GetBucketTagging | ||
GetBucketVersioning | ||
GetBucketWebsite | ||
ListObjectVersions | ||
ListObjectsV2 | Supported | |
GetObjectLockConfiguration | ||
GetPublicAccessBlock | ||
ListMultipartUploads | Supported | |
ListObjects | Supported | |
PutBucketAccelerateConfiguration | ||
PutBucketAcl | Partially supported | 사용자 ID와 AllUsers uri 기반의 설정만 가능 |
PutBucketAnalyticsConfiguration | ||
PutBucketCors | ||
PutBucketEncryption | Partially supported | 버킷이 비어있는 경우에만 설정 가능 |
PutBucketIntelligentTieringConfiguration | ||
PutBucketInventoryConfiguration | ||
PutBucketLifecycle | Partial Supported | |
PutBucketLifecycleConfiguration | Partial Supported | |
PutBucketLogging | Supported | |
PutBucketMetricsConfiguration | ||
PutBucketNotification | ||
PutBucketNotificationConfiguration | ||
PutBucketOwnershipControls | ||
PutBucketPolicy | ||
PutBucketReplication | ||
PutBucketRequestPayment | ||
PutBucketTagging | ||
PutBucketVersioning | ||
PutBucketWebsite | ||
PutObjectLockConfiguration | ||
PutPublicAccessBlock | ||
CreateBucket | Supported | |
DeleteBucketAnalyticsConfiguration | ||
DeleteBucketCors | ||
DeleteBucketEncryption | ||
DeleteBucketIntelligentTieringConfiguration | ||
DeleteBucketInventoryConfiguration | ||
DeleteBucketLifecycle | Supported | |
DeleteBucketLifecycleConfiguration | Supported | |
DeleteBucketMetricsConfiguration | ||
DeleteBucketOwnershipControls | ||
DeleteBucketPolicy | ||
DeleteBucketReplication | ||
DeleteBucketTagging | ||
DeleteBucketWebsite | ||
DeletePublicAccessBlock | ||
DeleteBucket | Supported | |
DeleteObjects | Supported | |
HeadObject | Supported | |
GetObjectAcl | ||
GetObjectAttributes | ||
GetObjectLegalHold | ||
GetObjectRetention | ||
GetObjectTagging | Supported | |
GetObjectTorrent | ||
ListParts | Supported | |
GetObject | Supported | |
PutObjectAcl | ||
PutObjectLegalHold | ||
PutObjectRetention | ||
PutObjectTagging | Supported | |
UploadPartCopy | Supported | |
UploadPart | Supported | |
CopyObject | Supported | |
PutObject | Supported | |
AbortMultipartUpload | Supported | |
DeleteObjectTagging | Supported | |
DeleteObject | Supported | |
CompleteMultipartUpload | Supported | |
CreateMultipartUpload | Supported | |
RestoreObject | ||
SelectObjectContent | ||
WriteGetObjectResponse |
API 사용 가이드
ListBuckets
프로젝트에 생성된 모든 버킷을 조회합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
GET | https://objectstorage.kr-central-2.kakaocloud.com/ |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<DisplayName>String</DisplayName>
<ID>String</ID>
</Owner>
<Buckets>
<Bucket>
<Name>String</Name>
<CreationDate>Timestamp</CreationDate>
</Bucket>
</Buckets>
</ListAllMyBucketsResult>
Response Elements
Response | 유형 | 설명 |
---|---|---|
DisplayName | String | 사용자 아이디 |
ID | String | 사용자 고유 아이디 |
Name | String | 버킷 이름 |
CreationDate | Timestamp | 생성 날짜 |
HeadBucket
버킷의 존재여부나 접근 권한이 있는지 확인하기 위해 HeadBuckets API를 사용할 수 있습니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
Head | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName} |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Amz-Security-Token | String | 필수 | AWS 보 안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
Response Headers
Key | 설명 |
---|---|
Date | Response 생성 시간 |
Content-Length | response의 body 크기 |
Connection | Connection 재사용 여부 |
X-Amz-Request-Id | Request 고유 ID |
X-Rgw-Bytes-Used | 생성 날짜 |
X-Rgw-Object-Count | Bucket 내 오브젝트 수 |
X-Rgw-Quota-Bucket-Objects | 미사용 |
X-Rgw-Quota-Bucket-Size | 미사용 |
X-Rgw-Quota-Max-Buckets | 미사용 |
X-Rgw-Quota-User-Objects | 미사용 |
X-Rgw-Quota-User-Size | 미사용 |
X-Content-Type-Options | MIME type sniffing을 막기 위한 보안용 header |
X-Frame-Options | click-jacking을 막기 위한 보안용 header |
X-XSS-Protection | Browser에서 XSS attack이 detection 되었을 때는 동작 방식을 나타내기 위한 보안용 header |
Strict-Transport-Security | https 통신만 허용하게 하는 보안용 header |
CreateBucket
버킷을 생성합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
PUT | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName} |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
DeleteBucket
버킷을 삭제합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
DELETE | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName} |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 204 응답을 받습니다.
GetBucketAcl
버킷의 접근 가능한 역할 권한 정보를 조회합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
GET | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName}/?acl |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
<AccessControlPolicy>
<Owner>
<ID>string</ID>
<DisplayName>string</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<ID>string</ID>
<DisplayName>string</DisplayName>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>
Response Elements
Response | 유형 | 설명 |
---|---|---|
DisplayName | String | 사용자 아이디 |
ID | String | 사용자 고유 아이디 |
xsi | String | - CanonicalUser - Group : 'AllUsers' 만 가능 |
Permission | String | - FULL_CONTROL - WRITE - WRITE_ACP - READ - READ_ACP |
PutBucketAcl
버킷의 접근 가능한 역할 권한을 설정합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
PUT | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName}/?acl |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Content-Type | String | 필수 | text/html |
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AccessControlList>
<Grant>
<Grantee>
<DisplayName> String </DisplayName>
<ID> String </ID>
<xsi:type> String </xsi:type>
</Grantee>
<Permission> String </Permission>
</Grant>
</AccessControlList>
<Owner>
<DisplayName> String </DisplayName>
<ID> String </ID>
</Owner>
</AccessControlPolicy>
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
DisplayName | String | 선택 | 사용자 아이디 |
ID | String | 선택 | 사용자 고유 아이디 |
xsi | String | 필수 | - CanonicalUser - Group : 'AllUsers' 만 가능 |
Permission | String | 선택 | - FULL_CONTROL - WRITE - WRITE_ACP - READ - READ_ACP |
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
GetBucketEncryption
버킷의 암호화 설정 정보를 조회합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
GET | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName}/?encryption |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Content-Type | String | 필수 | text/html |
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
이 요청은 Body 값을 가지지 않습니다.
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
<?xml version="1.0" encoding="UTF-8"?>
<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>String</SSEAlgorithm>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>
Response Elements
Response | 유형 | 설명 |
---|---|---|
SSEAlgorithm | String | AES256 |
PutBucketEncryption
버킷 암호화를 설정합니다. (버킷에 오브젝트가 비어있는 경우에만 설정이 가능합니다.)
API 호출 방식
메서드 | 요청 URL |
---|---|
PUT | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName}/?encryption |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Content-MD5 | String | 필수 | Request Body 내용을 서버 측 암호화 구성에 대한 MD5 다이제스트를 Base64로 인코딩한 값 |
Content-Type | String | 필수 | text/html |
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Request Body
<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>String</SSEAlgorithm>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
SSEAlgorithm | String | 필수 | AES256 |
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
GetBucketLifecycle
버킷 라이프 사이클 설정 정보를 조회합니다.
API 호출 방식
메서드 | 요청 URL |
---|---|
GET | https://objectstorage.kr-central-2.kakaocloud.com/{BucketName}/?lifecycle |
Request Syntax
Request Header
Key | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Content-Type | String | 필수 | text/html |
X-Amz-Security-Token | String | 필수 | AWS 보안 토큰 |
X-Amz-Content-Sha256 | String | 필수 | 컨텐츠의 SHA256 해시 값 |
X-Amz-Date | String | 필수 | AWS 서비스 요청을 보낸 날짜와 시간 |
Authorization | String | 필수 | 요청에 서명된 AWS 서명 버전 4 헤더 - Credential: AWS 액세스 키 ID 및 자격 증명 범위 (필수) - SignedHeaders: 서명된 헤더 이름 목록 (필수) - Signature: 서명 값 (필수) |
Response Syntax
동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<Status>string</Status>
<Expiration>
<Days>integer</Days>
</Expiration>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</And>
</Filter>
<ID>string</ID>
</Rule>
</LifecycleConfiguration>