본문으로 건너뛰기

Bucket

Object Storage의 Bucket API를 사용하여 버킷의 생성과 관련 정보 및 정책을 관리할 수 있습니다.

API 사용 준비

  • API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.
  • Object Storage의 API Model에 대한 설명은 API 모델 문서를 참고하시기 바랍니다.

API 엔드포인트 URL

API 요청을 위한 Object Storage API 엔드포인트 URL은 다음과 같습니다.

Object Storage API 엔드포인트 URL 형식
https://objectstorage.kr-central-2.kakaocloud.com

버킷 생성

버킷을 생성합니다.

권한 안내

카카오클라우드의 IAM 역할에 따라, 버킷을 생성하기 위해서는 프로젝트 관리자 또는 프로젝트 멤버 역할이 필요합니다.

Request Syntax
버킷 생성 Request Syntax (kr-central-2)
curl --request PUT --location 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
"name": "my-bucket-new",
"type": "STANDARD",
"use_encryption": true,
"encryption_configuration": {
"type": "managed"
}
}'
API 호출 방식
메서드요청 URL
PUT  https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰을 입력
Content-TypeString필수  application/json으로 고정
Request Elements
Request유형필수 여부설명
nameString필수  버킷 이름
typeString필수  버킷 타입
- Standard(기본값): standard 버킷
use_encryptionBoolean선택버킷 암호화 여부
encryption_configuration 설정을 입력하는 경우 입력값이 무시됨
- false(기본값): 암호화하지 않음
- true: 암호화 함
(encryption_configuration.type = managed와 동일)
encryption_configuration ▼Structure선택버킷 암호화 설정
    typeString필수  암호화 방법
- managed(기본값): 사바에서 제공하는 자동 암호화
- true(지원 예정): KMS를 이용한 키 관리 서비스와 연계한 암호화
Response Syntax
버킷 생성 Response Syntax (kr-central-2)
{
"account": "project-id",
"project": "project-id",
"name": "my-bucket-new",
"type": "STANDARD",
"bytes": 0,
"objectCount": 0,
"createdAt": "2022-04-25T10:28:57Z",
"acl": {
"permissions": null,
"public": "read-only",
"public_read_allow_ip_list": [
"ip / cidr"
]
},
"lastModified": "2022-04-25T10:28:57Z",
"use_encryption": true,
"encryption_type": "managed",
"storageClass": "STANDARD",
"storagePolicy": "default-placement"
}
Response Elements
Response유형설명
account (Deprecated)StringProject ID
- Swift API에서 Account 값. 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
projectStringProject ID
nameString생성된 버킷 이름
typeString생성된 버킷 타입
- STANDARD(기본값): standard 버킷
bytesString총 사용량
- 단위: Byte
objectCountInt버킷의 오브젝트 개수
createdAtString생성일
- 형식: RFC3339
- 예시: 2020-07-01T00:00:00Z
use_encryptionBoolean버킷 암호화 여부
- false(기본값): 암호화하지 않음
- true: 암호화 함
encryption_typeString버킷 암호화 타입
lastModifiedString최종 수정일
- 형식: RFC3339
- 예시: 2020-07-01T00:00:00Z
storageClassString스토리지 클래스 종류
- STANDARD(기본값): standard 클래스의 버킷
storagePolicyString스토리지 클래스의 존
- default-placement(기본값)
acl ▼-버킷에 대한 접근 권한
- null 입력 시, 기존 ACL 설정 삭제
    publicString퍼블릭 접근 허용 여부
- read-only, deny
    public_read_allow_ip_listList퍼블릭 접근 허용 IP 리스트
Status Code
HTTP Status응답 내용설명
200     OK성공
400Bad Request입력 설정 오류
401Unauthorized권한 없음
409Conflicts생성 실패
- 동일한 bucket_name이 이미 존재

버킷 관리

버킷 상세 조회

storage.buckets.get 권한이 있을 경우, 특정 버킷에 대한 상세 정보를 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

Request Syntax
버킷 상세 조회 Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'
API 호출 방식
메서드요청 URL
GET   https://objectstorage.{region_name}.kakaocloud.com/v1_ext/{bucket_name}
Path유형필수 여부설명
region_nameString필수  리전명
- kr-central-1 또는 kr-central-2
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰을 입력
Response Syntax

Bucket의 API 모델에 대한 자세한 설명은 Bucket API Model을 참고하시기 비랍니다.

