Bucket
Object Storage의 Bucket API를 사용하여 버킷의 생성과 관련 정보 및 정책을 관리할 수 있습니다.
API 사용 준비
- API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.
- Object Storage의 API Model에 대한 설명은 API 모델 문서를 참고하시기 바랍니다.
API 엔드포인트 URL
API 요청을 위한 Object Storage API 엔드포인트 URL은 다음과 같습니다.
- kr-central-1
- kr-central-2
https://objectstorage.kr-central-1.kakaocloud.com
https://objectstorage.kr-central-2.kakaocloud.com
버킷 생성
버킷을 생성합니다.
카카오클라우드의 IAM 역할에 따라, 버킷을 생성하기 위해서는 프로젝트 관리자 또는 프로젝트 멤버 역할이 필요합니다.
- kr-central-1
- kr-central-2
Request Syntax
curl --request PUT --location 'https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/bucket' \
--header 'X-Auth-Token: {x-auth-token}' \--header 'Content-Type: application/json' \
--data '{
"name": "my-bucket-new",
"type": "hot",
"use_encryption": true
}'
API 호출 방식
메서드 | 요청 URL |
---|---|
PUT | https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/bucket |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰을 입력 |
Content-Type | String | 필수 | application/json 으로 고정 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name | String | 필수 | 버킷 이름 |
type | String | 필수 | 버킷 유형 - hot (기본값): hot 버킷- cold (지원 예정): cold 버킷 |
use_encryption | Boolean | 선택 | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
Response Syntax
{
name: String
type: String
use_encryption: boolean
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 유형 - hot (기본값): hot 버킷- cold (지원 예정): cold 버킷 |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 bucket_name 이 이미 존재 |
Request Syntax
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-Token | String | 필수 | 사용자 인증 토큰을 입력 |
Content-Type | String | 필수 | application/json 으로 고정 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name | String | 필수 | 버킷 이름 |
type | String | 필수 | 버킷 유형 - Standard (기본값): standard 버킷 |
use_encryption | Boolean | 선택 | 버킷 암호화 여부encryption_configuration 설정을 입력하는 경우 입력값이 무시됨- false (기본값): 암호화하지 않음 - true : 암호화 함 (encryption_configuration.type = managed와 동일) |
encryption_configuration ▼ | Structure | 선택 | 버킷 암호화 설정 |
type | String | 필수 | 암호화 방법 - managed (기본값): 사바에서 제공하는 자동 암호화- true (지원 예정): KMS를 이용한 키 관리 서비스와 연계한 암호화 |
Response Syntax
{
"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) | String | 프로젝트 ID - Swift API에서 Account 값. 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) |
project | String | 프로젝트 ID |
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 유형 - STANDARD (기본값): standard 버킷 |
bytes | String | 총 사용량 - 단위: Byte |
objectCount | Int | 버킷의 오브젝트 개수 |
createdAt | String | 생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
encryption_type | String | 버킷 암호화 유형 |
lastModified | String | 최종 수정일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
storageClass | String | 스토리지 클래스 종류 - STANDARD (기본값): standard 클래스의 버킷 |
storagePolicy | String | 스토리지 클래스의 존 - default-placement (기본값) |
acl ▼ | - | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제 |
public | String | 퍼블릭 접근 허용 여부 - read-only , deny |
public_read_allow_ip_list | List | 퍼블릭 접근 허용 IP 리스트 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 입력 설정 오류 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 bucket_name 이 이미 존재 |
버킷 관리
버킷 상세 조회
storage.buckets.get 권한이 있을 경우, 특정 버킷에 대한 상세 정보를 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
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_name | String | 필수 | 리전명 - kr-central-1 또는 kr-central-2 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰을 입력 |
Response Syntax
Bucket의 API 모델에 대한 자세한 설명은 Bucket API Model을 참고하시기 비랍니다.
- kr-central-1
- kr-central-2
{
"account": "account-id",
"name": "test_bucket",
"type": "hot",
"bytes": 1073741824,
"objectCount": 1,
"policyCount": 0,
"createdAt": "2022-04-25T10:28:57Z",
"owner": {
"id": "user-id",
"name": "test_user@kakaoenterprise.com"
},
"acl": {
"permissions": null,
"public": "read-only",
"public_read_allow_ip_list": [
"ip / cidr"
]
},
"lastModified": "2022-04-25T10:28:57Z",
"use_encryption": false
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
account | String | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 유형 - hot (기본값): hot 버킷- cold (지원 예정): cold 버킷 |
bytes | String | 총 사용량 - 단위: Byte |
objectCount | Int | 버킷의 오브젝트 개수 |
policyCount | Int | 해당 버킷의 라이프사이클이 적용된 정책의 개수 (kr-central-1만 제공) |
createdAt | String | 생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
owner ▼ | - | 버킷 생성자 |
id | String | 버킷 생성자의 ID |
name | String | 버킷 생성자의 이름 |
acl ▼ | - | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정을 삭제 |
public | String | 읽기 전용 - read-only 만 작성 가능 |
public_read_allow_ip_list | List | 퍼블릭 접근 허용 IP |
lastModified | String | 최종 수정일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화함 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 bucket_name 이 이미 존재 |
{
"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 | 유형 | 설명 |
---|---|---|
project | String | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - S3 API에서 사용 |
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 유형 - standard (기본값): standard 버킷 |
bytes | String | 총 사용량 - 단위: Byte |
objectCount | Int | 버킷의 오브젝트 개수 |
createdAt | String | 생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
encryption_type | String | 버킷 암호화 유형 |
lastModified | String | 최종 수정일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
storageClass | String | 스토리지 클래스 종류 (kr-central-2만 제공) - standard (기본값): standard 클래스의 버킷 |
storagePolicy | String | 스토리지 클래스의 존 |
acl ▼ | - | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제 |
public | String | 읽기 전용 - read-only 만 작성 가능 |
public_read_allow_ip_list | List | 퍼블릭 접근 허용 IP |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 입력 설정 오류 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷 목록 조회
버킷 목록을 조회할 수 있습니다.
카카오클라우드의 IAM 역할에 따라, 버킷을 조회하기 위해서는 프로젝트 관리자 또는 프로젝트 멤버 역할이 필요합니다.
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_name | String | 필수 | 리전명 - kr-central-1 또는 kr-central-2 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Request Query
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
offset | Query | 선택 | 버킷 목록에서 오프셋부터 n개씩 가져옴 - 오프셋은 0부터 시작 - 기본값: 0 |
limit | Query | 선택 | 목록 개수 제한 - 기본값: 20 (최대 100개까지 조회 가능) |
prefix | Query | 선택 | Prefix로 버킷 이름 검색 |
include | Query | 선택 | 포함 문자열로 버킷 이름 검색 - Prefix와 같이 사용할 수 없음 |
type | Query | 선택 | Type 검색 조건 - hot (kr-central-1)- cold (kr-central-1)- STANDARD (kr-central-2) |
by | Query | 선택 | 정렬 영역 - bucket_name : 버킷 이름- bucket_type : 버킷의 유형- created_at : 버킷 최종 수정일- bytes_used : 버킷의 사용량 |
direct | Query | 선택 | 정렬 순서 - asc : 오름차순(기본값)- desc : 내림차순 |
Response Syntax
{
totalCount: int
offset: int
count: int
items: [SimpleBucket]
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
totalCount | Int | 총 버킷 수 |
offset | Int | 버킷 목록에서 오프셋부터 n개씩 가져옴 - i 번째부터 i+n 번째까지 |
count | Int | 반환된 버킷의 개수 |
items | List | 버킷의 상세 정보 - Model - Simple Bucket 참고 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 조회 권한 없음(토큰 오류) |
403 | Forbidden | 조회 권한 없음 |
버킷 접근 관리
- kr-central-1
- kr-central-2
사용자가 소유한 버킷에 대한 공공 접근이나 IP 리스트 기반의 접근 제어를 적용할 수 있습니다.
Request Syntax
curl --request POST --location 'https://objectstorage.kr-central-1.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-1.kakaocloud.com/v1_ext/bucket/{bucket_name} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Content-Type | String | 필수 | application/json 으로 고정 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
acl ▼ | Structure | 필수 | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제 |
public | String | 선택 | 퍼블릭 접근 허용 여부 - read-only : 허용함 - deny : 허용하지 않음 (acl = null 과 동일) |
public_read_allow_ip_list | List | 선택 | 접근을 허용할 IP 목록 |
Response Syntax
{
name: String
ownerId: String
acl: AccessControlList
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
name | String | 버킷 이름 |
ownerId | String | 버킷 소유자 ID (deprecated) - 현재는 소유자의 별도 권한이 존재하지 않음 |
acl | List | 접근 권한 설정 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
사용자가 소유한 버킷에 대한 접근을 관리할 수 있습니다. 다음 요청을 통해 사용자가 소유한 버킷에 대한 공공 접근이나 IP 리스트 기반의 접근 제어를 적용할 수 있습니다.
Request Syntax
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_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Content-Type | String | 필수 | application/json 으로 고정 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
acl ▼ | Structure | 필수 | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제 |
public | String | 선택 | 퍼블릭 접근 허용 여부 - read-only : 허용함- deny : 허용하지 않음 (acl = null과 동일) |
public_read_allow_ip_list | List | 선택 | 접근을 허용하는 IP 목록 |
Response Syntax
{
"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) | String | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID). 삭제 예정 |
project | String | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) |
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 유형 - STANDARD (기본값): standard 버킷 |
bytes | String | 총 사용량- 단위: Byte |
objectCount | Int | 버킷의 오브젝트 개수 |
createdAt | String | 생성일 - 형식: https://www.rfc-editor.org/rfc/rfc3339 - 예시: 2020-07-01T00:00:00Z |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
encryption_type | String | 버킷 암호화 유형 |
lastModified | String | 최종 수정일 - 형식: https://www.rfc-editor.org/rfc/rfc3339 - 예시: 2020-07-01T00:00:00Z |
storageClass | String | 스토리지 클래스 종류 - STANDARD (기본값): standard 클래스의 버킷 |
storagePolicy | String | 스토리지 클래스의 존 - default-placement (기본값) |
acl ▼ | - | 버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제 |
public | String | 퍼블릭 접근 허용 여부 - read-only , deny |
public_read_allow_ip_list | List | 퍼블릭 접근 허용 IP 리스트 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 (TOKEN 오류) |
403 | Forbidden | 수정 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
S3 버킷 접근 제어
S3 API를 이용한 버킷 접근 제어를 할 수 있습니다.
- kr-central-1
- kr-central-2
kr-central-1에서는 지원하지 않습니다.
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_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Authorization | String | 필수 | S3 authorization header |
Content-Type | String | 필수 | body content의 type - application/xml 이외의 입력은 parsing 오류가 발생할 수 있음 |
x-amz-acl | String | 선택 | 버킷에 적용할 canned ACL - private : public 공개하지 않음. storage.owner를 제외한 모든 사용 허가 제거- public-read : 모든 사용자에게 storage.objectReader 역할 부여- public-read-write : 모든 사용자에게 storage.objectCreator 역할 부여- authenticated-read : project에 허가된 사용자에게 storage.objectReader 역할 부여 |
Content-MD5 | String | 필수 | base64로 암호화된 body의 128-bit MD5 |
x-amz-grant-full-control | String | 선택 | 지정된 사용자에게 storage.admin 역할을 부여 - 사용자 ID와 AllUsers uri( http://acs.amazonaws.com/groups/global/AllUsers )만 제공 |
x-amz-grant-read | String | 선택 | 지정된 사용자에게 storage.objectReader 역할을 부여 - 사용자 ID와 AllUsers uri( http://acs.amazonaws.com/groups/global/AllUsers )만 제공 |
x-amz-grant-read-acp | String | 선택 | 지정된 사용자에게 storage.policyReader 역할을 부여 - 사용자 ID와 AllUsers uri( http://acs.amazonaws.com/groups/global/AllUsers )만 제공 |
x-amz-grant-write | String | 선택 | 지정된 사용자에게 storage.objectCreator 역할을 부여 - 사용자 ID와 AllUsers uri( http://acs.amazonaws.com/groups/global/AllUsers )만 제공 |
x-amz-grant-write-acp | String | 선택 | 지정된 사용자에게 storage.policyWriter 역할을 부여 - 사용자 ID와 AllUsers uri( http://acs.amazonaws.com/groups/global/AllUsers )만 제공 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
AccessControlPolicy ▼ | Structure | 선택 | |
AccessControlList ▼ | Structure | 필수 | 버킷에 설정할 Access Control 리스트 |
Grant ▼ | List | 필수 | |
Grantee ▼ | Structure | 필수 | 권한을 부여받을 대상 |
ID | String | 선택 | User ID - 사용자를 대상으로 권한을 부여할 때 입력 - ID 와 URI 중 하나는 입력이 되어야 함 |
URI | String | 선택 | AllUsers 그룹에 권한을 부여할 때 입력 - http://acs.amazonaws.com/groups/global/AllUsers - ID 와 URI 중 하나는 입력이 되어야 함 |
Permission | String | 필수 | 부여할 권한의 종류 - FULL_CONTROL : storage.admin 역할- WRITE : storage.objectCreator 역할- WRITE-ACP : storage.policyWriter 역할- READ : storage.objectReader 역할- READ-ACP : storage.policyReader 역할 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 (토큰 오류) |
403 | Forbidden | 수정 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
버킷 삭제
사용자가 소유한 버킷을 삭제할 수 있습니다. 버킷 삭제를 위해서는 storage.buckets.delete 권한이 필요합니다.
- 버킷 내에 오브젝트가 존재하는 경우에는 버킷을 삭제할 수 없습니다.
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 |
---|---|
DELETE | https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name} |
Request Element
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
region_name | String | 필수 | 리전 명 - kr-central-1 또는 kr-central-2 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
204 | No Content | 삭제 성공 |
401 | Unauthorized | 인증 실패 |
404 | Not found | 버킷 찾을 수 없음 |
409 | Conflict | 버킷이 비어 있지 않음 |
버킷 및 오브젝트 일괄 삭제
삭제 권한이 있는 사용자는 프로젝트 내 버킷 및 오브젝트를 일괄 삭제할 수 있습니다.
입력된 리스트를 순차적으로 삭제하기 위해 시도하며, 각각의 삭제 결과를 하나의 Response Body로 반환합니다.
- kr-central-1
- kr-central-2
Request Syntax
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 |
---|---|
DELETE | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/?bulk-delete |
Request Element
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Request Body
유형 | 필수 여부 | 설명 |
---|---|---|
String | 필수 | 삭제 대상 버킷 및 오브젝트 리스트 - Separator: new line |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음) |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
409 | Conflict | 버킷 삭제 실패 (Not empty) |
추후 지원 예정입니다.
버킷 비우기
storage.objects.delete 권한이 있을 경우, 버킷 비우기를 통해 버킷 하위 모든 Object를 삭제할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
- kr-central-1
- kr-central-2
kr-central-1에서는 지원하지 않습니다.
Request Syntax
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 |
---|---|
DELETE | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
directory | String | 선택 | 하위 오브젝트를 삭제하려고 하는 디렉터리의 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음) |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷 폴더 비우기
storage.objects.delete 권한이 있을 경우, 버킷 폴더 비우기를 통해 지정된 path 이하의 모든 오브젝트를 삭제할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
- kr-central-1
- kr-central-2
kr-central-1에서는 지원하지 않습니다.
Request Syntax
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 |
---|---|
DELETE | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
directory | String | 선택 | 하위 오브젝트를 삭제하려고 하는 디렉터리의 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음) |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷 메타 조회
storage.buckets.get 권한이 있을 경우, 버킷의 메타 정보를 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
- kr-central-1
- kr-central-2
Request Syntax
curl --location --request HEAD 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'
API 호출 방식
메서드 | 요청 URL |
---|---|
HEAD | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 권한 없음 |
버킷 메타 조회는 아래 GET, HEAD 메서드인 두 가지 방식으로 가능합니다.
- GET 방식
- HEAD 방식
Request Syntax
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_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
Response Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Container-Meta-* | String | 필수 | 사용자 지정 Meta 정보 |
Response Elements
Response | 유형 | 설명 |
---|---|---|
project | string | 프로젝트 ID |
name | string | bucket 이름 |
type | string | bucket 유형 - STANDARD |
bytes | int | bucket에 포함된 객체들의 총 용량 - 단, 30분마다 업데이트되며 현재 사용량과 차이가 있을 수 있음 |
objectCount | int | bucket에 포함된 객체들의 총 개수 - 단, 30분마다 업데이트되며 현재 개수와 차이가 있을 수 있음 |
createdAt | time | bucket 생성 일시 |
use_encryption | boolean | bucket의 암호화 여부 |
lastModified | time | bucket의 최종 수정 일시 |
storageClass | string | 저장소 클래스 종류 - STANDARD |
acl ▼ | List | 접근 관리 정책 |
public | string | 퍼블릭 접근 허용 여부 - read-only ,deny |
public_read_allow_ip_list | string | 퍼블릭 액세스가 허용된 IP 리스트 - IP 리스트가 설정되어 있는 경우, 토큰이 없는 접근은 해당 IP만 가능 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
Request Syntax
curl --location --request HEAD 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'
API 호출 방식
메서드 | 요청 URL |
---|---|
HEAD | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
Response Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Container-Meta-* | String | 필수 | 사용자 지정 Meta 정보 |
Response Elements
Response | 유형 | 설명 |
---|---|---|
Date | time | bucket 생성 일시 request 요청 시간 |
X-Container-Bytes-Used | int | bucket에 포함된 객체들의 총 용량 - 단, 30분마다 업데이트되며 현재 사용량과 차이가 있을 수 있음 |
X-Container-Bytes-Used-Actual | int | backend storage block 할당 사이즈 |
X-Container-Object-Count | int | bucket에 포함된 객체들의 총 개수 - 단, 30분마다 업데이트되며 현재 개수와 차이가 있을 수 있음 |
X-Storage-Class | string | 저장소 클래스 종류 - STANDARD |
X-Storage-Policy | string | 저장소에 적용되는 정책 - default-placement |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
버킷 메타 변경
storage.buckets.update 권한이 있을 경우, 버킷 메타 접근 권한을 가진 버킷의 메타 정보를 변경할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
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_name | String | 필수 | 리전명 - kr-central-1 또는 kr-central-2 |
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
X-Object-Meta-{name} | String | 필수 | 버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 {name} 에 입력 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 권한 없음 |
버킷 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
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_name | String | 필수 | 리전 명 - kr-central-1 또는 kr-central-2 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Content-Type | String | 필수 | application/json 으로 고정 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
region_name | String | 필수 | 리전 명 - kr-central-1 또는 kr-central-2 |
cors ▼ | list | 필수 | CORS 정책- 최대 설정할 수 있는 CORS 정책 수: 10개 |
allowed_origins | List | 필수 | 접근 허용하는 허용 origin - http 혹은 https 등 protocol 포함 - 최대 1개의 * (와일드카드) 문자 포함- origin 당 최대 입력 가능 길이: 200 - 포트를 명시할 수 있음 - 포트로 80이나 443을 프로토콜과 함께 명시하는 경우, 후에 입력되는 Origin Header가 프로토콜만 명시하고 포트를 명시하지 않은 경우 cors 허용 헤더가 반환되지 않음 |
allowed_methods | List | 필수 | 접근 허용할 메서드 - PUT , POST , GET , DELETE 등 |
allowed_headers | List | 필수 | 접근 허용할 헤더 |
expose_headers | List | 필수 | 브라우저에 노출한 헤더 |
max_age_seconds | Int | 선택 | preflight request 결과를 캐싱하는 수명 - 미입력 시, 캐싱하지 않음 |
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
}
]
}
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 잘못된 요청 (잘못된 이름 규칙) |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
버킷 CORS 정책 조회
storage.buckets.getIamPolicy 권한이 있을 경우, 개별 버킷에 대한 CORS 설정값을 조회할 수 있습니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
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_name | String | 필수 | 리전 명 - kr-central-1 또는 kr-central-2 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Content-Type | String | 필수 | application/json 으로 고정 |
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_origins | List | 필수 | 접근 허용하는 허용 origin - 최대 1개의 * (와일드 카드) 문자 포함- origin 당 최대 입력 가능 길이: 200 |
allowed_methods | List | 필수 | 접근 허용할 메서드(HTTP ) |
allowed_headers | List | 필수 | 접근 허용할 헤더 |
expose_headers | List | 필수 | 브라우저에 노출한 헤더 |
max_age_seconds | Int | 선택 | preflight request 결과를 캐싱하는 수명 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음) |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
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
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 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
API 호출 방식
메서드 | 요청 URL |
---|---|
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name - name: 버킷 이름 |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy - name: 버킷 이름 |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy/:id - name: 버킷 이름 - id: policy ID |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name - account: 프로젝트 ID - name: 버킷 이름 |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name/*object - account: 프로젝트 ID - name: 버킷 이름 - *object: object path |
OPTIONS | https://objectstorage.kr-central-2.kakaocloud.com/v1/:name - name: 버킷 이름 |
OPTIONS | https://objectstorage.{region_name}.kakaocloud.com/v1/:name/*object - name: 버킷 이름 - *object: object path |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Origin | String | 필수 | Origin - Protocol과 Host, Port까지 모두 합친 서버의 위치 |
Access-Control-Request-Headers | List | 필수 | 예비 요청할 헤더의 리스트 - X-Auth-Token , Content-Type |
Access-Control-Request-Method | List | 필수 | 예비 요청할 메서드의 리스트 - 예시: PUT , POST , GET , DELETE |
Response Header
Response | 유형 | 설명 |
---|---|---|
Content-Length | Int | Body 길이 |
Access-Control-Allow-Credentials | Boolean | 서로 다른 도메인 간 쿠키 공유를 허락하는 옵션 - true : 허용- false : 허용하지 않음 |
Access-Control-Allow-Headers | String | 리소스에 접근 허용할 수 있는 HTTP 헤더 |
Access-Control-Allow-Methods | String | 리소스에 접근 허용할 수 있는 HTTP 메서드 지정 |
Access-Control-Allow-Origin | String | 접근 허용이 가능한 오리진 |
Access-Control-Expose-Headers | String | 브라우저에 노출된 헤더 |
Access-Control-Max-Age | Int | preflight request 요청 결과를 캐시할 수 있는 시간 |
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
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
CORS Preflight 외의 요청
Request를 기반으로 CORS 비교가 진행되며, CORS 설정에 맞지 않는 요청은 Access-Control-Allow-Header
, Access-Control-Allow-Methods
, Access-Control-Max-Age Header
가 반환되지 않습니다. CORS 적용을 위해서는 반드시 헤더에 Origin
이 설정되어 있어야 합니다.
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_name | String | 필수 | 리전명 - kr-central-1 또는 kr-central-2 |
account | String | 필수 | 프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용 |
bucket_name | String | 필수 | 버킷 이름 |
object | String | 필수 | 오브젝트 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response 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-Type | Content-Type 개체 헤더는 리소스의 미디어 유형을 나타내기 위해 사용됨 |
Content-Length | Content-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 헤더에 서버가 아는 가장 마지막 수정된 날짜와 시각을 담은 응답 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷 LifeCycle
버킷의 LifeCycle을 생성하고 관리하기 위해서는 storage.buckets.update 권한이 필요합니다. Object Storage의 자세한 권한은 권한 관리를 참고하시기 바랍니다.
버킷 LifeCycle 생성
- kr-central-1
- kr-central-2
버킷의 라이프사이클을 생성할 수 있습니다.
Request Syntax
{
"target" : String // 적용 Prefix 값
"duration" : int // Policy 적용일, Day 기준. 예시: 30일 이후 적용
}
curl --location --request PUT 'https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/bucket/{bucket_name}/policy' \
--header 'X-Auth-Token: {X-Auth-Token}' \
--data-raw ' {
"target" : "test-target",
"duration" : 60
}'
API 호출 방식
메서드 | 요청 URL |
---|---|
PUT | https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/{bucket_name}/policy |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Request Elements
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
PolicyCreateRequest | Raw-data | 필수 | 정책 항목 |
Response Syntax
{
"policies": [
{
"id": 26,
"target": "test-test-",
"createdAt": "2021-03-24T01:27:38Z",
"duration": 60
},
]
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
policies ▼ | List | 라이프 사이클 정책 |
id | Integer | 정책 ID |
target | String | 대상 객체 |
createdAt | String | 생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
duration | Int | 유지 기간 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷의 Life Cycle을 생성 시, 기존에 생성한 Life Cycle은 오버라이트됩니다. 따라서, 기존의 Life Cycle에서 일부만 업데이트해야 할 경우에는 전체 설정을 받아 필요한 부분만 수정 후 업데이트를 요청해야 합니다.
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_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Request Body
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
Rule ▼ | List | 필수 | Life Cycle 정책 |
ID | String | 선택 | Rule을 구분하는 ID - 255자 이내의 고유한 문자열 |
Expiration ▼ | Structure | 필수 | 삭제에 대한 설정 - Date 혹은 Days 필드를 반드시 입력 필요 |
Date | Timestamp | 선택 | Object를 삭제할 날짜 - GMT ISO 8601 포맷인 2023-06-10T00:00:00.000Z 만 입력 가능 |
Days | integer | 선택 | Object의 생명 주기 - 생성일 기준으로 설정된 날짜가 지나면 Object가 삭제됨 - 0이 아닌 양수만 입력만 가능 |
Filter ▼ | Structure | 선택 | Life Cycle이 적용될 Object의 조건을 명시 |
Prefix | String | 필수 | Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체 필요 ' → &apos ; ” → " ; & → & < → < > → > \r → 또는 
 \n → 또는 
 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고 |
Status | String | 필수 | Life Cycle 적용 여부 - Enabled : Life Cycle을 설정 - Disabled : Life Cycle을 미설정 |
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 ▼ | List | Life Cycle 정책 |
ID | string | Rule을 구분하는 ID - 255자 이내의 고유한 문자열 |
Prefix | string | Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체됨 ' → ' ” → " & → & < → < > → > \r → 또는 \n → 또는 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고 |
Status | string | Life Cycle 적용 여부 - Enabled : Life Cycle을 설정 - Disabled : Life Cycle을 미설정 |
Expiration | integer | 삭제에 대한 설정 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | Configuration 설정값 오류 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |
버킷 LifeCycle 목록 조회
storage.buckets.update 권한이 있을 경우, Object Storage의 Life Cycle(수명 주기)을 생성하고 관리하여 객체 그룹에 적용할 일련의 수명 주기 규칙을 정의할 수 있습니다. 버킷의 Life Cycle을 통해 사용하지 않는 파일들을 삭제하여 저장 공간을 효율적으로 관리할 수 있습니다.
- kr-central-1
- kr-central-2
Life Cycle의 Expiry Rule은 하루에 두 번, 즉 00시(자정)와 12시(정오)에 작동합니다. 만약, 객체가 만료되는 당일인 00 시나 12시 이전에 Life Cycle 정책을 삭제하면 해당 정책은 그 즉시 적용되지 않습니다.
Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-1.kakaocloud.com/v1/bucket/{bucket_name}/policy' \
--header 'X-Auth-Token: {X-Auth-Token}' \
API 호출 방식
메서드 | 요청 URL |
---|---|
GET | https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/{bucket_name}/policy |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
bucket_name | String | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
{
"policies": [
{
"id": 26,
"target": "test-test-",
"createdAt": "2021-03-24T01:27:38Z",
"duration": 60
},
]
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
policies ▼ | List | 라이프 사이클 정책 |
id | Integer | 정책 ID |
target | String | 대상 객체 |
createdAt | String | 생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z |
duration | Int | 유지 기간 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
Life Cycle의 Expiry Rule은 하루에 한 번, 즉 00시(자정)에 작동합니다. 만약, 객체가 만료되는 당일인 00시나 12시 이전에 Life Cycle 정책을 삭제하면 해당 정책은 그 즉시 적용되지 않습니다.
Request Syntax
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_name | string | 필수 | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
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 ▼ | List | Life Cycle 정책 |
ID | string | Rule을 구분하는 ID - 255자 이내의 고유한 문자열 |
Prefix | string | Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체됨 ' → ' ” → " & → & < → < > → > \r → 또는 
 \n → 또는 
 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고 |
Status | string | Life cycle 적용 여부 - Enabled : Life Cycle을 설정 - Disabled : Life Cycle을 미설정 |
Expiration | integer | 삭제에 대한 설정 |
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
400 | Bad Request | Configuration 설정값 오류 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not Found | 버킷이 없음 |
버킷 LifeCycle 삭제
LifeCycle 접근 권한을 가진 사용자는 버킷의 LifeCycle을 삭제할 수 있습니다.
- kr-central-1
- kr-central-2
Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/bucket/{bucket_name}/policy/{policy_id}' \
--header 'X-Auth-Token: {X-Auth-Token}'
API 호출 방식
메서드 | 요청 URL |
---|---|
DELETE | https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/bucket/{bucket_name}/policy/{policy_id} |
Path | 필수 여부 | 유형 | 설명 |
---|---|---|---|
bucket_name | 필수 | String | 버킷 이름 |
policy_id | 필수 | Integer | 정책 ID |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
204 | No Content | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
Request Syntax
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 |
---|---|
DELETE | https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle |
Path | 필수 여부 | 유형 | 설명 |
---|---|---|---|
bucket_name | 필수 | String | 버킷 이름 |
Request Header
Request | 유형 | 필수 여부 | 설명 |
---|---|---|---|
X-Auth-Token | String | 필수 | 사용자 인증 토큰 |
Response Syntax
상태 코드
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | Configuration 설정값 오류 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |