Object_File & Folder
Object:File&Folder API를 사용하여 파일/폴더의 생성과 관련 정보 및 정책을 관리할 수 있습니다.
API 사용 준비
API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.
API 엔드포인트 URL
API 요청을 위한 Object Storage API 엔드포인트 URL은 다음과 같습니다.
- kr-central-1
- kr-central-2
https://objectstorage.kr-central-1.kakaocloud.com
https://objectstorage.kr-central-2.kakaocloud.com
지원 사양
Object REST-API는 Openstack의 Swift API 사양을 지원합니다.
Object REST-API | Swift API 사양 |
---|---|
Account | Bucket Account |
Container | Bucket Name |
Object | 폴더(Folder)와 파일(File) - 폴더 예시: images/small<br/> - 파일 예시: image/small/icon.jpg |
폴더 생성
Owner
, Read-Write
권한이 있는 사용자는 버킷 안에 폴더를 생성할 수 있습니다.
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/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.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
region_name | String | 필수 | 리전 명 : kr-central-1 또는 kr-central-2 |
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-{key_name} | String | 선택 | 버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 {key_name} 에 입력 - Swift API의 경우, 해당 prefix 적용 |
X-Object-Meta-{key_name} | String | 선택 | 버킷 메타 정보로, 사용자가 지정할 메타 데이터 이름을 {key_name} 에 입력 - S3 API의 경우, 해당 prefix 적용 |
Response Syntax
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
201 | Created | 성공 |
401 | Unauthorized | 인증 실패 |
403 | Forbidden | 권한 없음 |
파일 생성 및 업로드
Owner
, Read-Write
권한이 있는 사용자는 버킷 안에 파일을 생성하거나 업로드할 수 있습니다.
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/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.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{file} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
region_name | String | 필수 | 리전 명 : kr-central-1 또는 kr-central-2 |
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(업로드)하는 오브젝트가 파일인 경우 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 | 인증 실패 |
403 | Forbidden | 권한 없음 |
대용량 파일 업로드
HTTP 프로토콜은 연결 유지 기능이 없기 때문에 TCP 연결이 끊어지면 데이터 전송이 끝납니다. 따라서 대용량의 파일을 한 번의 Connection으로 업로드 시, Connection이 불안하거나 접속이 끊어진 경우에는 업로드가 중단될 수 있습니다. KakaoCloud 오브젝트 스토리지에서는 대용량 파일을 업로드하기 위해 다음의 대용량 오브젝트(Large Object) 업로드 방식을 지원합니다.
- kr-central-2의 암호화 버킷에서는 사용할 수 없습니다.
- 같은 이름의 파일이지만 다른 용량의 파일을 덮어쓰기로 업로드 시, 세그먼트 파일이 남아 있을 수 있습니다.
- 객체 조회를 통해 남아 있는 세그먼트 파일을 삭제하시길 권장합니다.
대용량 오브젝트(Large Object) 업로드 방식
방식 | 설명 |
---|---|
DLO(Dynamic Large Object) | 분할된 Segment Object가 하나의 단일 Large Object로 인식되도록 함 - Swift 프로토콜 |
SLO(Static Large Object) | Segment를 분할해 업로드하지만, Segment Naming 제약이 없고 사이즈가 동일하지 않아도 됨 - 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
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects...}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000001 --data-binary '1'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000002 --data-binary '2'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000003 --data-binary '3'
API 호출 방식
메서드 | URL |
---|---|
PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects…} |
Path | 유형 | 필수 여부 | 설명 |
---|---|---|---|
region_name | String | 필수 | kr-central-1 또는 kr-central-2 |
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
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Manifest: {bucket_name}/{DLO Manifest Object}' \