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-gov-central-1.kakaocloud-kr-gov.com

버킷 생성

버킷을 생성합니다.

권한 안내

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

Request Syntax

버킷 생성 Request Syntax
curl --location --request PUT 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my-bucket-new",
    "type": "hot",
    "use_encryption": True
}'

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/{bucket_name}`

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 
{
    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`이 이미 존재

버킷 관리

버킷 상세 조회

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

Request Syntax

버킷 상세 조회 Request Syntax
curl --location --request GET 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/{bucket_name}`

Path	유형	필수 여부	설명
region_name	String	필수	리전 명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰을 입력

Response Syntax

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

버킷 상세 조회 Response Syntax 
{
    "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	해당 버킷의 라이프사이클이 적용된 정책의 개수
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`이 이미 존재

버킷 목록 조회

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

권한 안내

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

Request Syntax

버킷 목록 조회 Request Syntax
curl --location --request GET 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket?limit=100' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket`

Request Element

Path	유형	필수 여부	설명
region_name	String	필수	리전명

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` - `cold`
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	조회 권한 없음

버킷 접근 관리

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

Request Syntax

접근 관리 Request Syntax 
curl --request POST --location 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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 
{
   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	버킷을 찾을 수 없음

버킷 삭제

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

버킷 내에 오브젝트가 존재하는 경우에는 버킷을 삭제할 수 없습니다.

Request Syntax

버킷 삭제 Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}`

Request Element

Path	유형	필수 여부	설명
region_name	String	필수	리전 명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

Response Syntax

Status Code

HTTP Status	응답 내용	설명
`204`	No Content	삭제 성공
`401`	Unauthorized	인증 실패
`404`	Not found	버킷 찾을 수 없음
`409`	Conflict	버킷이 비어있지 않음

버킷 및 오브젝트 일괄 삭제

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

Request Syntax

일괄 삭제 Request Syntax
curl --request DELETE --location 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/?bulk-delete`

Request Element

Path	유형	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

Request Body

유형	필수 여부	설명
String	필수	삭제 대상 버킷 및 오브젝트 리스트 - Separator: new line

Response Syntax

Status Code

HTTP Status	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음
`409`	Conflict	버킷 삭제 실패 (Not empty)

버킷 메타 조회

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

Request Syntax

버킷 메타 조회 Request Syntax
curl --location --request HEAD 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
HEAD	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}`

Path	유형	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

Response Syntax

Status Code

HTTP Status	응답 내용	설명
`200`	Success	성공
`401`	Unauthorized	권한 없음

버킷 메타 변경

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

Request Syntax

버킷 메타 변경 Request Syntax
curl --location --request POST 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}`

Request Element

Path	유형	필수 여부	설명
region_name	String	필수	리전명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
X-Object-Meta-`{name}`	String	필수	버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 `{name}`에 입력

Response Syntax

Status Code

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가 있는 경우, 그에 따른 결과를 반환할 수 있습니다.

API 명
/v1/:account/:container
/v1/:account/:container/*object

API 명
/v1/:account/:container
/v1/:account/:container/*object

안내

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

Request Syntax

CORS 정책 설정 Request Syntax
curl --request PUT --location 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}/cors`

Path	유형	필수 여부	설명
region_name	String	필수	리전 명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Type	String	필수	`application/json`으로 고정

Request Elements

Request	유형	필수 여부	설명
region_name	String	필수	리전 명
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 정책 설정 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	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	잘못된 요청 (잘못된 이름 규칙)
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음
`404`	Not found	버킷을 찾을 수 없음

버킷 CORS 정책 조회

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

Request Syntax

CORS 정책 조회 Request Syntax
curl --request GET --location 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}/cors`

Request Element

Path	유형	필수 여부	설명
region_name	String	필수	리전 명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Type	String	필수	`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_origins	List	필수	접근 허용하는 허용 origin - 최대 1개의 `*`(와일드 카드) 문자 포함 - origin 당 최대 입력 가능 길이: 200
allowed_methods	List	필수	접근 허용할 메서드(`HTTP`)
allowed_headers	List	필수	접근 허용할 헤더
expose_headers	List	필수	브라우저에 노출한 헤더
max_age_seconds	Int	선택	preflight request 결과를 캐싱하는 수명

Status Code

HTTP Status	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음

CORS Preflight 요청

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

