Object:File&Folder API

Object:File&Folder 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

지원 스펙

Object REST-API는 Openstack의 Swift API 스펙을 지원합니다.

Object REST-API	Swift API 스펙
Account	Bucket Account
Container	Bucket Name
Object	폴더(Folder)와 파일(File) - 폴더 예시: images/small - 파일 예시: image/small/icon.jpg

Method

폴더 생성

Owner, Read-Write 권한이 있는 사용자는 버킷 안에 폴더를 생성할 수 있습니다.

Request Syntax

코드 예제 폴더 생성 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Response Syntax

Status Code

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

파일 생성 및 업로드

Owner, Read-Write 권한이 있는 사용자는 버킷 안에 파일을 생성하거나 업로드할 수 있습니다.

Request Syntax

코드 예제 파일 생성 및 업로드 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}/{file}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: text/plain' \
--data-raw '{Content}'

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg
file	String	필수	파일명 - 예시: icon.jpg

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Type	String	필수	Put(업로드)하는 오브젝트가 폴더인 경우 `application/directory`을 입력
Content-Type	String	선택	Put(업로드)하는 오브젝트가 파일인 경우 mime type 문자열을 입력 - 콘텐츠 타입을 입력하지 않은 Put(업로드) 경우에는 Object Storage 내부적으로 현재 업로드하는 파일의 타입을 `application/octet-stream`으로 처리
X-Object-Meta-{name}	String	선택	버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 `{name}`에 입력
Content-Length	int	선택	콘텐츠 길이
Transfer-Encoding	String	선택	인코딩 방식 - `chunked` : 데이터가 일련의 청크 내에서 분할하여 전송하는 방식으로, chunked 값이 지정된 경우에는 Content-Length Header는 전송되면 안 됨 - `compress` : LZW 알고리즘을 사용하는 압축 방식 - `deflate` : deflate 알고리즘을 사용하는 압축 방식 - `gzip` : LZ77 알고리즘을 사용하는 압축 방식 - `identity` : 압축이나 수정이 없는 전송 방식

Request body Elements

Request	타입	필수 여부	설명
Content	Raw data	필수	파일의 콘텐츠

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공
401	Unauthorized	권한 없음

대용량 파일 업로드

HTTP 프로토콜은 연결 유지 기능이 없기 때문에 TCP 연결이 끊어지면 데이터 전송이 끝납니다. 따라서 대용량의 파일을 한 번의 Connection으로 업로드 시, Connection이 불안하거나 접속이 끊어진 경우에는 업로드가 중단될 수 있습니다. Kakao i Cloud 오브젝트 스토리지에서는 대용량 파일을 업로드하기 위해 다음의 대용량 오브젝트(Large Object) 업로드 방식을 지원합니다.

주의
같은 이름의 파일이지만 다른 용량의 파일을 덮어쓰기로 업로드 시, 세그먼트 파일이 남아 있을 수 있습니다.
객체 조회를 통해 남아 있는 세그먼트 파일을 삭제하시길 권장합니다.

대용량 오브젝트(Large Object) 업로드 방식

방식	설명
DLO(Dynamic Large Object)	분할된 Segment Object가 하나의 단일 Large Object로 인식되도록 함 - Swift 프로토콜
SLO(Static Large Object)	Segment를 분할해 업로드하지만, Segment Naming 제약이 없고 Size가 동일하지 않아도 됨 - Swift 프로토콜

DLO(Dynamic Large Object) 방식

DLO 방식은 나누어진 Segment Object가 하나의 단일 Large Object로 인식될 수 있도록 합니다. 또한, 각 Segment Object의 integrity를 보장하지 않습니다. 다운로드(GET) 시, 사용자는 Manifest Object 다운로드 요청을 합니다. 그리고 오브젝트 스토리지 서버에서는 Manifest Object에 입력된 X-Object-Manifest를 인지하고, Segment Object를 단일 대용량 오브젝트로 인식될 수 있게 합니다.

하나의 단일 대용량 오브젝트(Large Object)를 일정한 크기로 분할(Segment)합니다.
분할한 오브젝트를 Object Manifest 하위에 업로드합니다.
X-Object-Manifest 헤더의 항목이 기입된 Manifest Object 업로드합니다. 이때 Manifest Object를 먼저 업로드할 수 있습니다.

