Ncloud Storage 개요

Prev Next

Classic/VPC 환경에서 이용 가능합니다.

Ncloud Storage는 뛰어난 확장성, 가용성, 데이터 내구성을 보장하며, 언제든 데이터를 저장하고 검색할 수 있는 네이버 클라우드 플랫폼의 오브젝트 스토리지 서비스입니다. Ncloud Storage 서비스에서는 버킷 관리, 객체 업로드 등 데이터를 저장하고 관리하는 기능에 대한 API를 RESTful 형태로 제공합니다.

참고

Ncloud Storage API는 Amazon S3 API v2006-03-01과 높은 수준으로 호환되도록 설계되어 있습니다. Ncloud Stroage API에 대한 추가적인 정보는 AWS의 S3 API Reference를 참조해 주십시오.

Ncloud Storage 공통 설정

Ncloud Storage API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.

요청

공통 요청 형식을 설명합니다.

API URL

요청 API URL은 다음과 같습니다.

https://{Bucket}.{regionCode}.ncloudstorage.com

Bucket과 regionCode에 대한 설명은 다음과 같습니다.

구성 요소 필수 여부 설명
Bucket Optional 버킷 이름
  • 영문 소문자, 숫자, 특수 문자 '-'를 조합하여 3~63자 이내
  • 문자열의 시작과 끝은 영문 또는 숫자로 구성
  • 특정 접두사 및 접미사 사용 불가: 버킷 이름 규칙 참조
  • 버킷 이름 확인: ListBuckets 참조
regionCode Required 리전 코드
  • kr: 한국 리전 (유효값)
참고

API URL 관련하여 다음 내용을 참고해 주십시오.

  • HTTP/HTTPS 프로토콜을 지원합니다. 단, 데이터 보호를 위해 HTTPS 사용을 권장합니다.
  • 현재 한국 리전을 지원하고 있으며, 지원 리전은 지속적으로 추가 예정입니다.

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

필드 필수 여부 설명
Authorization Required 인증을 위한 서명
  • AWS Signature Version 4 사용
  • 네이버 클라우드 플랫폼에서 발급받은 Access Key와 Secret Key 사용
Host Required 리전별 엔드포인트
  • <예시> kr.ncloudstorage.com
x-amz-date Required 요청 일시
  • ISO 8601 형식(UTC 기준)
Content-Length Conditional 요청 바디 크기(Byte)
  • 객체 업로드 요청 시 필수

응답

공통 응답 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

필드 필수 여부 설명
accept-ranges - 범위 요청(Range Request) 지원 여부
  • bytes | none
    • bytes: 지원
    • none: 미지원
connection - 연결 지속 여부
  • keep-alive | close
    • keep-alive: 요청 완료 후 연결 유지
    • close: 요청 완료 후 연결 해지
Content-Length - 응답 바디 크기(Byte)
Content-Type - 요청 데이터의 형식
date - 응답 일시
  • HTTP-date 형식(GMT 기준)
etag - 객체 고유 식별자(Entity Tag)
last-modified - 마지막 수정 일시
  • HTTP-date 형식(GMT 기준)
server - 응답 반환 서버 이름
  • Ncloud Storage (유효값)
x-amz-access-point-alias - 버킷 이름 유형
  • true | false
    • true: 액세스 포인트 별칭(Alias)
    • false: 버킷 이름
x-amz-bucket-region - 버킷 리전
  • kr: 한국 리전
x-amz-checksum-type - 객체 체크섬 유형
  • COMPOSITE | FULL_OBJECT
    • COMPOSITE: 멀티파트 체크섬
    • FULL_OBJECT: 전체 객체 체크섬
x-amz-delete-marker - 객체 삭제 마커 여부
  • true | false
    • true: 삭제 마커
    • false: 일반 객체
x-amz-id-2 - 요청 아이디
  • x-amz-request-id와 함께 문제 해결 시 사용
x-amz-object-size - 객체 크기(Byte)
x-amz-request-id - 요청 아이디
  • UUID 형식
x-amz-version-id - 버전 관리 아이디
  • 버전 관리 활성화 시 표시

응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

