SWIFT & EXTENSION

카카오클라우드의 Object Storage는 Swift API와 호환되며,카카오클라우드 전용 Extension API를 추가로 제공합니다.

API 사용 준비

API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.

API 엔드포인트 URL

리전 정보를 확인 후 Object Storage API 엔드포인트 URL을 호출할 수 있습니다.

Object Storage API 엔드포인트 URL 형식
https://objectstorage.{region_name}.kakaocloud.com

제공되는 기능 목록

Extension API 지원 목록

Extention API 네이밍	설명
GetBucketMeta	버킷의 메타데이터 정보를 조회합니다.(버킷 ACL 정보 포함)
CreateBucket	버킷을 생성합니다. (버킷 암호화 설정 포함)
DeleteBucket	버킷을 삭제합니다.
ListBuckets	계정 내 모든 버킷 목록을 조회합니다.
UpdateBucketAcl	버킷의 ACL(Access Control List)을 수정합니다.
PutBucketLifecycleConfiguration	버킷의 수명 주기 구성을 생성 또는 수정합니다.
GetBucketLifecycleConfiguration	버킷의 수명 주기 구성을 조회합니다.
DeleteBucketLifecycleConfiguration	버킷의 수명 주기 구성을 삭제합니다.
GetBucketCors	버킷의 CORS 설정을 조회합니다.
PutBucketCors	버킷의 CORS 설정을 생성 또는 갱신합니다.

Swift API 지원 목록

info

"카카오 클라우드는 OpenStack Swift API 스펙을 준수하나, 서비스 안정성과 보안을 위해 일부 파라미터는 제한되거나 기본값이 고정되어 제공됩니다. 아래 명세에 기재된 파라미터 위주로 사용을 권장합니다."

Swift 네이밍	설명
Head Container	컨테이너 존재 여부 확인
List Containers	계정 내 컨테이너 목록 조회
List Capability	계정이 가진 기능/권한 목록 조회 (확장)
Create Container	새 컨테이너 생성
Delete Container	컨테이너 삭제
Update Container Metadata	컨테이너 메타데이터 수정
Get Object	객체 다운로드
Head Object	객체 메타데이터 조회
List Objects	컨테이너 내 객체 목록 조회
Create Object	객체 업로드
Update Object Metadata	객체 메타데이터 수정
Delete Object	객체 삭제
Copy Object	객체 복사
Initiate Multipart Upload	멀티파트 업로드 초기화
Upload Part	멀티파트 파트 업로드
List Parts	업로드된 파트 목록 조회
List Multipart Uploads	진행 중인 멀티파트 업로드 목록 조회
Abort Multipart Upload	멀티파트 업로드 중단
Complete Multipart Upload	멀티파트 업로드 완료
Create SLO Manifest	Static Large Object(SLO) 매니페스트 업로드
Create DLO Manifest	Dynamic Large Object(DLO) 매니페스트 업로드
Get Object Temp URL	객체에 접근 가능한 임시 URL 발급 (확장)

Extension API 사용 가이드

GetBucketMeta

storage.buckets.get 권한이 있을 경우, 버킷의 메타 정보를 조회할 수 있습니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Request Syntax

 Request Syntax 
curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

GetBucketMeta Response Syntax 
  {
      "project": "1b3c5b406a194bf09ac446627a39d916",
      "account": "1b3c5b406a194bf09ac446627a39d916",
      "name": "bucket_name",
      "type": "STANDARD",
      "bytes": 0,
      "objectCount": 0,
      "createdAt": "2025-10-15T07:30:40Z",
      "use_encryption": true,
      "encryption_type": "managed",
      "lastModified": "2025-10-15T07:30:40Z",
      "storageClass": "STANDARD",
      "storagePolicy": "default-placement",
      "acl": {
          "public": "deny",
          "public_read_allow_ip_list": null
      }
  }

Response Header

Request	유형	필수 여부	설명
X-Container-Meta-*	String	필수	사용자 지정 Meta 정보

Response Elements

Response	유형	설명
project	string	프로젝트 ID
name	string	bucket 이름
type	string	bucket 유형 - `STANDARD`
bytes	int	bucket에 포함된 객체들의 총 용량 - 단, 30분마다 업데이트되며 현재 사용량과 차이가 있을 수 있음
objectCount	int	bucket에 포함된 객체들의 총 개수 - 단, 30분마다 업데이트되며 현재 개수와 차이가 있을 수 있음
createdAt	time	bucket 생성 일시
use_encryption	boolean	bucket의 암호화 여부
lastModified	time	bucket의 최종 수정 일시
storageClass	string	저장소 클래스 종류 - `STANDARD`
acl ▼	List	접근 관리 정책
public	string	퍼블릭 접근 허용 여부 - `read-only`,`deny`
public_read_allow_ip_list	string	퍼블릭 액세스가 허용된 IP 리스트 - IP 리스트가 설정되어 있는 경우, 토큰이 없는 접근은 해당 IP만 가능

CreateBucket