DLO Segment Object 업로드

Request Syntax

코드 예제 DLO Segment Object 업로드 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects...}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'

코드 예제 DLO Segment Object 업로드

curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/DLO/00000001 --data-binary '1'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/DLO/00000002 --data-binary '2'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/DLO/00000003 --data-binary '3'

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects…}`

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
DLO Manifest Object	String	필수	Manifest Object 이름
Segment Objects…	String	필수	다수의 Segment Objects 업로드 가능 - 오름차순 Sequence Number Naming 필요함 (예시: segment_0001 … segment_0002 )

Request Header

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

Request Elements

Request	타입	필수 여부	설명
segment_content	Data-raw	필수	segment object의 콘텐츠

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

DLO Manifest Object 업로드

Request Syntax

코드 예제 DLO Manifest 업로드 Request Syntax

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

코드 예제 DLO Manifest Object 업로드 예제

curl -X PUT -H 'X-Auth-Token: <token>' -H 'X-Object-Manifest: test-bucket/DLO' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/DLO --data-binary ''

API 호출 방식

메서드	URL
PUT (Segment된 Object를 업로드)	`https:/objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Object…}`
PUT (Manifest Object 자체를 업로드)	`https:/objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{DLO Manifest Object}`

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
DLO Manifest Object	String	필수	Manifest Object 이름
Segment Object…	String	필수	다수의 Segment Objects 업로드 가능

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
X-Object-Manifest	String	필수	분할한 Segment Objects를 업로드한 경로 - {bucket_name}/{DLO Manifest Object} 형식

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

DLO 다운로드

Request Syntax

코드 예제 DLO 다운로드 Request Syntax

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

코드 예제 DLO 다운로드 예제

curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/DLO

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{DLO Manifest Object}`

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

Request Header

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

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

SLO(Static Large Object) 방식

SLO 방식은 DLO와 동일하게 Segment를 분할해 업로드하지만, Segment Naming 제약이 없고 Size가 동일하지 않아도 된다는 차이점이 있습니다. 또한, Manifest를 제일 마지막에 업로드해야 합니다. SLO Manifest Object는 Segment Object 목록을 순서대로 작성하여 입력해야 합니다. 현재 KiC 오브젝트 스토리지에서는 최대 1,000개의 Segment Object를 하나의 Manifest에 입력할 수 있습니다.
SLO Manifest Object 생성 요청을 하면 각 Segment Object가 입력된 경로에 있는지, etag Value와 segment object Size가 일치하는지 확인합니다. 정보가 일치하지 않으면 Manifest Object가 생성되지 않습니다. 또한, Manifest에 etag를 통해 Segment Object의 integrity를 보장합니다.

하나의 단일 대용량 오브젝트(Large Object)를 사용자가 원하는 크기로 분할(Segment)합니다.
각 Segment를 접근 권한이 있는 버킷에 업로드합니다. 동일한 버킷이 아니어도 되나, 접근 권한이 있는 프로젝트(account) 버킷이어야 합니다.
위의 업로드된 Segment 오브젝트의 Path, Etag, Size가 기록된 Manifest를 Body로 입력하여, SLO Manifest Object를 업로드합니다.

안내
Manifest에 대한 자세한 예제는 https://objectstorage.kr-central-1.kakaoi.io/info에서 참고하시기 바랍니다.

SLO Segment Object 업로드

Request Syntax

코드 예제 SLO Segment 업로드 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}/{Segment Object}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'

코드 예제 SLO Segment Object 업로드 예제

curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/slo_test_1.txt --data-binary '@./slo_test_1.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/other-bucket/slo_test_2.txt --data-binary '@./slo_test_2.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/other1-bucket/slo_test_3.txt --data-binary '@./slo_test_3.txt'

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}/{Segment Object}`

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	Segment Object를 업로드한 경로
Segment Object	String	필수	Segment Object 이름

Request Header

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

Request Elements

Request	타입	필수 여부	설명
segment_content	Raw-data	필수	segment object의 콘텐츠

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

SLO Manifest 업로드

Request Syntax

코드 예제 SLO Manifest 업로드 Request Syntax

curl --location --request PUT 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=put' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: "application/json"' \
--data '[ \
        {
            "path": "{path}/{Segment Object}",
            "etag": "{Segment Object의 etag 값}",
            "size_bytes": "{Segment Object Size}"
        },
        ....
    ]
}'

코드 예제 SLO Manifest Object 업로드 예제

curl -X PUT -H 'X-Auth-Token: <token>' -H 'Content-Type: application/json' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/bucket/SLO?multipart-manifest=put 
--data 
'
[
   {
      "path": "test-bucket/slo_test_1.txt",
      "etag": "ba1f2511fc30423bdbb183fe33f3dd0f",
      "size_bytes": 4
   },
   {
      "path": "other-bucket/slo_test_2.txt",
      "etag": "441295deac01cf5d6bdc7db3173adfdf",
      "size_bytes": 1369
   },
   {
      "path": "other1-bucket/slo_test_3.txt",
      "etag": "aa3f5bb8c988fa9b75a1cdb1dc4d93fc",
      "size_bytes": 4
   }
]
'

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=put`

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

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Type	String	필수	콘텐츠의 타입

Request Elements

Request	타입	필수 여부	설명
path	String	필수	{path}/{Segment Object} 형식으로 입력 - `{path}`: Object를 업로드할 경로 - `{Segment Object}`: path 하위의 Segment object
etag	String	선택	Segment Object의 etag 값
size_bytes	Int	선택	Segment Object 사이즈

안내
Manifest PUT 시 etag와 size_bytes를 입력한 후, 기존의 업로된 segment object의 etag와 size_bytes 값을 비교하여 일치하지 않을 시 오류를 발생시킴

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

SLO 다운로드

Request Syntax

코드 예제 SLO 다운로드 Request Syntax

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

코드 예제 SLO 다운로드 예제

curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/bucket/SLO

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{SLO Manifest Object}`

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

Request Header

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

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

SLO Manifest 다운로드

SLO는 SLO Manifest Object만 별도로 다운로드를 할 수 있습니다. query param으로 multipart-manifest=get을 요청하면, manifest만 다운로드할 수 있습니다

Request Syntax

코드 예제 SLO Manifest 다운로드 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get' \
--header 'X-Auth-Token: {x-auth-token}' \

코드 예제 SLO Manifest Object 다운로드 예제

curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/test-bucket/SLO?multipart-manifest=get

API 호출 방식

메서드	URL
PUT	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get`

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

Request Header

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

Response Syntax

Status Code

HTTP Status	응답 내용	설명
201	Created	성공

Object Meta 조회

Owner, Read-Only, Read-Write 권한이 있는 사용자는 버킷에 대해 조회할 수 있습니다. 버킷에 저장된 오브젝트(파일, 폴더) Meta 데이터를 제공합니다.

Request Syntax

코드 예제 Object Meta 조회 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Response Syntax

Status Code

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

Object Meta 변경

Owner, Read-Write 권한이 있는 사용자는 버킷에 대해 변경할 수 있습니다.
버킷에 저장된 오브젝트(파일, 폴더) Meta 데이터를 변경합니다.

Request Syntax

코드 예제 Object Meta 변경 Request Syntax

curl --location --request POST 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}' \
--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}`

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Response Syntax

Status Code

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

Object 목록 조회

Owner, Read-Write, Read-Only 권한이 있는 사용자는 버킷에 대해 조회할 수 있습니다. 버킷에 저장된 오브젝트(파일, 폴더) 목록을 조회합니다.

Request Syntax

코드 예제 Object 목록 조회 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}?format=json' \
--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	필수	사용자 인증 토큰

Request Query

Request	타입	필수 여부	설명
prefix	Query	선택	Directory path - 예시: image/small
delimiter	Query	선택	delimiter를 key로 사용할 경우에는 `/` 입력 필요
limit	Query	선택	목록 개수 - 기본값: `1000`
marker	Query	선택	검색 조건 - (Object name > Marker )
format	Query	선택	response 받을 포맷 - `plain`(기본값), `json`, `xml`

Response Syntax

코드 예제 JSON ObjectList

{
   name: String
   content_type: String
   bytes: int
   hash: String
   last_modified: String // 최종 수정일시 RFC3339 예시: 2020-07-01T00:00:00Z
   subdir: String // pseudo-directory인 경우 이 값만 제공
}

코드 예제 Object 목록 조회 Response Syntax

