Object Storage

개요

네이버 클라우드 플랫폼 Object Storage 는 스토리지 관리와 사용에 필요한 S3 API 를 제공합니다.

버전: Amazon S3 v2006-03-01

호출 도메인(Endpoint)

HTTP/HTTPS 프로토콜을 모두 지원하지만 데이터 보호를 위해 HTTPS 사용을 권장합니다.

리전 별 호출 도메인

리전 리전 이름 호출 도메인
한국 kr-standard https://kr.object.ncloudstorage.com
미국서부(New) us-standard https://us.object.ncloudstorage.com
싱가포르(New) sg-standard https://sg.object.ncloudstorage.com
일본(New) jp-standard https://jp.object.ncloudstorage.com
독일(New) de-standard https://de.object.ncloudstorage.com

제공 리전은 지속적으로 확대해갈 예정입니다.

인증키(Credential)

포탈 마이페이지 > 계정 관리 > 인증키 관리에서 생성한 API 인증키를 사용합니다.



아래는 S3 API를 사용하여 네이버 클라우드 플랫폼 Object Storage에 접근할 때 사용할 수 있는 모든 오퍼레이션을 설명합니다. 예를 포함하여 오퍼레이션 사용법에 대한 추가 정보를 확인하려면 버킷 오퍼레이션, 오브젝트 오퍼레이션 페이지를 참고하세요.

계정 관련 오퍼레이션

계정 레벨에서는 해당 계정에 속한 버킷 목록을 조회하는 오퍼레이션만 지원합니다. 계정의 버킷 개수는 1,000 개로 제한됩니다.

오퍼레이션 설명
GET Account(List Buckets) 계정에 속한 버킷 목록을 조회합니다.

버킷 오퍼레이션

버킷을 생성, 삭제, 조회, 제어하는 오퍼레이션을 설명합니다.

버킷 내의 오브젝트 목록 조회 GET Bucket (List Objects) Version 2 는 지원하지 않습니다.

오퍼레이션 설명
PUT Bucket 버킷을 생성합니다. 계정의 버킷 개수는 1,000 개로 제한됩니다.
GET Bucket(List Objects) 버킷에 포함된 오브젝트를 조회합니다. 한 번에 최대 1,000 개의 오브젝트가 나열됩니다.
HEAD Bucket 버킷 헤더를 조회합니다.
DELETE Bucket 빈 버킷을 삭제합니다.
PUT Bucket ACL 버킷에 적용할 접근 제어 목록(ACL)을 생성합니다.
GET Bucket ACL 버킷에 적용된 접근 제어 목록(ACL)을 조회합니다.
PUT Bucket CORS 버킷에 적용할 CORS 설정을 생성합니다.
GET Bucket CORS 버킷에 적용된 CORS 설정을 조회합니다.
DELETE Bucket CORS 버킷에 적용된 CORS 설정을 삭제합니다.
List Multipart Uploads 완료되지 않았거나 취소된 멀티파트 업로드를 조회합니다.

오브젝트 오퍼레이션

오브젝트를 생성, 삭제, 조회, 제어하는 오퍼레이션을 설명합니다.

오퍼레이션 설명
PUT Object 버킷에 오브젝트를 추가(업로드)합니다.
PUT Object (Copy) 오브젝트 복사본을 생성합니다.
GET Object 오브젝트를 조회(다운로드)합니다.
HEAD Object 오브젝트 헤더를 조회합니다.
DELETE Object 버킷에서 오브젝트를 삭제합니다.
DELETE Multiple Objects 버킷에서 멀티파트 오브젝트를 삭제합니다.
PUT Object ACL 오브젝트에 적용할 접근 제어 목록(ACL)을 생성합니다.
GET Object ACL 오브젝트에 적용된 접근 제어 목록(ACL)을 조회합니다.
OPTIONS Object CORS 설정을 확인하여 특정 요청을 전송할 수 있는지 조회합니다.
Initiate Multipart Upload 업로드할 파트 집합에 지정할 업로드 ID 를 생성합니다.
Upload Part 업로드 ID 와 연관된 오브젝트의 파트를 업로드합니다.
Complete Multipart Upload 업로드 ID 와 연관된 파트로 분리된 오브젝트를 결합합니다.
Abort Multipart Upload 업로드를 중단하고 업로드 ID 와 연관된 파트를 삭제합니다.