버킷을 생성합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket`

Request Syntax

 Request Syntax 
curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "bucket_name",
    "type": "STANDARD",
    "use_encryption": true,
    "encryption_configuration": {
        "type": "managed"
    }
}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)

Request Header

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

Request Body

Request Syntax 
  {
    "name": "bucket_name",
    "type": "STANDARD",
    "use_encryption": true,
    "encryption_configuration": {
      "type": "managed"
    }
  }

변수명	유형	필수 여부	설명
name	String	필수	버킷 이름
type	String	필수	버킷 유형 - `Standard`(기본값): standard 버킷
use_encryption	Boolean	선택	버킷 암호화 여부 `encryption_configuration` 설정을 입력하는 경우 입력값이 무시됨 - `false`(기본값): 암호화하지 않음 - `true`: 암호화 함 (encryption_configuration.type = managed와 동일)
encryption_configuration ▼	Structure	선택	버킷 암호화 설정
type	String	필수	암호화 방법 - `managed`(기본값): 카카오 클라우드에서 제공하는 자동 암호화 - `true`(지원 예정): KMS를 이용한 키 관리 서비스와 연계한 암호화

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

CreateBucket Response Syntax 
{
   "account": "project-id",
   "project": "project-id",
   "name": "bucket_name",
   "type": "STANDARD",
   "bytes": 0,
   "objectCount": 0,
   "createdAt": "2022-04-25T10:28:57Z",
   "acl": {
     "permissions": null,
     "public": "read-only",
     "public_read_allow_ip_list": [
       "ip / cidr"
     ]
   },
   "lastModified": "2022-04-25T10:28:57Z",
   "use_encryption": true,
   "encryption_type": "managed",
   "storageClass": "STANDARD",
   "storagePolicy": "default-placement"
}

Response Elements

Response	유형	설명
account (Deprecated)	String	프로젝트 ID - Swift API에서 Account 값. 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
project	String	프로젝트 ID
name	String	생성된 버킷 이름
type	String	생성된 버킷 유형 - `STANDARD`(기본값): standard 버킷
bytes	String	총 사용량 - 단위: Byte
objectCount	Int	버킷의 오브젝트 개수
createdAt	String	생성일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z
use_encryption	Boolean	버킷 암호화 여부 - `false`(기본값): 암호화하지 않음 - `true`: 암호화 함
encryption_type	String	버킷 암호화 유형
lastModified	String	최종 수정일 - 형식: RFC3339 - 예시: 2020-07-01T00:00:00Z
storageClass	String	스토리지 클래스 종류 - `STANDARD`(기본값): standard 클래스의 버킷
storagePolicy	String	스토리지 클래스의 존 - `default-placement`(기본값)
acl ▼	-	버킷에 대한 접근 권한 - `null` 입력 시, 기존 ACL 설정 삭제
public	String	퍼블릭 접근 허용 여부 - `read-only`, `deny`
public_read_allow_ip_list	List	퍼블릭 접근 허용 IP 리스트

DeleteBucket

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

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

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Request Syntax

 Request Syntax 
curl --request DELETE --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 204 응답을 받습니다.

ListBuckets

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

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket`

Request Syntax

ListBuckets Request Syntax 
curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket?limit=20&offset=0&direct=asc' \
--header 'X-Auth-Token: {x-auth-token}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)

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 검색 조건 - `STANDARD` (kr-central-2)
by	Query	선택	정렬 영역 - `bucket_name`: 버킷 이름 - `bucket_type`: 버킷의 유형 - `created_at`: 버킷 최종 수정일 - `bytes_used`: 버킷의 사용량
direct	Query	선택	정렬 순서 - `asc`: 오름차순(기본값) - `desc`: 내림차순

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

ListBuckets 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 참고

UpdateBucketAcl

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

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Request Syntax

 Request Syntax 
curl --request POST --location 'https://objectstorage.{region_name}.kakaocloud.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"
    ]
  }
}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

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

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

버킷 접근 관리 Response Syntax 
{
  "project": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "account": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "name": "my-bucket-new",
  "type": "STANDARD",
  "bytes": 0,
  "objectCount": 0,
  "createdAt": "2023-07-08T04:08:05Z",
  "use_encryption": true,
  "encryption_type": "managed",
  "lastModified": "2023-07-08T04:08:05Z",
  "storageClass": "STANDARD",
  "storagePolicy": "default-placement",
  "acl": {
    "public": "deny",
    "public_read_allow_ip_list": null
  }
}

Response Elements

Response	유형	설명
account (Deprecated)	String	프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID). 삭제 예정
project	String	프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID)
name	String	생성된 버킷 이름
type	String	생성된 버킷 유형 - `STANDARD`(기본값): standard 버킷
bytes	String	총 사용량- 단위: Byte
objectCount	Int	버킷의 오브젝트 개수
createdAt	String	생성일 - 형식: https://www.rfc-editor.org/rfc/rfc3339 - 예시: 2020-07-01T00:00:00Z
use_encryption	Boolean	버킷 암호화 여부 - `false`(기본값): 암호화하지 않음 - `true`: 암호화 함
encryption_type	String	버킷 암호화 유형
lastModified	String	최종 수정일 - 형식: https://www.rfc-editor.org/rfc/rfc3339 - 예시: 2020-07-01T00:00:00Z
storageClass	String	스토리지 클래스 종류 - `STANDARD`(기본값): standard 클래스의 버킷
storagePolicy	String	스토리지 클래스의 존 - `default-placement`(기본값)
acl ▼	-	버킷에 대한 접근 권한 - `null` 입력 시, 기존 ACL 설정 삭제
public	String	퍼블릭 접근 허용 여부 - `read-only`, `deny`
public_read_allow_ip_list	List	퍼블릭 접근 허용 IP 리스트

