Bucket API

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

API 엔드포인트 URL

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

코드 예제 Object Storage API 엔드포인트 URL 형식

KR-Central-1 : https://objectstorage.kr-central-1.kakaoi.io 
KR-Central-2 : https://objectstorage.kr-central-2.kakaoi.io

Method

버킷 생성

버킷 생성 권한이 있는 사용자는 버킷을 생성할 수 있습니다.

Request Syntax

코드 예제 버킷 생성(BucketCreateReq) Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket' \
--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-central-1.kakaoi.io/v1_ext/bucket

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰을 입력
Content-Type	String	필수	application/json로 고정

Request Elements

Request	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름
type	String	필수	버킷 타입 - hot(기본값): hot 버킷 - cold(지원 예정): cold 버킷
use_encryption	Boolean	선택	버킷 암호화 여부 - false(기본값): 암호화하지 않음 - true: 암호화 함

Response Syntax

코드 예제 버킷 생성 Response Syntax

{
    name: String             
    type: String                    
    use_encrytion: boolean         
}

Response Elements

Response	타입	설명
name	String	생성된 버킷 이름
type	String	생성된 버킷 타입 - hot(기본값): hot 버킷 - cold(지원 예정): cold 버킷
use_encrytion	Boolean	버킷 암호화 여부 - false(기본값): 암호화하지 않음 - true: 암호화 함

Status Code

