본문으로 건너뛰기

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
- 사용자를 대상으로 권한을 부여할 때 입력
- ID와 URI 중 하나는 입력이 되어야 함
URIString선택AllUsers 그룹에 권한을 부여할 때 입력
- http://acs.amazonaws.com/groups/global/AllUsers
- ID와 URI 중 하나는 입력이 되어야 함
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버킷을 찾을 수 없음
최종 수정: 에