PutBucketLifecycleConfiguration

객체의 수명주기 정책을 설정할 수 있습니다.

warning

기존에 생성한 수명주기 정책은은 오버라이트됩니다. 따라서, 기존의 수명주기정책 에서 일부만 업데이트해야 할 경우에는 전체 설정을 받아 필요한 부분만 수정 후 업데이트를 요청해야 합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Request Syntax

 Request Syntax 
curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>2023-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Request Body

Request	유형	필수 여부	설명
Rule ▼	List	필수	수명주기 정책
ID	String	선택	Rule을 구분하는 ID - 255자 이내의 고유한 문자열
Expiration ▼	Structure	필수	삭제에 대한 설정 - Date 혹은 Days 필드를 반드시 입력 필요
Date	Timestamp	선택	Object를 삭제할 날짜 - GMT ISO 8601 포맷인 `2023-06-10T00:00:00.000Z`만 입력 가능
Days	integer	선택	Object의 생명 주기 - 생성일 기준으로 설정된 날짜가 지나면 Object가 삭제됨 - 0이 아닌 양수만 입력만 가능
Filter ▼	Structure	선택	수명주기 정책이 적용될 Object의 조건을 명시
Prefix	String	필수	Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체 필요 `'` → `&apos`; `”` → `&quot`; `&` → `&` `<` → `<` `>` → `>` `\r` → ` ` 또는 ` ` `\n` → ` ` 또는 ` ` 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
Status	String	필수	수명주기 정책 적용 여부 - Enabled : 활성화 - Disabled : 비활성화

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

수명주기 정책 설정Response Syntax
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376
 
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

Response Elements

Response	유형	설명
Rule ▼	List	수명주기 정책
ID	string	Rule을 구분하는 ID - 255자 이내의 고유한 문자열
Prefix	string	Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체됨 `'` → `'` `”` → `"` `&` → `&` `<` → `<` `>` → `>` `\r` → ` ` 또는 ` ` `\n` → ` ` 또는 ` ` 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
Status	string	수명주기 정책 적용 여부 - `Enabled`: 활성화 - `Disabled`: 비활성화
Expiration	integer	삭제에 대한 설정

GetBucketLifecycleConfiguration

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

안내

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

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Request Syntax

 Request Syntax 
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}' 

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

버킷 Lifecycle 목록 조회 Response Syntax 
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

Response Elements

Response	유형	설명
Rule ▼	List	Lifecycle 정책
ID	string	Rule을 구분하는 ID - 255자 이내의 고유한 문자열
Prefix	string	Rule을 적용할 Object의 Prefix - 다음의 특수 문자는 XML 엔티티 코드로 대체됨 `'` → `'` `”` → `"` `&` → `&` `<` → `<` `>` → `>` `\r` → ` ` 또는 ` ` `\n` → ` ` 또는 ` ` 자세한 설명은 AWS의 XML 관련 개체 키 제약 조건 문서 참고
Status	string	Lifecycle 적용 여부 - `Enabled` : Lifecycle 을 설정 - `Disabled` : Lifecycle 을 미설정
Expiration	integer	삭제에 대한 설정

DeleteBucketLifecycleConfiguration

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

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Request Syntax

 Request Syntax 
curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

GetBucketCors

storage.buckets.getIamPolicy 권한이 있을 경우, 개별 버킷에 대한 CORS 설정값을 조회할 수 있습니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors`

Request Syntax

 Request Syntax
curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

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 결과를 캐싱하는 수명

PutBucketCors

storage.buckets.setIamPolicy 권한이 있는 사용자는 개별 버킷에 대한 CORS 정책을 설정할 수 있습니다. Object Storage의 자세한 권한은 역할 및 권한를 참고하시기 바랍니다. 버킷에 대한 새로운 CORS 설정 적용 시, 리스트 전체가 업데이트됩니다.

안내

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

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors`

Request Syntax

CORS 정책 설정 Request Syntax
curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.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
    }
  ]
}'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
bucket_name	대상 버킷 이름

Request Header

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

Request Body

Request	유형	필수 여부	설명
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

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

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
    }
  ]
}

CORS Preflight 요청

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

버킷에 CORS가 설정되어 있는 경우, Swift(ext) API 또는 S3 API 경로로 CORS Preflight(OPTIONS) 요청을 수행할 수 있으며, 해당 요청은 버킷 및 객체 경로를 대상으로 CORS 응답 헤더를 반환합니다.