[
    {
        "name": "document",
        "content_type": "application/directory",
        "bytes": 0,
        "hash": "d41d8cd98f00b204e9800998ecf8427e",
        "last_modified": "2020-06-26T11:12:03+09:00"
    },
    {
        "name": "document/hello.txt",
        "content_type": "application/octet-stream",
        "bytes": 7,
        "hash": "083d9fe8506415ba02f2f86e0531527f",
        "last_modified": "2020-06-26T11:14:50+09:00"
    }
]

Response Elements

Response	타입	설명
name	String	오브젝트	이름
content_type	String	해당 오브젝트를 PUT할 때 입력받았던 Content-Type 값이 반환 - 타입: directory / 이미지 / 구분 바이너리 등
bytes	int	오브젝트 크기
hash	String	파일 고윳값
last_modified	String	최종 수정일시 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z
subdir	String	`pseudo-directory`인 경우 이 값만 제공됨

Status Code

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

Object 다운로드

Owner, Read-Write, Read-Only 권한이 있는 사용자는 버킷의 오브젝트를 다운로드할 수 있습니다.
Path가 Folder인 경우, 사이즈가 0인 Content를 응답 받습니다. Folder의 하부 목록을 조회하기 위해서는 Object List API를 사용해야 합니다.

Request Syntax

코드 예제 Object 다운로드 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Response Syntax

코드 예제 Object 다운로드 Response Syntax

{
   Content-Length (Header) 
   Content-Type (Header)
   Last-Modified (Header)
   ETag (Header)           
   Content (Body)          
}

Response Header

Response	타입	설명
Content-Length	int	오브젝트의 크기 값 - 파일인 경우 파일 크기 값이 전달됨 - 폴더인 경우에는 메타 정보만 있어 `0` 값이 전달됨
Content-Type	String	콘텐츠의 타입
Last-Modified	String	최종 수정일시
ETag	String	ETag는 바이너리에 대한 MD5 해쉬값임으로 바이너리가 존재하지 않는 폴더의 경우에는 의미 없는 값 전달됨

Response Elements

Response	타입	설명
Content	Raw data	콘텐츠 타입이 폴더인 경우 전달 안 됨

Status Code

응답 코드	응답 내용	설명
200	OK	성공
401	Unauthorized	권한 없음
404	Notfound	File not found

Object 삭제

Owner, Read-Write 권한이 있는 사용자는 버킷의 오브젝트를 삭제할 수 있습니다.

Request Syntax

코드 예제 Object 삭제 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Response Syntax

Status Code

HTTPS Status	응답 내용	설명
204	No Content	성공
401	Unauthorized	권한 없음
404	Notfound	File not found

Object 복사

복사할 오브젝트에 대한 읽기 권한과 복사될 오브젝트에 대한 쓰기 권한(Read-Write 권한)이 있어야 합니다.

Request Syntax

코드 예제 Object 복사 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Destination	String	필수	복사할 목적지의 경로명 - 예시: {target-bucket-name}/{target-path}

Response Syntax

Status Code

HTTPS Status	응답 내용	설명
201	Created	성공
401	Unauthorized	권한 없음
404	Notfound	File not found

Object 이동

이동할 오브젝트에 대한 읽기 권한과 이동될 오브젝트에 대한 쓰기 권한(Read-Write 권한)이 있어야 합니다.

Request Syntax

코드 예제 Object 이동 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

Request	타입	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Destination	String	필수	이동할 목적지의 경로 - 예시: {target-bucket-name}/{target-path}

Response Syntax

Status Code

HTTPS Status	응답 내용	설명
201	Created	성공
401	Unauthorized	권한 없음
404	Notfound	File not found

Object 다운로드용 Temp URL 생성

오브젝트에 대한 접근 권한이 있는 사용자는 특정 기간 유효한 다운로드용 Temp URL을 생성합니다. temp_url_expires는 유효 시간으로 사용자가 지정한 시간까지 다운로드 받을 수 있도록 설정합니다.

Request Syntax

코드 예제 Object 다운로드용 Temp URL 생성 Request Syntax

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

API 호출 방식

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

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Header

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

Request Query

Request	타입	필수 여부	설명
temp_url_expires	int	필수	발급된 Temp URL의 유효시간 - 단위: Unix epoch time

Response Syntax

코드 예제 Object 다운로드용 Temp URL 생성 Response