HTTP Status	응답 내용	설명
200	OK Bucket (Body (JSON)	성공
401	Unauthorized	권한 없음
409	Conflicts	생성 실패 - 동일한 bucket_name 이미 존재

버킷 상세 조회

특정 버킷에 대한 상세 정보를 조회할 수 있습니다.

Request Syntax

코드 예제 버킷 상세 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
GET	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/{bucket_name}

Path	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

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

Request Elements

Request	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

API 모델

안내
Model에 대한 자세한 설명은 API Model를 참고하시기 바랍니다.

Model Bucket

{
    account: String            // project ID | Swift API에서 account 값으로 사용
    name: String               // 버킷 이름 | object storage에서 유일한 값
    type: String               // 버킷 타입 | hot | cold
    bytes: int                 // 총 사용량 | 단위: Byte
    objectCount: int           // 해당 버킷에 속한 오브젝트 개수
    policyCount: int           // 해당 버킷의 라이프사이클이 적용된 정책의 개수
    createdAt: String          // 생성일로 RFC3339 형식 | 예시)2020-07-01T00:00:00Z
    lastModified: String       // 수정일로 RFC3339 형식 | 예시)2020-07-01T00:00:00Z
    owner: [SimpleUser]        // 버킷 생성자 | 생성자는 버킷에 대한 Admin 권한 가짐
    acl: [AccessControlList]   // 버킷에 대한 접근 권한
    use_encryption: boolean    // 버킷 암호화 여부
}

Model SimpleUser

{
    id: String              // 사용자 ID. 예시) a0cd4299ed99458f9679c89a27e1a52d
    name: String            // 사용자 name. 예시) reuben.b@kakkaoenterprise.com
}

Model AccessControlList

{
   acl : [Permission]       // 버킷에 대한 접근 권한
   publicAcl : String       // 버킷 공개 여부 | Deny(기본값): 공개하지 않음, Read-Only: 읽기 권한 공개  
}

Model Permission

{
   user : SimpelUser        // 버킷에 접근할 수 있는 사용자
   permission: String       // 버킷 접근 권한 | read-only, read-write
}

Response Syntax

코드 예제 버킷 상세 조회 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이면 무시
lastModified	String	수정일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z
use_encryption	Boolean	버킷 암호화 여부 - false(기본값): 암호화하지 않음 - true: 암호화 함

Status Code

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

버킷 목록 조회

X-Auth-Token으로 인증된 사용자가 접근할 수 있는 버킷 목록을 조회할 수 있습니다.

Request Syntax

코드 예제 버킷 목록 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket?limit=100' \
/--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
GET	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket

Request Header

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

Request Query

Request	타입	필수 여부	설명
offset	Query	선택	버킷 목록에서 오프셋부터 n개씩 가져옴 - 오프셋은 0부터 시작 - 기본값: 0
limit	Query	선택	목록 개수 제한 - 기본값: 20
prefix	Query	선택	Prefix로 버킷 이름 검색
include	Query	선택	포함 문자열로 버킷 이름 검색 - prefix 와 같이 사용할 수 없음
type	Query	선택	Type 검색 조건 - hot: hot 버킷 - cold: 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	버킷의 상세 정보

API 모델

안내
Model에 대한 자세한 설명은 API Model를 참고하시기 바랍니다.

Model SimpleBucket

{
   account:String          // Project ID | Swift API에서 account 값으로 사용
   name:String             // 버킷 이름 | Object storage에서 유일한 값
   type:String             // 버킷 타입 | hot/cold
   bytes:int               // 총 사용량 | 단위: Byte
   objectCount:int         // 해당 버킷에 속한 오브젝트 개수
   policyCount:int         // 해당 버킷의 라이프사이클이 적용된 정책의 개수
   createdAt:String        // 생성일로 RFC3339 형식 | 예시) 2020-07-01T00:00:00Z
   lastModified:String     // 수정일로 RFC3339 형식 | 예시) 2020-07-01T00:00:00Z
   owner: [SimpleUser]     // 버킷 생성자 | 해당 버킷에 대해 생성자는 admin 권한을 가짐
   use_encryption:boolean  // 버킷 암호화 여부
}

Status Code

HTTP Status	응답 내용	설명
200	OK BucketList (Body (JSON)	성공
401	Unauthorized	권한 없음

버킷 접근 관리

사용자가 소유한 버킷에 대한 접근을 관리할 수 있습니다. 현재 버킷에 대한 역할 부여는 콘솔에서만 가능합니다.

Request Syntax

코드 예제 접근 관리 Request Syntax

curl --location --request POST 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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.kakaoi.io/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 ▼	-	필수	버킷에 대한 접근 권한 - null 입력 시, 기존 ACL 설정 삭제
public	String	선택	읽기 전용 - read-only만 작성 가능
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 - 예시: 55b477f0fd364cfe8cb9d05c66fe549a
acl	List	접근 권한 설정 - null이면 무시

Status Code

HTTP Status	응답 내용	설명
200	OK	성공
401	Unauthorized	권한 없음
404	Notfound	버킷 찾을 수 없음

버킷 소유자 변경

버킷 소유자를 변경할 수 있습니다. 현재 버킷에 대한 역할 부여는 콘솔에서만 가능합니다.

Request Syntax

코드 예제 버킷 소유자 변경 Request Syntax

curl --location --request POST 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my-bucket-new",
    "ownerId": "55b477f0fd364cfe8cb9d05c66fe549a" 
}'

API 호출 방식

메서드	요청 URL
POST	https://objectstorage.kr-central-1.kakaoi.io/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	필수	버킷 이름
ownerId	String	필수	사용자 ID - 예시: 55b477f0fd364cfe8cb9d05c66fe549a

Response Syntax

코드 예제 버킷 소유자 변경 Response Syntax

{
   name: String             
   ownerId: String         
   acl: AccessControlList  
}

Response Elements

Response	타입	설명
name	String	버킷 이름
ownerId	String	사용자 ID - 예시: 55b477f0fd364cfe8cb9d05c66fe549a
acl	List	버킷에 대한 접근 권한 - null이면 무시

Status Code

HTTP Status	응답 내용	설명
200	OK	성공
401	Unauthorized	권한 없음
404	Notfound	버킷 찾을 수 없음

버킷 CORS 정책 설정

개별 버킷에 대한 CORS 정책을 설정할 수 있습니다. 버킷에 대한 스토리지 관리자 역할이 있는 사용자는 CORS 정책을 설정할 수 있습니다. 버킷에 대한 새로운 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

안내
기본 CORS 정책의 Origin은 외부 도메인의 접근을 허용하지 않습니다.

API 호출 방식

메서드	요청 URL
POST	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/cors

Path	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

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

Request 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 결과를 캐싱하는 수명 - 미입력 시 기본값은 5로 설정

Request Syntax

코드 예제 CORS 정책 설정 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'   \
--data-raw '{
    "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
PUT	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/cors

Path	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

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

Request 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 결과를 캐싱하는 수명 - 미입력 시 기본깂은 5로 설정

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	BadRequest	잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
401	Unauthorized	인증 실패
403	Forbidden	권한 없음

버킷 CORS 정책 조회

개별 버킷에 대한 CORS 설정값을 조회할 수 있습니다.

Request Syntax

코드 예제 CORS 정책 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'

API 호출 방식

메서드	요청 URL
GET	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/cors

Path	타입	필수 여부	설명
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 결과를 캐싱하는 수명 - 미입력 시 기본값은 5로 설정

Status Code

HTTP Status	응답 내용	설명
200	OK	성공
400	BadRequest	잘못된 요청 (잘못된 이름 규칙 또는 존재하지 않음)
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 'http://objectstorage.kr-central-1.kakaoi.io/v1/2f3139be045f416aab9c67da60624eb7/{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'

API 호출 방식

메서드	요청 URL
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1/:account - account: Project ID
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/auth/v1.0
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/:name - name: 버킷 이름
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/:name/policy - name: 버킷 이름
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/:name/policy/:id - name: 버킷 이름 - id: policy ID
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1/:account/:container - container: 버킷 container
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1/:account/:container/*object - container: 버킷 container
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/project
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v1/*path
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v3/users
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v3/users/:user_id - user.id: 사용자 ID
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v3/users/:user_id/password - user.id: 사용자 ID
OPTIONS	https://objectstorage.kr-central-1.kakaoi.io/v3/auth/tokens

Request Header

Request	타입	필수 여부	설명
Origin	String	필수	Origin - Protocol과 Host, Port까지 모두 합친 서버의 위치
Access-Control-Request-Headers	List	필수	예비 요청할 헤더의 리스트 - X-Auth-Token: 사용자 인증 토큰 - Content-Type: body resource 타입
Access-Control-Request-Method	List	필수	예비 요청할 메서드의 리스트

Response Header

Response	타입	설명
Content-Length	Int	Body 길이
Connection	String	Connection 일반 헤더는 현재의 전송이 완료된 후 네트워크 접속을 제어
Access-Control-Allow-Credentials	Boolean	서로 다른 도메인 간 쿠키 공유를 허락하는 옵션 - true: 허용 - false: 허용하지 않음
Access-Control-Allow-Headers	String	리소스에 접근 허용할 수 있는 HTTP 헤더
Access-Control-Allow-Methods	String	리소스에 접근 허용할 수 있는 HTTP 메서드 지정
Access-Control-Allow-Origin	String	접근 허용이 가능한 origin
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 설정에 맞지 않는 요청은 403 Forbidden 에러(정의되지 않은 origin/메서드)가 발생합니다. CORS 적용을 위해서는 반드시 헤더에 Origin이 설정되어 있어야 합니다.
헤더에 Allowed Headers에 정의된 헤더 이외의 Key 값이 들어와도 무시됩니다.

Request Syntax

코드 예제 CORS Preflight 외의 요청 Request Syntax

curl --location --request GET 'http://objectstorage.kr-central-1.kakaoi.io/v1/2f3139be045f416aab9c67da60624eb7/{bucket_name}/{object}' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Origin: https://www.example1.com'

API 호출 방식

메서드	요청 URL
GET	http://objectstorage.kr-central-1.kakaoi.io/v1/2f3139be045f416aab9c67da60624eb7/{bucket_name}/{object}

Path	타입	필수 여부	설명
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
Connection: keep-alive
Accept-Ranges: bytes
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Expose-Headers: {}
Etag: {ETag value}
Last-Modified: Thu, 07 Jul 2022 08:13:27 GMT
Vary: Origin
X-Openstack-Request-Id: 7b0f0443-52b9-4f26-ba0b-9edf0c0719b4
X-Timestamp: 1657181607
X-Trans-Id: 7b0f0443-52b9-4f26-ba0b-9edf0c0719b4
Strict-Transport-Security: max-age=31536000; includeSubDomains

Response Elements

Response	설명
Content-Type	Content-Type 개체 헤더는 리소스의 미디어 타입을 나타내기 위해 사용됨
Content-Length	Content-Length 개체 헤더는 수신자에게 보내지는 Byte 단위의 개체 본문 크기
Connection	연결 상태
Accept-Ranges	Accept-Ranges 응답 HTTP 헤더는 부분 요청의 지원을 알리기 위해 서버에 의해 사용되는 표식 - 해당 필드의 값은 범위를 정의하기 위해 사용될 수 있는 단위
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	권한 없음

버킷 삭제

사용자가 소유한 버킷을 삭제할 수 있습니다.

Request Syntax

코드 예제 버킷 삭제 Request Syntax

curl --location --request DELETE 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
DELETE	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}

Path	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

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

Response Syntax

Status Code

HTTP Status	응답 내용	설명
200	OK	성공
401	Unauthorized	인증 실패
404	Notfound	버킷 찾을 수 없음

일괄 삭제

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

Request Syntax

코드 예제 일괄 삭제 Request Syntax

curl --location --request DELETE 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/?bulk-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'
--header 'Accept: application/json'
--data-raw 'exist-container/exist-object
exist-container
not-exist-bucket
not-empty-bucket
'

API 호출 방식

메서드	요청 URL
DELETE	https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/?bulk-delete

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

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Accept	String	선택	삭제 결과에 대한 문서 포맷 - text/plain(기본값), application/json, application/xml(text/xml)

Request Body Elements

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

Response Syntax

Status Code

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

버킷 메타 조회

Owner, Read-Write, Read-Only 권한을 가진 사용자는 버킷의 메타 정보를 조회할 수 있습니다.

Request Syntax

코드 예제 버킷 메타 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API 호출 방식

메서드	요청 URL
GET	https://objectstorage.kr-central-1.kakaoi.io/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	권한 없음

버킷 메타 변경

버킷 메타 접근 권한을 가진 버킷의 메타 정보를 변경할 수 있습니다.

Request Syntax

코드 예제 버킷 메타 변경 Request Syntax

curl --location --request POST 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API 호출 방식

메서드	요청 URL
POST	https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}

Path	타입	필수 여부	설명
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	권한 없음

버킷 LifeCycle 목록 조회

LifeCycle 접근 권한을 가진 사용자는 버킷의 LifeCycle 목록을 조회할 수 있습니다.

Request Syntax

코드 예제 버킷 LifeCycle 목록 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1/bucket/{bucket_name}/policy' \
--header 'X-Auth-Token: {X-Auth-Token}' \

API 호출 방식

메서드	요청 URL
GET	https://objectstorage.kr-central-1.kakaoi.io/v1_ext/{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

코드 예제 Bucket LifeCycle 생성 - PolicyCreateRequest

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

코드 예제 버킷 LifeCycle 생성 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/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.kakaoi.io/v1_ext/{bucket_name}/policy

Path	타입	필수 여부	설명
bucket_name	String	필수	버킷 이름

Request Header

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

Request Elements

Request	타입	필수 여부	설명
PolicyCreateRequest	Raw-data	필수	정책 항목

Response Syntax

JSON 버킷 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-central-1.kakaoi.io/v1_ext/bucket/{bucket_name}/policy/{policy_id}' \
--header 'X-Auth-Token: {X-Auth-Token}'

API 호출 방식

메서드	요청 URL
DELETE	https://objectstorage.kr-central-1.kakaoi.io/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	권한 없음