버킷에 CORS 정책이 설정되어 있는 경우, 브라우저는 실제 요청을 보내기 전에 OPTIONS 메서드를 사용하여 예비 요청(Preflight)을 수행합니다.
개발자는 테스트 목적으로 아래와 같이 curl을 통해 직접 확인할 수 있습니다.

Request Syntax

CORS Preflight 요청 Request Syntax
curl --location --request OPTIONS 'http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object_name}' \
--header 'Origin: https://www.example.com' \
--header 'Access-Control-Request-Headers: X-Auth-Token,Content-Type' \
--header 'Access-Control-Request-Method: GET'

Path Parameters

변수명	설명
region_name	서비스 리전 이름 (예: kr-central-2)
account	프로젝트 ID - 토큰 발급 시 확인 가능 (토큰 발급 과정에서 사용/확인된 프로젝트 ID) - Swift API에서 Account 값으로 사용
bucket_name	버킷 이름
object_name	객체 이름

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 요청 결과를 캐시할 수 있는 시간

상태 코드

CORS Preflight(OPTIONS) 요청에 대해 서버는 204 No Content 상태 코드로 응답하며, CORS 허용 여부는 응답 헤더(Access-Control-Allow-*)를 기준으로 판단됩니다.

안내

CORS 설정(PutBucketCors)을 완료한 후, 브라우저에서 403 Forbidden 에러가 발생한다면 Preflight 요청이 허용된 Origin과 Method를 반환하는지 위 curl 명령어로 먼저 확인하시기 바랍니다.

Swift API 사용 가이드

Head Container

API 호출 방식

메서드	요청 URL
HEAD	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}`

Request Syntax

 Head Container Request Syntax 
curl --request HEAD --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Response Header

Request	유형	설명
X-Container-Object-Count	Integer	버킷 내에 존재하는 총 객체의 수
X-Container-Bytes-Used	Integer	버킷에 저장된 객체들의 논리적 총 용량 (Byte)
X-Container-Bytes-Used-Actual	Integer	복제본(Replication) 등을 포함하여 실제로 디스크에 점유된 물리적 총 용량 (Byte)
X-Storage-Policy	String	버킷에 적용된 스토리지 정책 이름 (예: Policy-0)
X-Timestamp	Float	버킷이 생성되거나 마지막으로 수정된 시간의 Unix Timestamp
X-Trans-Id	String	요청 처리에 대한 고유 트랜잭션 식별자 (장애 대응 시 활용)
X-Openstack-Request-Id	String	OpenStack 서비스에서 부여한 요청 고유 ID
Content-Type	String	응답 데이터의 형식 (보통 text/plain; charset=utf-8)

List Containers

프로젝트 내에 생성된 모든 버킷 목록을 조회합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}`

Request Syntax

 List Containers Request Syntax 
curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

ListBuckets Response Syntax
[
  my-bucket-01
  my-bucket-02
  my-bucket-03
  my-bucket-04
  my-bucket-05
]

Response Header

Request	설명
X-Acoount-Container-Count	프로젝트(Acoount) 내에 생성된 총 버킷(Container)의 개수
X-Acoount-Object-Count	프로젝트 내 모든 버킷에 저장된 전체 객체(Object)의 총합
X-Acoount-Bytes-Used	프로젝트 내 모든 객체의 논리적 총 용량 사용자가 업로드한 원본 파일 크기의 합계 (단위: Byte)
X-Acoount-Bytes-Used-Actual	프로젝트 내 모든 객체가 실제로 점유 중인 물리적 용량 데이터 보호를 위한 복제본(Replication) 용량 (단위: Byte)
X-Acoount-Storage-Policy-Default-Placement-Container-Count	'Default-Placement' 정책이 적용된 버킷의 개수
X-Acoount-Storage-Policy-Default-Placement-Object-Count	'Default-Placement' 정책이 적용된 버킷 내 전체 객체의 개수
X-Acoount-Storage-Policy-Default-Placement-Bytes-Used	'Default-Placement' 정책 환경에서의 논리적 총 사용량
X-Acoount-Storage-Policy-Default-Placement-Bytes-Used-Actual	'Default-Placement' 정책 환경에서의 실제 물리적 총 점유량
X-Timestamp	해당 프로젝트 정보가 마지막으로 수정되거나 통계가 갱신된 시점의 Unix Timestamp
X-Trans-Id	해당 요청에 대해 시스템이 부여한 고유 트랜잭션 식별자 오류 발생 시 기술 지원을 위한 로그 추적에 사용
X-Openstack-Request-Id	OpenStack 인프라에서 부여한 요청 고유 ID

ListCapability

