REST API

페이지 이동경로

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 권한 없음