버킷 상세 조회 Response Syntax(kr-central-2)
{    
"project": "project-id",
"name": "test-bucket-01",
"type": "STANDARD",
"bytes": 0,
"objectCount": 0,
"createdAt": "2023-06-21T07:17:10Z",
"use_encryption": true,
"encryption_type": " ",
"lastModified": "2023-06-21T07:17:10Z",
"storageClass": "STANDARD",
"storagePolicy": "default-placement",
"acl": {
"public": "deny",
"public_read_allow_ip_list": null
}
}
Response Elements
Response유형설명
projectStringProject ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- S3 API에서 사용
nameString생성된 버킷 이름
typeString생성된 버킷 타입
- standard(기본값): standard 버킷
bytesString총 사용량
- 단위: Byte
objectCountInt버킷의 오브젝트 개수
createdAtString생성일
- 형식: RFC3339
- 예시: 2020-07-01T00:00:00Z
use_encryptionBoolean버킷 암호화 여부
- false(기본값): 암호화하지 않음
- true: 암호화 함
encryption_typeString버킷 암호화 타입
lastModifiedString최종 수정일
- 형식: RFC3339
- 예시: 2020-07-01T00:00:00Z
storageClassString스토리지 클래스 종류 (kr-central-2만 제공)
- standard(기본값): standard 클래스의 버킷
storagePolicyString스토리지 클래스의 존
acl ▼-버킷에 대한 접근 권한
- null 입력 시, 기존 ACL 설정 삭제
    publicString읽기 전용
- read-only만 작성 가능
    public_read_allow_ip_listList퍼블릭 접근 허용 IP
Status Code
HTTP Status응답 내용설명
200     OK성공
400Bad Request입력 설정 오류
401Unauthorized인증 실패
403Forbidden권한 없음

버킷 목록 조회

버킷 목록을 조회할 수 있습니다.

권한 안내

카카오클라우드의 IAM 역할에 따라, 버킷을 조회하기 위해서는 프로젝트 관리자 또는 프로젝트 멤버 역할이 필요합니다.

Request Syntax
버킷 목록 조회 Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket?limit=100' \
--header 'X-Auth-Token: {x-auth-token}'
API 호출 방식
메서드요청 URL
GET  https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket
Request Element
Path유형필수 여부설명
region_nameString필수  리전명
- kr-central-1 또는 kr-central-2
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Request Query
Request유형필수 여부설명
offsetQuery선택버킷 목록에서 오프셋부터 n개씩 가져옴
- 오프셋은 0부터 시작
- 기본값: 0
limitQuery선택목록 개수 제한
- 기본값: 20 (최대 100개까지 조회 가능)
prefixQuery선택Prefix로 버킷 이름 검색
includeQuery선택포함 문자열로 버킷 이름 검색
- Prefix와 같이 사용할 수 없음
typeQuery선택Type 검색 조건
- hot (kr-central-1)
- cold (kr-central-1)
- STANDARD (kr-central-2)
byQuery선택정렬 영역
- bucket_name: 버킷 이름
- bucket_type: 버킷의 타입
- created_at: 버킷 최종 수정일
- bytes_used: 버킷의 사용량
directQuery선택정렬 순서
- asc: 오름차순(기본값)
- desc: 내림차순
Response Syntax
버킷 목록 조회 Response Syntax
{
totalCount: int
offset: int
count: int
items: [SimpleBucket]
}
Response Elements
Response유형설명
totalCountInt   총 버킷 수
offsetInt버킷 목록에서 오프셋부터 n개씩 가져옴
- i 번째부터 i+n 번째까지
countInt반환된 버킷의 개수
itemsList버킷의 상세 정보
- Model - Simple Bucket 참고
Status Code
HTTP Status응답 내용설명
200     OK성공
401Unauthorized조회 권한 없음(토큰 오류)
403Forbidden조회 권한 없음

버킷 접근 관리

사용자가 소유한 버킷에 대한 접근을 관리할 수 있습니다. 다음 요청을 통해 사용자가 소유한 버킷에 대한 공공 접근이나 IP 리스트 기반의 접근 제어를 적용할 수 있습니다.

Request Syntax
IP 리스트 기반의 접근 제어 Request Syntax (kr-central-2)
curl --request POST --location 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
"name": "my-bucket-new",
"acl": {
"public": "read-only",
"public_read_allow_ip_list": [
"1.1.1.1",
"2.2.2.0/24"
]
}
}'
API 호출 방식
메서드요청 URL
POST   https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}
Path유형필수 여부설명
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-Token  String필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Request Elements
Request유형필수 여부설명
bucket_nameString필수  버킷 이름
acl ▼Structure필수  버킷에 대한 접근 권한
- null 입력 시, 기존 ACL 설정 삭제
    publicString선택퍼블릭 접근 허용 여부
- read-only: 허용함
- deny: 허용하지 않음 (acl = null과 동일)
    public_read_allow_ip_listList선택접근을 허용하는 IP 목록