프로젝트가 사용 가능한 오브젝트 스토리지의 기능 및 권한 목록을 조회합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/info`

Request Syntax

 ListCapability Request Syntax 
curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/info'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)

Request Header

본 요청은 별도의 인증 헤더를 요구하지 않을 수 있습니다. (설정에 따라 상이)

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

ListCapability Response Syntax
{
    "swift": {
        "version": "objectstorage-api-v2.0.21-126",
        "Acoount_listing_limit": 1000,
        "max_meta_length": 4096,
        "min_meta_value_length": 0,
        "max_meta_value_length": 512,
        "container_listing_limit": 1000,
        "max_file_size": 5368709120,
        "max_object_name_length": 396,
        "min_object_name_length": 1,
        "min_meta_name_length": 2,
        "max_meta_name_length": 64,
        "max_Acoount_name_length": 32,
        "min_container_name_length": 4,
        "max_container_name_length": 63,
        "policies": [
            {
                "name": "default-placement",
                "default": true
            }
        ]
    },
    "tempurl": {
        "methods": [
            "GET"
        ]
    },
    "slo": {
        "max_manifest_segments": 1000,
        "min_segment_size": 1,
        "max_manifest_size": 8392704
    },
    "tempauth": {}
}

Response Element

Request	유형	설명
version	String	오브젝트 스토리지 API의 현재 버전
Acoount_listing_limit	Integer	한 번의 요청으로 조회 가능한 최대 버킷 리스트 수(1,000)
max_file_size	Integer	단일 업로드로 처리 가능한 최대 파일 크기 (단위: Byte, 약 5GB)
max_meta_name_length	Integer	메타데이터 키(Key) 이름의 최대 길이 (64자)
max_meta_value_length	Integer	메타데이터 값(Value)의 최대 길이 (512자)
max_meta_length	Integer	전체 메타데이터의 최대 합계 길이 (4,096자)
max_object_name_length	Integer	객체 이름(Key)의 최대 허용 길이 (396자)
min_container_name_length	Integer	버킷 이름의 최소 길이 (4자)
max_container_name_length	Integer	버킷 이름의 최대 길이 (63자)
policies	Array	지원되는 스토리지 정책 목록
policies.name	String	정책의 이름 (예: default-placement)
policies.default	Boolean	해당 정책이 기본으로 적용되는지 여부
tempurl	Object	임시 URL 발급 기능 관련 정보
methods	Array	임시 URL을 통해 허용되는 HTTP 메서드 목록 (예: GET)
slo	Object	정적 대용량 객체(Static Large Object) 관련 제약 사항
max_manifest_segments	Integer	하나의 SLO 매니페스트에 포함될 수 있는 최대 파트 수 (1,000개)
min_segment_size	Integer	SLO 구성 시 파트의 최소 크기 (1 Byte)
max_manifest_size	Integer	SLO 매니페스트 파일 자체의 최대 크기 (Byte)
tempauth	Object	임시 인증 모듈 활성화 여부를 나타내는 객체

Create Container

새 버킷을 생성합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}`

Request Syntax

 Create Container Request Syntax 
curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 201 응답을 받습니다.

Delete Container

버킷을 삭제합니다.

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}`

Request Syntax

 Delete Container Request Syntax 
curl --request DELETE --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 204 No Content 응답을 받습니다.

Update Container Metadata

버킷의 메타데이터를 생성, 수정, 삭제 합니다.

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}`

Request Syntax

 Update Container Metadata Request Syntax 
curl --request POST --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Type	String	필수	`application/json`으로 고정
X-Container-Meta-`key`	String	선택	메타 데이터 값 Value ex) `key` = 메타데이터 Key 이름, Value = 메타 데이터값
X-Remove-Container-Meta-`key`	String	선택	메타 데이터 삭제

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 204 No Content 응답을 받습니다.

Get Object

객체를 다운로드 합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}`

Request Syntax

 Get Object Request Syntax 
curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다. 요청된 객체를 불러옵니다.

Response Header

Request	설명
Date	response 생성 시간
Content-Type	body에 담긴 content의 형식
Content-Length	Object 크기
Connection	connection 재활용 여부
Accept-Ranges	클라이언트가 원하는 파일의 일부분을 바이트 단위로 요청할 수 있음
Etag	웹 서버가 리소스의 내용이나 메타데이터가 변경되었는지를 식별하기 위한 식별자
Last-Modified	마지막 수정일
X-Object-Storage-Class	Integer
X-Openstack-Request-Id	String
X-Trans-Id	String
X-Rgw-Object-Type	String

Head Object

객체 Head 정보를 조회합니다.

API 호출 방식

메서드	요청 URL
HEAD	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}`

Request Syntax

 Head Object Request Syntax 
curl --request HEAD --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Response Header

Request	설명
Date	response 생성 시간
Content-Type	body에 담긴 content의 형식
Content-Length	Object 크기
Connection	connection 재활용 여부
Accept-Ranges	클라이언트가 원하는 파일의 일부분을 바이트 단위로 요청할 수 있음
Etag	웹 서버가 리소스의 내용이나 메타데이터가 변경되었는지를 식별하기 위한 식별자
Last-Modified	마지막 수정일
X-Object-Storage-Class	Integer
X-Openstack-Request-Id	String
X-Trans-Id	String
X-Rgw-Object-Type	String

List Objects

버킷에 저장된 오브젝트(파일, 폴더) 목록을 조회합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}?format=json`

Request Syntax

 List Containers Request Syntax 
curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}?format=json' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름

Request Query

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

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

List Objects Response Syntax
[
    {
        "name": "apple1.JPG",
        "hash": "4fabff2e18b68ae780cf0bc54d1fec82",
        "bytes": 1699756,
        "content_type": "image/jpeg",
        "last_modified": "2026-02-19T04:44:38.302Z"
    },
]    

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`인 경우 이 값만 제공됨