HTTP 상태 코드 코드 설명 과금 여부
304 NotModified 리소스가 변경되지 않음 N
400 AuthorizationHeaderMalformed 유효하지 않은 인증 정보 또는 리전 정보 N
400 AuthorizationQueryParametersError 유효하지 않은 인증 쿼리 파라미터 N
400 BadDigest 요청 헤더의 Content-MD5 값 또는 체크섬 값이 서버의 계산 값과 불일치 Y
400 EntityTooLarge 업로드한 객체의 크기가 허용된 최대 크기 초과 N
400 EntityTooSmall 업로드한 객체의 크기가 허용된 최소 크기 미달 N
400 InvalidArgument 올바르지 않은 요청 파라미터 또는 헤더 N
400 InvalidBucketName 잘못된 형식의 버킷 이름 N
400 InvalidDigest 요청 헤더의 Content-MD5 또는 체크섬 값 오류 N
400 InvalidLocationConstraint 유효하지 않은 리전 제약 조건 N
400 InvalidPart 지정한 파트 중 하나 이상을 찾을 수 없음(파트 미 업로드 또는 ETag가 일치하지 않는 파트 지정) Y
400 InvalidPartNumber 올바르지 않은 파트 번호 Y
400 InvalidPartOrder 파트 목록이 파트 번호를 기준으로 오름차순 정렬되지 않음 Y
400 InvalidRequest 올바르지 않은 요청 N
400 InvalidStorageClass 유효하지 않은 스토리지 클래스 N
400 InvalidURI 파싱할 수 없는 URI N
400 KeyTooLongError 입력한 키 길이가 허용된 범위 초과 N
400 MalformedXML 입력한 XML 형식이 올바르지 않거나 게시된 스키마에 대해 검증되지 않음 N
400 MetadataTooLarge 메타데이터 헤더가 허용된 크기 초과 N
400 MissingRequestBodyError 요청 바디가 비어 있음 N
400 NotImplemented 구현되지 않은 헤더 입력 N
400 RequestHeaderSectionTooLarge 요청 헤더와 요청 쿼리 파라미터가 최대 허용 크기 초과 N
400 TooManyBuckets 허용된 버킷 수(100개) 초과 N
400 XAmzContentSHA256Mismatch x-amz-content-sha256 헤더 값이 서버의 계산 값과 불일치 N
400 InvalidEncryptionAlgorithmError 유효하지 않은 암호화 알고리즘 N
403 AccessDenied 접근 권한 없음 N
403 InvalidAccessKeyId 존재하지 않는 Access Key 아이디 N
403 InvalidObjectState 현재 객체 상태에 대해 유효하지 않은 작업 요청 Y
403 RequestTimeTooSkewed 요청 시간과 서버 시간의 차이가 너무 큼 N
403 SignatureDoesNotMatch 요청 서명 값이 서버의 계산 값과 불일치 N
404 NoSuchBucket 존재하지 않는 버킷 N
404 NoSuchKey 존재하지 않는 Key Y
404 NoSuchUpload 존재하지 않는 멀티파트 업로드(업로드 아이디 오류 또는 멀티파트 업로드 중단/완료) Y
404 NoSuchVersion 존재하지 않는 버전 아이디 Y
404 NoSuchLifecycleConfiguration 존재하지 않는 수명주기 규칙 Y
405 MethodNotAllowed 리소스에 대해 허용되지 않은 메서드 요청 N
409 BucketAlreadyExists 사용할 수 없는 버킷 이름 N
409 BucketAlreadyOwnedByYou 이미 소유 중인 버킷 생성 요청 Y
409 BucketNotEmpty 비어 있지 않은 버킷 삭제 요청 Y
409 BucketNotEmptyInUnversioned 비어 있지 않은 버킷 삭제 요청(버전 관리 비활성화 상태) N
409 RestoreAlreadyInProgress 객체 복원을 이미 진행 중 Y
411 MissingContentLength Content-Length 헤더 누락 N
412 PreconditionFailed 지정한 전제 조건 중 적어도 하나가 성립하지 않음 Y
416 InvalidPartNumber 요청한 파트 번호가 적합하지 않음 Y
416 InvalidRange 요청된 범위가 요청에 적합하지 않음 Y
429 SlowDown 너무 많은 요청률 N
500 InternalError 서버 내부 오류 N
503 ServiceUnavailable 서비스에서 요청 처리 불가 N
참고

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Ncloud API 응답 상태 코드를 참조해 주십시오.

Ncloud Storage API

Ncloud Storage 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.

Bucket

Bucket 관련 API에 대한 설명은 다음과 같습니다.

API 설명
CreateBucket Ncloud Storage 버킷 생성
GetBucketEncryption Ncloud Storage 버킷 암호화 정책 조회
GetBucketLifecycleConfiguration Ncloud Storage 버킷 수명주기 조회
GetBucketLocation Ncloud Storage 버킷 리전 정보 조회
GetBucketVersioning Ncloud Storage 버킷 버전 상태 조회
HeadBucket Ncloud Storage 버킷 메타데이터 조회
ListBuckets Ncloud Storage 버킷 목록 조회
PutBucketVersioning Ncloud Storage 버킷 버전 상태 변경
PutBuckeLifecycleConfiguration Ncloud Storage 버킷 수명주기 변경
DeleteBucket Ncloud Storage 버킷 삭제
DeleteBucketLifecycle Ncloud Storage 버킷 수명주기 삭제

Object

Object 관련 API에 대한 설명은 다음과 같습니다.

API 설명
CopyObject Ncloud Storage 버킷에 저장한 객체 복사
PutObject Ncloud Storage 버킷에 객체 저장
GetObject Ncloud Storage 버킷에 저장한 객체 다운로드 및 조회
HeadObject Ncloud Storage 버킷에 저장한 객체 메타데이터 조회
ListObjects Ncloud Storage 버킷 내 객체 목록 조회
ListObjectsV2 Ncloud Storage 버킷 내 객체 목록 조회(최신 버전)
ListObjectVersions 버전 관리가 설정된 버킷에 저장한 객체의 모든 버전 메타데이터 조회
RestoreObject Archive Class에 저장한 객체에 접근 가능하도록 객체 복원
DeleteObject Ncloud Storage 버킷에 저장한 객체 삭제
DeleteObjects Ncloud Storage 버킷에 저장한 객체 일괄 삭제

Multipart Upload

Multipart Upload 관련 API에 대한 설명은 다음과 같습니다.

API 설명
CreateMultipartUpload 멀티파트 업로드 시작 및 업로드 아이디 반환
UploadPart 멀티파트 업로드의 파트 업로드
UploadPartCopy 버킷에 이미 저장한 객체를 복사해 파트로 업로드
ListParts 멀티파트 업로드의 파트 목록 조회
ListMultipartUploads 진행 중인 멀티파트 업로드 목록 조회
CompleteMultipartUpload 업로드한 파트를 조합하여 객체 생성 및 멀티파트 업로드 완료
AbortMultipartUpload 진행 중인 멀티파트 업로드 중지

Ncloud Storage 연관 리소스

Ncloud Storage API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.