하단의 API는 해당 container에 PUT /v1_ext/bucket/:name/cors을 통해 설정된 CORS가 있는 경우, 그에 따른 결과를 반환할 수 있습니다.
API 명
/v1/:account/:container
/v1/:account/:container/*object

Request Syntax

CORS Preflight 요청 Request Syntax
curl --location --request OPTIONS 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

API 호출 방식

메서드	요청 URL
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1_ext/bucket`
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1_ext/bucket/:name` - name: 버킷 이름
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1_ext/bucket/:name/policy` - name: 버킷 이름
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1_ext/bucket/:name/policy/:id` - name: 버킷 이름 - id: policy ID
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1/:account/:name` - account: Project ID - name: 버킷 이름
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.com/v1/:account/:name/object` - account: Project ID - name: 버킷 이름 - object: object path
OPTIONS	`https://objectstorage.kr-central-2.kakaocloud-kr-gov.com/v1/:name` - name: 버킷 이름
OPTIONS	`https://objectstorage.{region_name}.kakaocloud-kr-gov.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

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	성공
`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

CORS Preflight 외의 요청 Request Syntax
curl --location --request GET 'http://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}/{object}' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Origin: https://www.example1.com'

API 호출 방식

메서드	요청 URL
GET	`http://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/{account}/{bucket_name}/{object}`

Request Element

Path	유형	필수 여부	설명
region_name	String	필수	리전명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
object	String	필수	오브젝트 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

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-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 헤더에 서버가 아는 가장 마지막 수정된 날짜와 시각을 담은 응답

Status Code

HTTP Status	응답 내용	설명
`200`	OK	성공
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음

버킷 LifeCycle

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

버킷 LifeCycle 생성

버킷의 라이프사이클을 생성할 수 있습니다.

Request Syntax

Bucket LifeCycle 생성
{
    "target" :      String              // 적용 Prefix 값
    "duration" :    int                 // Policy 적용일, Day 기준. 예시: 30일 이후 적용
}

버킷 LifeCycle 생성 예시
curl --location --request PUT 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}/policy`

Path	유형	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

Request Elements

Request	유형	필수 여부	설명
PolicyCreateRequest	Raw-data	필수	정책 항목

Response Syntax

버킷 LifeCycle 생성
{
    "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	유지 기간

Status Code

HTTP Status	응답 내용	설명
`200`	Success	성공
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음

버킷 LifeCycle 목록 조회

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

안내

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

Request Syntax

버킷 LifeCycle 목록 조회 Request Syntax
curl --location --request GET 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/bucket/{bucket_name}/policy' \
--header 'X-Auth-Token: {X-Auth-Token}' \

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1/bucket/{bucket_name}/policy`

Path	유형	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰

Response Syntax

버킷 LifeCycle 목록 조회 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	유지 기간

Status Code

HTTP Status	응답 내용	설명
`200`	Success	성공
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음

버킷 LifeCycle 삭제

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

Request Syntax

버킷 LifeCycle 삭제 Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.com/v1_ext/bucket/{bucket_name}/policy/{policy_id}' \
--header 'X-Auth-Token: {X-Auth-Token}'

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.kr-gov-central-1.kakaocloud-kr-gov.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

Status Code

HTTP Status	응답 내용	설명
`204`	No Content	성공
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음

API 사용 준비​

API 엔드포인트 URL​

버킷 생성​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

Status Code​

버킷 관리​

버킷 상세 조회​

Request Syntax​

API 호출 방식​

Request Header​

Response Syntax​

Response Elements​

Status Code​

버킷 목록 조회​

Request Syntax​

API 호출 방식​

Request Element​

Request Header​

Request Query​

Response Syntax​

Response Elements​

Status Code​

버킷 접근 관리​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

Status Code​

버킷 삭제​

Request Syntax​

API 호출 방식​

Request Element​

Request Header​

Response Syntax​

Status Code​

버킷 및 오브젝트 일괄 삭제​

Request Syntax​

API 호출 방식​

Request Element​

Request Header​

Request Body​

Response Syntax​

Status Code​

버킷 메타 조회​

Request Syntax​

API 호출 방식​

Request Header​

Response Syntax​

Status Code​

버킷 메타 변경​

Request Syntax​

API 호출 방식​

Request Element​

Request Header​

Response Syntax​

Status Code​

버킷 CORS 정책​

버킷 CORS 정책 설정​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Response Syntax​

Status Code​

버킷 CORS 정책 조회​

Request Syntax​

API 호출 방식​

Request Element​

Request Header​

Response Syntax​

Response Elements​

Status Code​

CORS Preflight 요청​

API 사용 준비

API 엔드포인트 URL

버킷 생성

Request Syntax

API 호출 방식

Request Header

Request Elements

Response Syntax

Response Elements

Status Code

버킷 관리

버킷 상세 조회

Request Syntax

API 호출 방식

Request Header

Response Syntax

Response Elements

Status Code

버킷 목록 조회

Request Syntax

API 호출 방식

Request Element

Request Header

Request Query

Response Syntax

Response Elements

Status Code

버킷 접근 관리

Request Syntax

API 호출 방식

Request Header

Request Elements

Response Syntax

Response Elements

Status Code

버킷 삭제

Request Syntax

API 호출 방식

Request Element

Request Header

Response Syntax

Status Code

버킷 및 오브젝트 일괄 삭제

Request Syntax

API 호출 방식

Request Element

Request Header

Request Body

Response Syntax

Status Code

버킷 메타 조회

Request Syntax

API 호출 방식

Request Header

Response Syntax

Status Code

버킷 메타 변경

Request Syntax

API 호출 방식

Request Element

Request Header

Response Syntax

Status Code

버킷 CORS 정책

버킷 CORS 정책 설정

Request Syntax

API 호출 방식

Request Header

Request Elements

Response Syntax

Status Code

버킷 CORS 정책 조회

Request Syntax

API 호출 방식

Request Element

Request Header

Response Syntax

Response Elements

Status Code

CORS Preflight 요청