Create Object

버킷에 객체를 업로드 한다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}`

Request Syntax

 Create Object Request Syntax 
curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'
--data-binary {local_file_part_path}

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

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

객체 데이터. (업로드하는 실제 데이터입니다.)
파일 스트림(Byte Stream)을 본문에 직접 담아 전송합니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Update Object Metadata

객체의 메타데이터를 생성, 수정, 삭제 합니다.

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}`

Request Syntax

 Update Object Metadata Request Syntax 
curl --request POST --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

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	선택	콘텐츠 길이

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Delete Object

객체를 삭제합니다.

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}`

Request Syntax

 Delete Object Request Syntax 
curl --request DELETE --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Query

Request	유형	필수 여부	설명
multipart-manifest	Query	필수	`delete` 값을 입력하여 연결된 모든 세그먼트를 함께 삭제하도록 지정합니다.

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 204 응답을 받습니다.

Copy Object

객체를 복사 합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{dest_Bucket_Name}/{dest_Object_Key}`

Request Syntax

 Copy Object Request Syntax 
curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{dest_Bucket_Name}/{dest_Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Length: 0' \
--header 'X-Copy-From: /{src_bucket_name}/{src_object_key}' 

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
dest_Bucket_Name	복사된 객체가 저장될 대상(목적지) 버킷 이름
dest_Object_Key	복사되어 새로 생성될 대상(목적지) 객체의 고유 키(경로 포함)

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
Content-Length	String	필수	`application/json`으로 고정
X-Fresh-Metadata	String	선택	`True`로 설정 시 원본의 메타데이터를 복사하지 않고 요청에 포함된 새 메타데이터만 적용
X-Copy-From	String	필수	원본 객체의 경로

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 201 응답을 받습니다.

Initiate Multipart Upload

대용량 객체 업로드를 위해 멀티파트 업로드를 **초기화(Initiate)**합니다.
이 요청이 성공해야만 파일 조각(Part)들을 올릴 수 있는 고유한 UploadId가 발급됩니다.

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_name}/{Object_Key}?uploads`

Request Syntax

 Initiate Multipart Upload Request Syntax 
curl --request POST --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_name}/{Object_Key}?uploads` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

DeleteObjects Response Syntax
    <?xml version="1.0" encoding="UTF-8"?>
    <InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Tenant>String</Tenant>
        <Bucket>String</Bucket>
        <Key>String</Key>
        <UploadId>String</UploadId>
    </InitiateMultipartUploadResult>

Response Elements

Response	설명
Tenant	프로젝트 ID
Bucket	업로드가 진행되는 버킷 이름
Key	업로드될 객체의 이름 (Path)
UploadId	멀티파트 업로드를 식별하는 고유 ID. UploadPart, CompleteMultipartUpload 호출 시 사용

Upload Part

대용량 객체를 여러 개의 파트로 나누어 업로드합니다.
모든 파트 업로드가 완료된 후 CompleteMultipartUpload를 호출하여 하나의 객체로 결합해야 합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?partNumber={n}&uploadId={Upload_Id}`

Request Syntax

 Upload Part Request Syntax 
curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?partNumber={n}&uploadId={Upload_Id}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/octet-stream' \
--upload-file {local_file_part_path}

Path Parameters

| Path | 설명 | | --- | --- | --- | --- | | Region_Name | 서비스 리전 이름 (예: kr-central-2) | | Acoount | 프로젝트의 고유 ID | | Bucket_Name | 버킷 이름 | | Object_Key | 객체의 고유 키(경로 포함) |

Request Query

Request	유형	필수 여부	설명
uploadId	Query	필수	Initiate Multipart Upload에서 반환된 large object의 고유 upload id
partNumber	Query	필수	현재 업로드하는 부분 파일의 large object 상 부분 순번 (1~10000)

Request Header

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

Request Body

객체 데이터. (업로드하는 실제 데이터입니다.)
파일 스트림(Byte Stream)을 본문에 직접 담아 전송합니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 201 응답을 받습니다.

Response Header

Request	설명
Date	response 생성 시간
Etag	웹 서버가 리소스의 내용이나 메타데이터가 변경되었는지를 식별하기 위한 식별자
X-Trans-Id	String
X-Openstack-Request-Id	String

List Part

특정 멀티파트 업로드에 대해 성공적으로 업로드된 파트 목록을 조회합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={Upload_Id}`

Request Syntax

 List Part Request Syntax 
curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={Upload_Id}' \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Query

Request	유형	필수 여부	설명
uploadId	Query	필수	Initiate Multipart Upload에서 반환된 large object의 고유 upload id

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Response Header

Request	설명
Date	response 생성 시간
Etag	웹 서버가 리소스의 내용이나 메타데이터가 변경되었는지를 식별하기 위한 식별자
X-Trans-Id	String
X-Openstack-Request-Id	String

List Multipart Uploads

특정 버킷에서 완료되지 않고 진행 중인 모든 멀티파트 업로드 목록을 조회합니다.

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploads`

Request Syntax

 List Multipart Uploads Request Syntax 
curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploads` \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

