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
Object Storage API 엔드포인트 URL 형식
https://objectstorage.kr-central-1.kakaocloud.com
Object Storage API 엔드포인트 URL 형식
https://objectstorage.kr-central-2.kakaocloud.com
버킷 생성
버킷을 생성합니다.
권한 안내
카카오클라우드의 IAM 역할에 따라, 버킷을 생성하기 위해서는 프로젝트 관리자 또는 프로젝트 멤버 역할이 필요합니다.
- kr-central-1
- kr-central-2
Request Syntax
버킷 생성 Request Syntax (kr-central-1)
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
버킷 생성 Response Syntax (kr-central-1)
{
name: String
type: String
use_encryption: boolean
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
name | String | 생성된 버킷 이름 |
type | String | 생성된 버킷 타입 - hot (기본값): hot 버킷- cold (지원 예정): cold 버킷 |
use_encryption | Boolean | 버킷 암호화 여부 - false (기본값): 암호화하지 않음 - true : 암호화 함 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 bucket_name 이 이미 존재 |
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-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
버킷 생성 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) | String | Project ID - Swift API에서 Account 값. 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) |
project | String | Project 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 리스트 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 입력 설정 오류 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 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_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
버킷 상세 조회 Response Syntax(kr-central-1)
{
"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 | Project 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 : 암호화 함 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
409 | Conflicts | 생성 실패 - 동일한 bucket_name 이 이미 존재 |
버킷 상세 조회 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 | 유형 | 설명 |
---|---|---|
project | String | Project 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 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
400 | Bad Request | 입력 설정 오류 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
버킷 목록 조회
버킷 목록을 조회할 수 있습니다.
권한 안내
카카오클라우드의 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_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
버킷 목록 조회 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 참고 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 조회 권한 없음(토큰 오류) |
403 | Forbidden | 조회 권한 없음 |
버킷 접근 관리
- kr-central-1
- kr-central-2
사용자가 소유한 버킷에 대한 공공 접근이나 IP 리스트 기반의 접근 제어를 적용할 수 있습니다.
Request Syntax
접근 관리 Request Syntax (kr-central-1)
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
버킷 접근 관리 Response Syntax (kr-central-1)
{
name: String
ownerId: String
acl: AccessControlList
}
Response Elements
Response | 유형 | 설명 |
---|---|---|
name | String | 버킷 이름 |
ownerId | String | 버킷 소유자 ID (deprecated) - 현재는 소유자의 별도 권한이 존재하지 않음 |
acl | List | 접근 권한 설정 |
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | OK | 성공 |
401 | Unauthorized | 권한 없음 |
404 | Not found | 버킷을 찾을 수 없음 |