{
   url          : 해당 오브젝트를 다운로드 받을 수 있는 temp url
   sig          : 해당 url의 signiture이며 url에 포함됨
   MeteringInfo : 버킷의 정보
}

코드 예제 Object 다운로드용 Temp URL 생성 Response

{
    "url": "/v1/my-account/my-bucket/hello.txt?temp_url_sig=d4be653107de1053fb682bbc855d971bee935d54&temp_url_expires=1647918000",
    "sig": "d4be653107de1053fb682bbc855d971bee935d54",
    "MeteringInfo": {
        "BucketName": "my-bucket",
        "BucketType": "hot",
        "BucketCreatedAt": 1622788405000
    }
}

Response Elements

Response	타입	설명
url	String	해당 오브젝트를 다운로드 받을 수 있는 temp url
sig	String	해당 url의 signiture이며 url에 포함됨
MeteringInfo ▼	-	버킷의 정보
BucketName	String	버킷 이름
BucketType	String	버킷 타입
BucketCreatedAt	String	버킷 생성일

Status Code

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

Temp URL을 사용한 Object 다운로드

생성된 Temp URL을 사용하면 발급 시 신청한 유효 시간 동안 해당 오브젝트를 다운로드할 수 있습니다. Temp URL을 사용할 경우, X-Auth-Token 없이 다운로드 받을 수 있으므로 Temp URL의 발급자는 신뢰할 수 있는 사용자에게 전달해야 합니다.

Request Syntax

코드 예제 Temp URL을 사용한 Object 다운로드 Request Syntax

curl --location --request GET 'https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}?temp_url_sig={signature}&temp_url_expires={unix epoch time}'

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.kr-central-1.kakaoi.io/v1/{account}/{bucket_name}/{path}?temp_url_sig=value&temp_url_expires=value&filename=value`

Path	타입	필수 여부	설명
account	String	필수	Project ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	String	필수	버킷 이름
path	String	필수	폴더 전체 경로 - 예시: image/small, images/small/icon.jpg

Request Query

Request	타입	필수 여부	설명
temp_url_sig	Query	필수	발급받은 Temp URL Response의 signature 정보
temp_url_expires	Query	필수	발급받은 Temp URL Resoponse의 유효시간 정보 - 단위: Unix epoch time
filename	Query	선택	오브젝트를 브라우저에서 다운로드 받을 때 사용할 custom 파일명 - utf-8 percent encoding된 문자열

Response Syntax

코드 예제 Temp URL을 사용한 Object 다운로드 Response Syntax

{
   Content-Length (Header) 
   Content-Type (Header)
   Last-Modified (Header)
   ETag (Header)           
   Content-Disposition (Header)
   Content (Body)        
}

Response Header

Response	타입	설명
Content-Length	int	오브젝트의 크기값 - 파일인 경우 파일 크기값이 전달됨 - 폴더인 경우에는 메타 정보만 있어 `0`값이 전달됨
Content-Type	String	미디어 타입
Last-Modified	String	최종 수정일시
ETag	String	ETag는 바이너리에 대한 MD5 해쉬값임으로, 바이너리가 존재하지 않는 폴더의 경우에는 의미 없는 값 전달됨
Content-Disposition	String	Object 다운로드 시 브라우저가 로컬에 저장할 파일명 - 기본값: Object Name - utf-8 percent encoding된 문자열이 전달됨

Response Elements

Response	타입	설명
Content	Body	콘텐츠 타입이 폴더인 경우 전달 안 됨

Status Code

HTTPS Status	응답 내용	설명
200	Success	성공
403	Forbidden	Temp URL의 유효시간 만료

클라우드 가이드 센터 User Guide

REST API

페이지 이동경로

Object:File&Folder API

API 엔드포인트 URL

지원 스펙

Method

폴더 생성

파일 생성 및 업로드

대용량 파일 업로드

DLO(Dynamic Large Object) 방식

DLO Segment Object 업로드

DLO Manifest Object 업로드

DLO 다운로드

SLO(Static Large Object) 방식

SLO Segment Object 업로드

SLO Manifest 업로드

SLO 다운로드

SLO Manifest 다운로드

Object Meta 조회

Object Meta 변경

Object 목록 조회

Object 다운로드

Object 삭제

Object 복사

Object 이동

Object 다운로드용 Temp URL 생성

Temp URL을 사용한 Object 다운로드