List Multipart Uploads Response Syntax
  <?xml version="1.0" encoding="UTF-8"?>
  <ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Tenant>String</Tenant>
      <Bucket>String</Bucket>
      <NextKeyMarker>String</NextKeyMarker>
      <NextUploadIdMarker>String</NextUploadIdMarker>
      <MaxUploads>Integer</MaxUploads>
      <IsTruncated>Boolean</IsTruncated>
      <Upload>
          <Key>String</Key>
          <UploadId>String</UploadId>
          <Initiator>
              <ID>String</ID>
              <DisplayName>String</DisplayName>
          </Initiator>
          <Owner>
              <ID>String</ID>
              <DisplayName>String</DisplayName>
          </Owner>
          <StorageClass>String</StorageClass>
          <Initiated>Timestamp</Initiated>
      </Upload>
  </ListMultipartUploadsResult>

Response Elements

Response	유형	설명
Tenant	String	프로젝트 ID
Bucket	String	버킷 이름
NextKeyMarker	String	다음 요청에서 key-marker 요청 매개변수에 사용해야 하는 값
NextUploadIdMarker	String	다음 요청에서 upload-id-marker 요청 매개변수에 사용해야 하는 값
MaxUploads	Integer	멀티파트 업로드의 최대 수
IsTruncated	String	Part 목록이 잘렸는지 여부
Key	String	업로드할 객체 키
UploadId	String	멀티파트 업로드 ID
ID	String	프로젝트 ID
DisplayName	String	프로젝트 이름
StorageClass	String	스토리지 클래스
Initiated	Timestamp	멀티파트 업로드 시작 일시

Abort Multipart Upload

진행 중인 멀티파트 업로드를 중단하고 업로드된 모든 파트를 삭제합니다.
중단된 UploadId는 더 이상 사용할 수 없습니다.

API 호출 방식

메서드	요청 URL
DELETE	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}`

Request Syntax

 Abort Multipart Upload Request Syntax 
curl --request DELETE --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}` \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Query

Request	유형	필수 여부	설명
uploadId	Query	필수	Initiate Multipart Upload에서 반환된 large object의 고유 upload id

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 204 응답을 받습니다.

CompleteMultipartUpload

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}`

Request Syntax

 CompleteMultipartUpload Request Syntax 
curl --request POST --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"897a0f868d69985acdbf1e9f9d6f3603"</ETag>
    </Part>
</CompleteMultipartUpload>'

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Query

Request	유형	필수 여부	설명
uploadId	Query	필수	Initiate Multipart Upload에서 반환된 large object의 고유 upload id

Request Header

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

Request Body

CompleteMultipartUpload Response Syntax
<CompleteMultipartUpload>
   <Part>
      <ETag>String</ETag>
      <PartNumber>Integer</PartNumber>
   </Part>
   ...
</CompleteMultipartUpload>

Request Elements

Request	유형	필수 여부	설명
ETag	String	선택	객체의 해시값
PartNumber	Integer	선택	파트 식별 번호 (1 - 10,000 사이의 양의 정수)

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

SLO(Static Large Object) 방식

SLO 방식은 DLO와 동일하게 Segment를 분할해 업로드하지만, Segment Naming 제약이 없고 사이즈가 동일하지 않아도 된다는 차이점이 있습니다. 또한, Manifest를 제일 마지막에 업로드해야 합니다. SLO Manifest Object는 Segment Object 목록을 순서대로 작성하여 입력해야 합니다. 현재 KC Object Storage에서는 최대 1,000개의 Segment Object를 하나의 Manifest에 입력할 수 있습니다.

SLO Manifest Object 생성 요청을 하면 각 Segment Object가 입력된 경로에 있는지, etag Value와 Segment object Size가 일치하는지 확인합니다. 정보가 일치하지 않으면 Manifest Object가 생성되지 않습니다. 또한, Manifest에 etag를 통해 Segment Object의 무결성을 보장합니다.

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

안내

Manifest에 대한 자세한 예제는 https://objectstorage.kr-central-2.kakaocloud.com/info에서 참고하시기 바랍니다.

Create SLO Manifest

업로드된 세그먼트(조각)들의 정보를 담은 JSON 매니페스트 파일을 업로드하여 하나의 정적 대용량 객체(SLO)를 생성합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{SLO Manifest Object}?multipart-manifest=put`

Request Syntax

 Create SLO Manifest Request Syntax 
curl --request PUT --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{SLO Manifest Object}?multipart-manifest=put` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '[
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   },
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   },
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   }
]'

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
SLO Manifest Object	Manifest Object 이름

Request Header

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

Request Body

Create SLO Manifest Response Syntax
[
   {
      "path": "jay-cool-1/video_part_aa",
      "etag": "841aa70a236b55d22260aa4defe699cf",
      "size_bytes": 52428800
   },
   {
      "path": "jay-cool-1/video_part_ab",
      "etag": "30c4e8955088e398b2b87d52554d3f90",
      "size_bytes": 23052099
   }
   ...
]

Request Elements

Request	유형	필수 여부	설명
Path	String	필수	`Path/Segment Object` 형식으로 입력 - Path: Object를 업로드할 경로 - Segment Object: path 하위의 Segment object
ETag	String	필수	객체의 해시값
size_bytes	Integer	필수	Segment Object 사이즈

안내

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

Response Syntax

동작에 성공하면, 서비스는 HTTP 201 응답을 받습니다.

Create DLO Manifest

특정 접두어(Prefix)를 가진 객체들을 하나의 큰 객체로 묶어주는 매니페스트 파일을 생성합니다.

API 호출 방식

메서드	요청 URL
PUT	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{DLO Manifest Object}`