Response Syntax
버킷 접근 관리 Response Syntax (kr-central-2)
{
"project": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
"account": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
"name": "my-bucket-new",
"type": "STANDARD",
"bytes": 0,
"objectCount": 0,
"createdAt": "2023-07-08T04:08:05Z",
"use_encryption": true,
"encryption_type": "managed",
"lastModified": "2023-07-08T04:08:05Z",
"storageClass": "STANDARD",
"storagePolicy": "default-placement",
"acl": {
"public": "deny",
"public_read_allow_ip_list": null
}
}
Response Elements
Response유형설명
account (Deprecated)StringProject ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID). 삭제 예정
projectStringProject ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
nameString생성된 버킷 이름
typeString생성된 버킷 타입
- STANDARD(기본값): standard 버킷
bytesString총 사용량- 단위: Byte
objectCountInt버킷의 오브젝트 개수
createdAtString생성일
- 형식: https://www.rfc-editor.org/rfc/rfc3339
- 예시: 2020-07-01T00:00:00Z
use_encryptionBoolean버킷 암호화 여부
- false(기본값): 암호화하지 않음
- true: 암호화 함
encryption_typeString버킷 암호화 타입
lastModifiedString최종 수정일
- 형식: https://www.rfc-editor.org/rfc/rfc3339
- 예시: 2020-07-01T00:00:00Z
storageClassString스토리지 클래스 종류
- STANDARD(기본값): standard 클래스의 버킷
storagePolicyString스토리지 클래스의 존
- default-placement(기본값)
acl ▼-버킷에 대한 접근 권한
- null 입력 시, 기존 ACL 설정 삭제
    publicString퍼블릭 접근 허용 여부
- read-only, deny
    public_read_allow_ip_listList퍼블릭 접근 허용 IP 리스트
Status Code
HTTP Status응답 내용설명
200     OK성공
401Unauthorized권한 없음 (TOKEN 오류)
403Forbidden수정 권한 없음
404Not found버킷을 찾을 수 없음

S3 버킷 접근 제어

S3 API를 이용한 버킷 접근 제어를 할 수 있습니다.