공통 헤더

공통 요청 헤더

다음 표는 네이버 클라우드 플랫폼 Object Storage 에서 지원하는 공통 요청 헤더를 설명합니다.

네이버 클라우드 플랫폼 Object Storage 는 다음 표에 나열되지 않은 공통 헤더는 요청이 전송됐더라도 무시합니다.

단, 요청 중 일부는 이 문서에 정의된 바와 같이 다른 헤더를 지원할 수 있습니다. 인증 헤더 생성에 대한 자세한 내용은 “인증 관리” 페이지에서 확인할 수 있습니다.

헤더 설명
Authorization 필수(AWS Signature Version 4)
Host 필수
x-amz-date 필수. Date 로 지정될 수 있습니다.
x-amz-content-sha256 필수. 단, 오브젝트 업로드 시 또는 본문에 요청 정보가 포함된 경우에 해당합니다.
Content-Length 필수. 단, 오브젝트 업로드 시에 해당합니다. 청크 인코딩(chunked encoding)이 지원됩니다.
Content-MD5 전송 중인 요청 본문의 128 비트 MD5 해시값
Expect 100-continue 인 경우 요청 본문 전송 전에 헤더가 승인될 때까지 대기합니다.

공통 응답 헤더

다음 표는 공통 응답 헤더를 설명합니다.

헤더 설명
Content-Length 요청 본문의 길이(단위: 바이트)
Connection 연결됐는지 여부
Date 요청 메시지의 타임스탬프
ETag 요청 메시지의 MD5 해시값
x-amz-request-id 요청 시 생성된 고유 식별자

오류 코드