Request Syntax

 Create DLO Manifest Request Syntax 
curl --request PUT --location `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}/{Segment_Object_Prefix}' \
--header 'Content-Length: 0'

Path Parameters

Path	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

Request	유형	필수 여부	설명
X-Auth-Token	String	필수	사용자 인증 토큰
X-Object-Manifest	String	필수	조각 파일들이 위치한 `{버킷명}/{접두어}`를 지정합니다. - 오름차순 Sequence Number Naming 필요함 (예시: segment_0001 ... segment_0002 )

Response Syntax

동작에 성공하면, 서비스는 HTTP 201 응답을 받습니다.

Get Object Temp URL

Object 다운로드용 Temp URL 생성

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

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}`

Request Syntax

 Object 다운로드용 Temp URL 생성 Request Syntax 
curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}` \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Header

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

Request Query

Request	유형	필수 여부	설명
temp_url	String	필수	TempUrl 발급 요청을 나타내는 키
temp_url_expires	timestamp	필수	발급된 TempUrl의 유효시간 - sec 단위

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다.

Response Body

Get Object Temp URL response Syntax
    {
        "url": "/v1/{project_id}/object-reg-test-1/test.txt?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}",
        "sig": "{sig}"
    }

Response Elements

Response	유형	설명
url	string	해당 오브젝트를 expire 시간 안에 다운로드 받을 수 있는 임시 URL
sig	string	해당 URL의 signature이며 object의 expire 시간 안에서 유효한 signature

Temp URL을 사용한 Object 다운로드

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

API 호출 방식

메서드	요청 URL
GET	`https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}`

Request Syntax

 Temp URL을 사용한 Object 다운로드 Request Syntax 
curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}` \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

변수명	설명
Region_Name	서비스 리전 이름 (예: kr-central-2)
Acoount	프로젝트의 고유 ID
Bucket_Name	대상 버킷 이름
Object_Key	객체의 고유 키(경로 포함)

Request Query

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

Request Header

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

Request Body

이 요청은 Body 값을 가지지 않습니다.

Response Syntax

동작에 성공하면, 서비스는 HTTP 200 응답을 받습니다. 요청된 객체를 불러옵니다.

공통 상태 코드

HTTP Status	응답 내용	설명
`200`	OK	성공
`204`	No Content	성공
`400`	BadRequest	요청 정보 오류
`401`	Unauthorized	인증 실패
`403`	Forbidden	권한 없음
`404`	Not Found	요청한 리소스를 찾을 수 없음
`409`	Conflicts	충돌

API 사용 준비​

API 엔드포인트 URL​

제공되는 기능 목록​

Extension API 지원 목록​

Swift API 지원 목록​

Extension API 사용 가이드​

GetBucketMeta​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Body​

Response Syntax​

Response Header​

Response Elements​

CreateBucket​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Body​

Response Syntax​

Response Elements​

DeleteBucket​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Body​

Response Syntax​

ListBuckets​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Query​

Response Syntax​

Response Elements​

UpdateBucketAcl​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

PutBucketLifecycleConfiguration​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Body​

Response Syntax​

Response Elements​

GetBucketLifecycleConfiguration​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Response Syntax​

Response Elements​

DeleteBucketLifecycleConfiguration​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Response Syntax​

GetBucketCors​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Response Syntax​

Response Elements​

PutBucketCors​

API 호출 방식​

Request Syntax​

Path Parameters​

Request Header​

Request Body​

API 사용 준비

API 엔드포인트 URL

제공되는 기능 목록

Extension API 지원 목록

Swift API 지원 목록

Extension API 사용 가이드

GetBucketMeta

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Body

Response Syntax

Response Header

Response Elements

CreateBucket

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Body

Response Syntax

Response Elements

DeleteBucket

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Body

Response Syntax

ListBuckets

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Query

Response Syntax

Response Elements

UpdateBucketAcl

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Elements

Response Syntax

Response Elements

PutBucketLifecycleConfiguration

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Body

Response Syntax

Response Elements

GetBucketLifecycleConfiguration

API 호출 방식

Request Syntax

Path Parameters

Request Header

Response Syntax

Response Elements

DeleteBucketLifecycleConfiguration

API 호출 방식

Request Syntax

Path Parameters

Request Header

Response Syntax

GetBucketCors

API 호출 방식

Request Syntax

Path Parameters

Request Header

Response Syntax

Response Elements

PutBucketCors

API 호출 방식

Request Syntax

Path Parameters

Request Header

Request Body