User ID 기반의 접근 관리 Request Syntax (kr-central-2)
curl --request POST --location 'https://objectstorage.kr-central-2.kakaocloud.com/{bucket_name}?acl' \
--header 'Authorization: {authorization}' \
--header 'Content-Type: application/xml' \
--header 'x-amz-acl: {Acl}' \
--header 'Content-MD5: {ContentMD5}' \
--header 'x-amz-grant-full-control: {GrantFullControl}' \
--header 'x-amz-grant-read: {GrantRead}' \
--header 'x-amz-grant-read-acp: {GrantReadACP}' \
--header 'x-amz-grant-write: {GrantWrite}' \
--header 'x-amz-grant-write-acp: {GrantWriteACP}' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AccessControlList>
<Grant>
<Grantee>
<ID>string</ID>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>'
API 호출 방식
메서드요청 URL
POST  https://objectstorage.kr-central-2.kakaocloud.com/{bucket_name}?acl
Path유형필수 여부설명
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
AuthorizationString필수  S3 authorization header
Content-TypeString필수  body content의 type - application/xml 이외의 입력은 parsing 오류가 발생할 수 있음
x-amz-aclString선택버킷에 적용할 canned ACL
- private : public 공개하지 않음. storage.owner를 제외한 모든 사용 허가 제거
- public-read: 모든 사용자에게 storage.objectReader 역할 부여
- public-read-write: 모든 사용자에게 storage.objectCreator 역할 부여
- authenticated-read: project에 허가된 사용자에게 storage.objectReader 역할 부여
Content-MD5String필수  base64로 암호화된 body의 128-bit MD5
x-amz-grant-full-controlString선택지정된 사용자에게 storage.admin 역할을 부여
- 사용자 ID와 AllUsers uri(http://acs.amazonaws.com/groups/global/AllUsers)만 제공
x-amz-grant-readString선택지정된 사용자에게 storage.objectReader 역할을 부여
- 사용자 ID와 AllUsers uri(http://acs.amazonaws.com/groups/global/AllUsers)만 제공
x-amz-grant-read-acpString선택지정된 사용자에게 storage.policyReader 역할을 부여
- 사용자 ID와 AllUsers uri(http://acs.amazonaws.com/groups/global/AllUsers)만 제공
x-amz-grant-writeString선택지정된 사용자에게 storage.objectCreator 역할을 부여
- 사용자 ID와 AllUsers uri(http://acs.amazonaws.com/groups/global/AllUsers)만 제공
x-amz-grant-write-acpString선택지정된 사용자에게 storage.policyWriter 역할을 부여
- 사용자 ID와 AllUsers uri(http://acs.amazonaws.com/groups/global/AllUsers)만 제공
Request Elements
Request유형필수 여부설명
bucket_nameString필수  버킷 이름
AccessControlPolicy ▼Structure선택
AccessControlList ▼Structure필수  버킷에 설정할 Access Control 리스트
Grant ▼List필수  
Grantee ▼Structure필수  권한을 부여받을 대상
IDString선택User ID
- 사용자를 대상으로 권한을 부여할 때 입력
- IDURI 중 하나는 입력이 되어야 함
URIString선택AllUsers 그룹에 권한을 부여할 때 입력
- http://acs.amazonaws.com/groups/global/AllUsers
- IDURI 중 하나는 입력이 되어야 함
PermissionString필수  부여할 권한의 종류
- FULL_CONTROL: storage.admin 역할
- WRITE: storage.objectCreator 역할
- WRITE-ACP: storage.policyWriter 역할
- READ: storage.objectReader 역할
- READ-ACP: storage.policyReader 역할
Status Code
HTTP Status응답 내용설명
200     OK성공
401Unauthorized권한 없음 (토큰 오류)
403Forbidden수정 권한 없음
404Not found버킷을 찾을 수 없음

버킷 삭제

사용자가 소유한 버킷을 삭제할 수 있습니다. 버킷 삭제를 위해서는 storage.buckets.delete 권한이 필요합니다.

  • 버킷 내에 오브젝트가 존재하는 경우에는 버킷을 삭제할 수 없습니다.
Request Syntax
버킷 삭제 Request Syntax
curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'
API 호출 방식
메서드요청 URL
DELETEhttps://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}
Request Element
Path유형필수 여부설명
region_nameString필수  리전 명
- kr-central-1 또는 kr-central-2
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Status Code
HTTP Status응답 내용설명
204     No Content삭제 성공
401Unauthorized인증 실패
404Not found버킷 찾을 수 없음
409Conflict버킷이 비어 있지 않음

버킷 및 오브젝트 일괄 삭제

삭제 권한이 있는 사용자는 프로젝트 내 버킷 및 오브젝트를 일괄 삭제할 수 있습니다.
입력된 리스트를 순차적으로 삭제하기 위해 시도하며, 각각의 삭제 결과를 하나의 Response Body로 반환합니다.

Request Syntax
일괄 삭제 Request Syntax (kr-central-1)
curl --request DELETE --location 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/?bulk-delete' \
--header 'X-Auth-Token: {X-Auth-Token}' \
--header 'Accept: application/json' \
--data 'exist-container/exist-objectexist-containernot-exist-bucketnot-empty-bucket'
API 호출 방식
메서드요청 URL
DELETEhttps://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/?bulk-delete
Request Element
Path유형필수 여부설명
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Request Body
유형필수 여부설명
String필수  삭제 대상 버킷 및 오브젝트 리스트
- Separator: new line
Response Syntax
Status Code
HTTP Status응답 내용설명
200    OK성공
400Bad Request잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
401Unauthorized인증 실패
403Forbidden권한 없음
409Conflict버킷 삭제 실패 (Not empty)

버킷 비우기

storage.objects.delete 권한이 있을 경우, 버킷 비우기를 통해 버킷 하위 모든 Object를 삭제할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

Request Syntax
버킷 비우기 Request Syntax (kr-central-2)
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'
API 호출 방식
메서드요청 URL
DELETEhttps://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete
Path유형필수 여부설명
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
directoryString선택하위 오브젝트를 삭제하려고 하는 디렉터리의 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Status Code
HTTP Status응답 내용설명
200    OK성공
400Bad Request잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
401Unauthorized인증 실패
403Forbidden권한 없음

버킷 폴더 비우기

storage.objects.delete 권한이 있을 경우, 버킷 폴더 비우기를 통해 지정된 path 이하의 모든 오브젝트를 삭제할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

Request Syntax
버킷 폴더 비우기 Request Syntax (kr-central-2)
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'
API 호출 방식
메서드요청 URL
DELETEhttps://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete
Path유형필수 여부설명
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
bucket_nameString필수  버킷 이름
directoryString선택하위 오브젝트를 삭제하려고 하는 디렉터리의 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Status Code
HTTP Status응답 내용설명
200    OK성공
400Bad Request잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
401Unauthorized인증 실패
403Forbidden권한 없음

버킷 메타 조회

storage.buckets.get 권한이 있을 경우, 버킷의 메타 정보를 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

버킷 메타 조회는 아래 GET, HEAD 메서드인 두 가지 방식으로 가능합니다.

Request Syntax
버킷 메타 조회(GET) Request Syntax (kr-central-2)
curl --location --request GET 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'
API 호출 방식
메서드요청 URL
GET   https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}
Path유형필수 여부설명
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Response Header
Request유형필수 여부설명
X-Container-Meta-*String필수  사용자 지정 Meta 정보
Response Elements
Response유형설명
projectstringProject ID
namestringbucket 이름
typestringbucket 타입
- STANDARD
bytesintbucket에 포함된 객체들의 총 용량
- 단, 30분마다 업데이트되며 현재 사용량과 차이가 있을 수 있음
objectCountintbucket에 포함된 객체들의 총 개수
- 단, 30분마다 업데이트되며 현재 개수와 차이가 있을 수 있음
createdAttimebucket 생성 일시
use_encryptionbooleanbucket의 암호화 여부
lastModifiedtimebucket의 최종 수정 일시
storageClassstring저장소 클래스 종류
- STANDARD
acl ▼List접근 관리 정책
     publicstring퍼블릭 접근 허용 여부
- read-only,deny
    public_read_allow_ip_liststring퍼블릭 액세스가 허용된 IP 리스트
- IP 리스트가 설정되어 있는 경우, 토큰이 없는 접근은 해당 IP만 가능
Status Code
HTTP Status응답 내용설명
200     Success성공
401Unauthorized인증 실패
403Forbidden권한 없음
404Not found버킷을 찾을 수 없음

버킷 메타 변경

storage.buckets.update 권한이 있을 경우, 버킷 메타 접근 권한을 가진 버킷의 메타 정보를 변경할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

Request Syntax
버킷 메타 변경 Request Syntax
curl --location --request POST 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'
API 호출 방식
메서드요청 URL
POST   https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}
Request Element
Path유형필수 여부설명
region_nameString필수  리전명
- kr-central-1 또는 kr-central-2
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
X-Object-Meta-{name}String필수  버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 {name}에 입력
Response Syntax
Status Code
HTTP Status응답 내용설명
200     Success성공
401Unauthorized권한 없음

버킷 CORS 정책

버킷 CORS 정책 설정

storage.buckets.setIamPolicy 권한이 있는 사용자는 개별 버킷에 대한 CORS 정책을 설정할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다. 버킷에 대한 새로운 CORS 설정 적용 시, 리스트 전체가 업데이트됩니다.

  • “cors” =[] 혹은 empty body 입력 시, 기존에 설정된 cors 내역이 삭제되며 기본 CORS 정책이 적용됩니다. 이 방법으로 설정된 CORS 설정은 아래 API에서만 작동합니다.

  • 아래 API 들은 해당 container에 PUT /v1_ext/bucket/:name/cors을 통해 설정된 CORS가 있는 경우, 그에 따른 결과를 반환할 수 있습니다.

    • /v1/:account/:container
    • /v1/:account/:container/*object
    • /:bucket (kr-central-2 s3 api)
    • /:bucket/*object (kr-central-2 s3 api)
안내

CORS 정책이 설정되지 않은 경우, 콘솔이 아닌 외부 도메인의 접근을 허용하지 않습니다.

Request Syntax
CORS 정책 설정 Request Syntax
curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
"cors": [
{
"allowed_origins": [
"https://www.example1.com"
],
"allowed_methods": [
"PUT",
"GET"
],
"allowed_headers": [
"*"
],
"expose_headers": [],
"max_age_seconds": 10
},
{
"allowed_origins": [
"https://www.example2.com"
],
"allowed_methods": [
"PUT",
"GET",
"DELETE"
],
"allowed_headers": [
"*"
],
"expose_headers": [
"X-Object-Meta-User-Defined"
],
"max_age_seconds": 10
}
]
}'
API 호출 방식
메서드요청 URL
POST   https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors
Path유형필수 여부설명
region_nameString필수  리전 명
- kr-central-1 또는 kr-central-2
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Request Elements
Request유형필수 여부설명
region_nameString필수  리전 명
- kr-central-1 또는 kr-central-2
cors ▼list필수  CORS 정책- 최대 설정할 수 있는 CORS 정책 수: 10개
    allowed_originsList필수  접근 허용하는 허용 origin
- http 혹은 https 등 protocol 포함
- 최대 1개의 *(와일드카드) 문자 포함
- origin 당 최대 입력 가능 길이: 200
- 포트를 명시할 수 있음
- 포트로 80이나 443을 프로토콜과 함께 명시하는 경우, 후에 입력되는 Origin Header가 프로토콜만 명시하고 포트를 명시하지 않은 경우 cors 허용 헤더가 반환되지 않음
    allowed_methodsList필수  접근 허용할 메서드
- PUT, POST, GET, DELETE
    allowed_headersList필수  접근 허용할 헤더
    expose_headersList필수  브라우저에 노출한 헤더
    max_age_secondsInt선택preflight request 결과를 캐싱하는 수명
- 미입력 시, 캐싱하지 않음
Response Syntax
CORS 정책 설정 Response Syntax
{
"cors": [
{
"allowed_origins": [
"https://www.example1.com"
],
"allowed_headers": [
"*"
],
"allowed_methods": [
"PUT",
"GET"
],
"expose_headers": [],
"max_age_seconds": 10
},
{
"allowed_origins": [
"https://www.example2.com"
],
"allowed_headers": [
"*"
],
"allowed_methods": [
"PUT",
"GET",
"DELETE"
],
"expose_headers": [
"X-Object-Meta-User-Defined"
],
"max_age_seconds": 10
}
]
}
Status Code
HTTP Status응답 내용설명
200OK성공
400Bad Request잘못된 요청 (잘못된 이름 규칙)
401Unauthorized인증 실패
403Forbidden권한 없음
404Not found버킷을 찾을 수 없음

버킷 CORS 정책 조회

storage.buckets.getIamPolicy 권한이 있을 경우, 개별 버킷에 대한 CORS 설정값을 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

Request Syntax
CORS 정책 조회 Request Syntax
curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json'
API 호출 방식
메서드요청 URL
GET  https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors
Request Element
Path유형필수 여부설명
region_nameString필수  리전 명
- kr-central-1 또는 kr-central-2
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Response Syntax
CORS 정책 조회 Response Syntax
{
"cors": [
{
"allowed_origins": [
"https://www.example1.com"
],
"allowed_headers": [
"*"
],
"allowed_methods": [
"PUT",
"GET"
],
"expose_headers": [],
"max_age_seconds": 10
},
{
"allowed_origins": [
"https://www.example2.com"
],
"allowed_headers": [
"*"
],
"allowed_methods": [
"PUT",
"GET",
"DELETE"
],
"expose_headers": [
"X-Object-Meta-User-Defined"
],
"max_age_seconds": 10
}
]
}
Response Elements
Request유형필수 여부설명
cors ▼List 필수  CORS 정책
- 최대 설정할 수 있는 CORS 정책 수: 10개
    allowed_originsList필수  접근 허용하는 허용 origin
- 최대 1개의 *(와일드 카드) 문자 포함
- origin 당 최대 입력 가능 길이: 200
    allowed_methodsList필수  접근 허용할 메서드(HTTP)
    allowed_headersList필수  접근 허용할 헤더
    expose_headersList필수  브라우저에 노출한 헤더
    max_age_secondsInt선택preflight request 결과를 캐싱하는 수명
Status Code
HTTP Status응답 내용설명
200OK성공
400Bad Request잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
401Unauthorized인증 실패
403Forbidden권한 없음

CORS Preflight 요청

버킷에 대한 CORS Preflight를 요청할 수 있습니다.

  • 하단의 API는 해당 container에 PUT /v1_ext/bucket/:name/cors을 통해 설정된 CORS가 있는 경우, 그에 따른 결과를 반환할 수 있습니다.
    • /v1/:account/:container
    • /v1/:account/:container/*object
    • /:bucket (kr-central-2 s3 api)
    • /:bucket/*object (kr-central-2 s3 api)
Request Syntax
CORS Preflight 요청 Request Syntax
curl --location --request OPTIONS 'http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/test.txt' \
--header 'Origin: https://www.example1.com' \
--header 'Access-Control-Request-Headers: X-Auth-Token,Content-Type' \
--header 'Access-Control-Request-Method: GET'
Request Element
Path유형필수 여부설명
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
API 호출 방식
메서드요청 URL
OPTIONS  https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name
- name: 버킷 이름
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy
- name: 버킷 이름
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy/:id
- name: 버킷 이름
- id: policy ID
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name
- account: Project ID
- name: 버킷 이름
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name/*object
- account: Project ID
- name: 버킷 이름
- *object: object path
OPTIONShttps://objectstorage.kr-central-2.kakaocloud.com/v1/:name
- name: 버킷 이름
OPTIONShttps://objectstorage.{region_name}.kakaocloud.com/v1/:name/*object
- name: 버킷 이름
- *object: object path
Request Header
Request유형필수 여부설명
OriginString필수  Origin
- Protocol과 Host, Port까지 모두 합친 서버의 위치
Access-Control-Request-HeadersList필수  예비 요청할 헤더의 리스트
- X-Auth-Token, Content-Type
Access-Control-Request-MethodList필수   예비 요청할 메서드의 리스트
- 예시: PUT, POST, GET, DELETE
Response Header
Response유형설명
Content-LengthIntBody 길이
Access-Control-Allow-CredentialsBoolean서로 다른 도메인 간 쿠키 공유를 허락하는 옵션
- true: 허용
- false: 허용하지 않음
Access-Control-Allow-HeadersString리소스에 접근 허용할 수 있는 HTTP 헤더
Access-Control-Allow-MethodsString리소스에 접근 허용할 수 있는 HTTP 메서드 지정
Access-Control-Allow-OriginString접근 허용이 가능한 오리진
Access-Control-Expose-HeadersString브라우저에 노출된 헤더
Access-Control-Max-AgeIntpreflight request 요청 결과를 캐시할 수 있는 시간
Response Syntax
CORS Preflight 요청 Response Syntax
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: PUT, GET
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Expose-Headers:
Access-Control-Max-Age: 10
Vary: Origin
Strict-Transport-Security: max-age=31536000; includeSubDomains
Status Code
HTTP Status응답 내용설명
200      OK성공
401Unauthorized인증 실패
403Forbidden권한 없음

CORS Preflight 외의 요청

Request를 기반으로 CORS 비교가 진행되며, CORS 설정에 맞지 않는 요청은 Access-Control-Allow-Header, Access-Control-Allow-Methods, Access-Control-Max-Age Header가 반환되지 않습니다. CORS 적용을 위해서는 반드시 헤더에 Origin이 설정되어 있어야 합니다.

Request Syntax
CORS Preflight 외의 요청 Request Syntax
curl --location --request GET 'http://objectstorage.{regoin_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Origin: https://www.example1.com'
API 호출 방식
메서드요청 URL
GET  http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}
Request Element
Path유형필수 여부설명
region_nameString필수  리전명
- kr-central-1 또는 kr-central-2
accountString필수  Project ID
- 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
- Swift API에서 Account 값으로 사용
bucket_nameString필수  버킷 이름
objectString필수  오브젝트 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
CORS Preflight 외의 요청 Response Header Syntax
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 10
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Allow-Methods: PUT, GET
Access-Control-Expose-Headers: {}
Etag: {ETag value}
Last-Modified: Thu, 07 Jul 2022 08:13:27 GMT
Vary: Origin
Response Elements
Response설명
Content-TypeContent-Type 개체 헤더는 리소스의 미디어 타입을 나타내기 위해 사용됨
Content-LengthContent-Length 개체 헤더는 수신자에게 보내지는 Byte 단위의 개체 본문 크기
Access-Control-Allow-Credentials서로 다른 도메인 간 쿠키 공유를 허락하는 옵션
- true: 허용
- false: 허용하지 않음
Access-Control-Allow-Origin접근 허용이 가능한 origin
Access-Control-Expose-Headers브라우저에 노출된 헤더
Etag오브젝트 고유의 해시 값
- ETag HTTP 응답 헤더는 특정 버전의 리소스를 식별하는 식별자
- 웹 서버가 내용 변경 확인 시 변경이 없다면 웹 서버로 full 요청을 보내지 않기에 효율적인 캐시 사용과 대역폭 절약 가능
- 변경이 있는 경우, “mid-air collisions(리소스 간의 동시다발적 수정 및 덮어쓰기 현상)”을 막는 데 유용하게 사용됨
Last-Modified최종 수정일
- Last-Modified 응답은 HTTP 헤더에 서버가 아는 가장 마지막 수정된 날짜와 시각을 담은 응답
Status Code
HTTP Status응답 내용설명
200     OK성공
401Unauthorized인증 실패
403Forbidden권한 없음

버킷 LifeCycle

버킷의 LifeCycle을 생성하고 관리하기 위해서는 storage.buckets.update 권한이 필요합니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.

버킷 LifeCycle 생성

버킷의 Life Cycle을 생성 시, 기존에 생성한 Life Cycle은 오버라이트됩니다. 따라서, 기존의 Life Cycle에서 일부만 업데이트해야 할 경우에는 전체 설정을 받아 필요한 부분만 수정 후 업데이트를 요청해야 합니다.

Request Syntax
버킷 LifeCycle 생성 Request Syntax
PUT /v1_ext/bucket/{bucket_name}/lifecycle
X-Auth-Token: {x-auth-token}

<?xml version="1.0"?>
<LifecycleConfiguration>
<Rule>
<ID>day1Rule</ID>
<Expiration>
<Days>1</Days>
</Expiration>
<Prefix>expire1/</Prefix>
<Status>Enabled</Status>
</Rule>
<Rule>
<ID>dateRule</ID>
<Expiration>
<Date>2023-06-10T00:00:00.000Z</Date>
</Expiration>
<Prefix>20230-06-08/</Prefix>
<Status>Enabled</Status>
</Rule>
</LifecycleConfiguration>
API 호출 방식
메서드요청 URL
PUT   https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle
Path유형필수 여부설명
bucket_nameString필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Request Body
Request유형필수 여부설명
Rule ▼List필수  Life Cycle 정책
    IDString선택Rule을 구분하는 ID
- 255자 이내의 고유한 문자열
Expiration ▼Structure필수  삭제에 대한 설정
- Date 혹은 Days 필드를 반드시 입력 필요
    DateTimestamp선택Object를 삭제할 날짜
- GMT ISO 8601 포맷인 2023-06-10T00:00:00.000Z만 입력 가능
    Daysinteger선택Object의 생명 주기
- 생성일 기준으로 설정된 날짜가 지나면 Object가 삭제됨
- 0이 아닌 양수만 입력만 가능
Filter ▼Structure선택Life Cycle이 적용될 Object의 조건을 명시
    PrefixString필수  Rule을 적용할 Object의 Prefix
- 다음의 특수 문자는 XML 엔티티 코드로 대체 필요
' → &apos;
→ &quot;
& → &amp;
< → &lt;
>&gt;
\r → &#13; 또는 &#x0D;
\n → &#10; 또는 &#x0A;

자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
    StatusString필수  Life Cycle 적용 여부
- Enabled : Life Cycle을 설정
- Disabled : Life Cycle을 미설정
Response Syntax
버킷 LifeCycle 생성 Response Syntax
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
<Rule>
<ID>day1Rule</ID>
<Expiration>
<Days>1</Days>
</Expiration>
<Prefix>expire1/</Prefix>
<Status>Enabled</Status>
</Rule>
<Rule>
<ID>dateRule</ID>
<Expiration>
<Date>2023-06-10T00:00:00.000Z</Date>
</Expiration>
<Prefix>20230-06-08/</Prefix>
<Status>Enabled</Status>
</Rule>
</LifecycleConfiguration>

Response Elements
Response유형설명
Rule ▼ListLife Cycle 정책
    IDstringRule을 구분하는 ID
- 255자 이내의 고유한 문자열
    PrefixstringRule을 적용할 Object의 Prefix
- 다음의 특수 문자는 XML 엔티티 코드로 대체됨

' → '
” → "
& → &
< → <
> → >
\r →   또는 
\n →   또는 

자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
    StatusstringLife Cycle 적용 여부
- Enabled: Life Cycle을 설정
- Disabled: Life Cycle을 미설정
    Expirationinteger삭제에 대한 설정
Status Code
HTTP Status응답 내용설명
200    OK성공
400Bad RequestConfiguration 설정값 오류
401Unauthorized인증 실패
403Forbidden권한 없음
404Not found버킷을 찾을 수 없음

버킷 LifeCycle 목록 조회

storage.buckets.update 권한이 있을 경우, Object Storage의 Life Cycle(수명 주기)을 생성하고 관리하여 객체 그룹에 적용할 일련의 수명 주기 규칙을 정의할 수 있습니다. 버킷의 Life Cycle을 통해 사용하지 않는 파일들을 삭제하여 저장 공간을 효율적으로 관리할 수 있습니다.

안내

Life Cycle의 Expiry Rule은 하루에 한 번, 즉 00시(자정)에 작동합니다. 만약, 객체가 만료되는 당일인 00시나 12시 이전에 Life Cycle 정책을 삭제하면 해당 정책은 그 즉시 적용되지 않습니다.

Request Syntax
버킷 Life Cycle 목록 조회 Request Syntax (kr-central-2)
curl --location --request GET 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'
API 호출 방식
메서드요청 URL
GET   https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle
Path유형필수 여부설명
bucket_namestring필수  버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
버킷 Life Cycle 목록 조회 Response Syntax (kr-central-2)
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
<Rule>
<ID>day1Rule</ID>
<Expiration>
<Days>1</Days>
</Expiration>
<Prefix>expire1/</Prefix>
<Status>Enabled</Status>
</Rule>
<Rule>
<ID>dateRule</ID>
<Expiration>
<Date>2023-06-10T00:00:00.000Z</Date>
</Expiration>
<Prefix>20230-06-08/</Prefix>
<Status>Enabled</Status>
</Rule>
</LifecycleConfiguration>
Response Elements
Response유형설명
Rule ▼ListLife Cycle 정책
     IDstringRule을 구분하는 ID
- 255자 이내의 고유한 문자열
     PrefixstringRule을 적용할 Object의 Prefix
- 다음의 특수 문자는 XML 엔티티 코드로 대체됨

' → &apos;
→ &quot;
& → &amp;
< → &lt;
>&gt;
\r → &#13; 또는 &#x0D;
\n → &#10; 또는 &#x0A;

자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
     StatusstringLife cycle 적용 여부
- Enabled : Life Cycle을 설정
- Disabled : Life Cycle을 미설정
     Expirationinteger삭제에 대한 설정
Status Code
HTTP Status응답 내용설명
200     Success성공
400Bad RequestConfiguration 설정값 오류
401Unauthorized인증 실패
403Forbidden권한 없음
404Not Found버킷이 없음

버킷 LifeCycle 삭제

LifeCycle 접근 권한을 가진 사용자는 버킷의 LifeCycle을 삭제할 수 있습니다.

Request Syntax
버킷 LifeCycle 삭제 Request Syntax (kr-central-2)
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'
API 호출 방식
메서드요청 URL
DELETEhttps://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle
Path필수 여부유형설명
bucket_name필수  String버킷 이름
Request Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Status Code
HTTP Status응답 내용설명
200    OK성공
400Bad RequestConfiguration 설정값 오류
401Unauthorized인증 실패
403Forbidden권한 없음
404Not found버킷을 찾을 수 없음