오류 코드 설명 HTTP 상태 코드
AccessDenied 접근이 거부되었습니다. 403 Forbidden
BadDigest 지정한 Content-MD5 가 수신한 내용과 일치하지 않습니다. 400 Bad Request
BucketAlreadyExists 요청한 버킷 이름을 사용할 수 없습니다. 해당 버킷의 네임스페이스는 시스템을 이용하는 모든 사용자가 공유합니다. 다른 이름을 선택한 후 다시 시도하세요. 409 Conflict
BucketNotEmpty 삭제하려는 버킷이 비어 있지 않습니다. 409 Conflict
CredentialsNotSupported 해당 요청은 Credentials 을 지원하지 않습니다. 400 Bad Request
EntityTooSmall 업로드하려는 오브젝트의 크기가 허용되는 최소 크기보다 작습니다. 400 Bad Request
EntityTooLarge 업로드하려는 오브젝트의 크기가 허용되는 최대 크기를 초과했습니다. 400 Bad Request
IncompleteBody Content-Length HTTP 헤더에 값을 지정하지 않았습니다. 400 Bad Request
IncorrectNumberOfFilesInPostRequest POST 요청으로는 파일을 하나만 업로드할 수 있습니다. 400 Bad Request
InlineDataTooLarge 인라인 데이터의 크기가 허용된 최대 크기를 초과했습니다. 400 Bad Request
InternalError 내부 오류가 발생했습니다. 다시 시도하세요. 500 Internal Server Error
InvalidAccessKeyId 입력한 AWS 액세스 키 아이디가 데이터베이스에 존재하지 않습니다. 403 Forbidden
InvalidArgument 유효하지 않은 파라미터입니다. 400 Bad Request
InvalidArgument 시크릿 키의 MD5 해시값이 잘못되었습니다. MD5 해시는 Base64 인코딩되어야 합니다. 400 Bad Request
InvalidArgument MD5 해시값이 입력하신 값과 일치하지 않습니다. 400 Bad Request
InvalidBucketName 지정한 버킷이 유효하지 않습니다. 400 Bad Request
InvalidBucketState 해당 요청은 현재의 버킷 상태로는 유효하지 않습니다. 409 Conflict
InvalidDigest 지정한 Content-MD5 가 유효하지 않습니다. 400 Bad Request
InvalidEncryptionAlgorithmError 지정한 Encryption 요청이 유효하지 않습니다. 지원되는 값은 AES256 입니다. 400 Bad Request
InvalidLocationConstraint 지역 제약 조건이 유효하지 않습니다. 400 Bad Request
InvalidObjectState 현재의 오브젝트 상태에서는 해당 오퍼레이션이 유효하지 않습니다. 403 Forbidden
InvalidPart 지정된 파트 중 하나 이상을 찾을 수 없습니다. 해당 파트가 업로드되지 않았거나 지정된 엔티티 태그가 파트의 엔티티 태그와 일치하지 않을 수 있습니다. 400 Bad Request
InvalidPartOrder 파트 목록이 오름차순으로 정렬되지 않았습니다. 파트 번호순으로 정렬되어야 합니다. 400 Bad Request
InvalidRange 요청한 범위를 충족시킬 수 없습니다. 416 Requested Range Not Satisfiable
InvalidRequest AWS4-HMAC-SHA256 알고리즘을 사용하세요. 400 Bad Request
InvalidSecurity 입력하신 보안 Credentials 이 유효하지 않습니다. 403 Forbidden
InvalidURI 지정된 URI 의 구문을 분석할 수 없습니다. 400 Bad Request
KeyTooLong 키가 너무 깁니다. 400 Bad Request
MalformedACLError 입력하신 XML 형식이 올바르지 않거나, 게시된 스키마의 유효성을 검사하지 않았습니다. 400 Bad Request
MalformedPOSTRequest POST 요청 본문의 multipart/form-data 속성값이 올바르지 않습니다. 400 Bad Request
MalformedXML 설정이 잘못된 XML(XSD 규정을 따르지 않는 XML)을 전송할 때 발생하는 오류입니다. 오류 메시지는 다음과 같습니다. “The XML you provided was not well-formed or did not validate against our published schema.” 400 Bad Request
MaxMessageLengthExceeded 요청이 너무 깁니다. 400 Bad Request
MaxPostPreDataLengthExceededError 업로드 파일 앞의 POST 요청 필드가 너무 큽니다. 400 Bad Request
MetadataTooLarge 메타데이터의 헤더 크기가 허용된 최대 크기를 초과했습니다. 400 Bad Request
MethodNotAllowed 지정한 메서드는 이 리소스에 사용할 수 없습니다. 405 Method Not Allowed
MissingContentLength Content-Length HTTP 헤더를 제공해야 합니다. 411 Length Required
MissingRequestBodyError 빈 XML 문서를 전송할 때 발생하는 오류입니다. 오류 메시지는 다음과 같습니다. “Request body is empty.” 400 Bad Request
NoSuchBucket 지정한 버킷이 존재하지 않습니다. 404 Not Found
NoSuchKey 지정한 키가 존재하지 않습니다. 404 Not Found
NoSuchUpload 지정한 멀티파트 업로드가 존재하지 않습니다. 업로드 ID 가 유효하지 않거나, 멀티파트 업로드가 중단 또는 완료되었을 수 있습니다. 404 Not Found
NotImplemented 입력하신 헤더는 구현되지 않은 기능을 의미합니다. 501 Not Implemented
OperationAborted 조건부 연산이 이 리소스와 충돌합니다. 다시 시도하세요. 409 Conflict
PreconditionFailed 지정한 전제 조건 중 하나 이상이 수행되지 않았습니다. 412 Precondition Failed
Redirect 임시로 새 위치로 리디렉션합니다. 307 Moved Temporarily
RequestIsNotMultiPartContent 버킷 POST 요청에는 enclosure-type multipart/form-data 속성값을 지정해야 합니다. 400 Bad Request
RequestTimeout 소켓 연결이 제한 시간 내에 서버에 도달하지 못했습니다. 400 Bad Request
RequestTimeTooSkewed 요청 시간과 서버 시간 간의 차이가 너무 큽니다. 403 Forbidden
SignatureDoesNotMatch 입력하신 서명값이 측정된 서명값과 일치하지 않습니다. AWS 시크릿 키와 서명 방식을 확인하세요. 403 Forbidden
ServiceUnavailable 요청 빈도를 줄여 주세요. 503 Service Unavailable
SlowDown 요청 빈도를 줄여 주세요. 503 Slow Down
TemporaryRedirect DNS 를 업데이트하는 동안 버킷으로 리디렉션하고 있습니다. 307 Moved Temporarily
TooManyBuckets 버킷 생성 허용 개수를 초과했습니다. 400 Bad Request
UnexpectedContent 해당 요청은 콘텐츠를 지원하지 않습니다. 400 Bad Request
UnresolvableGrantByEmailAddress 입력하신 메일 주소와 일치하는 계정이 데이터베이스에 존재하지 않습니다. 400 Bad Request
UserKeyMustBeSpecified 버킷 POST 요청은 지정된 필드 이름을 포함해야 합니다. 필드 이름이 지정돼 있다면 필드 순서를 확인하세요. 400 Bad Request

인증

네이버 클라우드 플랫폼 Object Storage API 의 인증은 Authorization 헤더를 통해 이루어지고, 인증 방법은 Object Storage API 사용 가이드에서 확인하실 수 있습니다.

접근 제어 목록(ACL)

네이버 클라우드 플랫폼 Object Storage 서비스를 이용 중인 회원을 대상으로 버킷과 오브젝트에 접근 권한을 부여할 수 있습니다.

네이버 클라우드 플랫폼 Object Storage 이용신청을 완료한 회원은 Object Storage에서 사용할 수 있는 ID가 발급됩니다.
이 ID는 버킷과 오브젝트의 접근 권한을 설정할 때 사용됩니다.

또한 인증없이 접근 가능하도록 public-read, public-write 권한 설정도 가능합니다.

다음 표는 권한 종류와 해당 권한이 부여된 경우 가능한 오퍼레이션을 설명합니다.

권한 버킷에 부여된 경우 오브젝트에 부여된 경우
READ 버킷에 속한 오브젝트 목록 조회가 가능합니다. 오브젝트 데이터와 메타데이터의 읽기가 가능합니다.
WRITE 새 오브젝트를 생성하거나 기존 오브젝트의 덮어쓰기 또는 삭제가 가능합니다. N/A
READ_ACP 버킷의 ACL 조회가 가능합니다. 오브젝트의 ACL 조회가 가능합니다.
WRITE_ACP 버킷의 ACL 설정이 가능합니다. 오브젝트의 ACL 설정이 가능합니다.
FULL_CONTROL READ, WRITE, READ_ACP, WRITE_ACP 권한으로 가능한 모든 오퍼레이션을 수행할 수 있습니다. READ, READ_ACP, WRITE_ACP 권한으로 가능한 모든 오퍼레이션을 수행할 수 있습니다.

다음 표는 NCP 오브젝트 스토리지에서 지원하는 기본 ACL을 설명합니다. 이 표에 언급되지 않은 값은 지원되지 않습니다.

기본 ACL 적용 대상 설명
private 버킷, 오브젝트 소유자에게 FULL_CONTROL 권한을 부여합니다. (default)
public-read 버킷, 오브젝트 소유자에게 FULL_CONTROL 권한을 부여하고, 모든 사용자에게 READ 권한을 부여합니다.
public-read-write 버킷, 오브젝트 소유자에게 FULL_CONTROL 권한을 부여하고, 모든 사용자에게 READ와 WRITE 권한을 부여합니다.
authenticated-read 버킷, 오브젝트 소유자에게 FULL_CONTROL 권한을 부여하고, 인증된 사용자에게 READ 권한을 부여합니다.

public-read를 포함하여 READ 권한이 버킷에 적용된 경우에는 오브젝트를 조회만 할 수 있을 뿐 오브젝트 자체에는 접근할 수 없습니다.

아쉬운 점이 있다면 이야기해 주세요.
0/5000
내용을 입력해 주세요
의견 보내기