Ncloud Storage 개요

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

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

참고

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

Ncloud Storage 공통 설정

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

요청

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

API URL

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

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

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

구성 요소	필수 여부	설명
`Bucket`	Optional	버킷 이름 버킷 이름 규칙 참조 버킷 이름 확인: ListBuckets 참조
`regionCode`	Required	리전 코드 `kr`: 한국 리전 (유효값)

참고

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

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

버킷 이름 규칙

버킷 이름 규칙은 다음과 같습니다. 버킷을 생성할 때와 웹 사이트 호스팅 엔드포인트에서 버킷을 판정할 때 같은 규칙을 적용합니다.

구분	규칙
길이	3~63자
사용 가능 문자	영문 소문자, 숫자, 점(`.`), 하이픈(`-`)
시작·끝 문자	영문 소문자 또는 숫자
점(`.`)으로 나눈 구간	빈 구간 불가 하이픈(`-`)으로 시작하거나 끝날 수 없음
사용 불가 형식	IP 주소 형식 <예시> `192.168.0.1`
사용 불가 접두사	`xn--`, `sthree-`, `amzn-s3-demo-`
사용 불가 접미사	`-s3alias`, `--ol-s3`, `--x-s3`, `.mrap`

참고

버킷 이름 관련하여 다음 내용을 참고해 주십시오.

버킷 이름은 전체 리전에서 고유해야 합니다.
점(.)이 포함된 이름을 사용할 수 있습니다. 단, 점이 연속되거나(a..b) 점과 하이픈이 맞닿은(a-.b, a.-b) 형태는 사용할 수 없습니다.
규칙에 맞지 않는 이름으로 CreateBucket을 요청하면 InvalidBucketName을 반환합니다.
콘솔에서 버킷을 생성할 때 적용되는 이름 규칙은 버킷 관리를 참조해 주십시오.

웹 사이트 호스팅 엔드포인트

PutBucketWebsite로 정적 웹 사이트 호스팅을 설정한 버킷은 다음 URL로도 접근할 수 있습니다.

http://{Bucket}.kr.website.ncloudstorage.com

참고

웹 사이트 호스팅 엔드포인트 관련하여 다음 내용을 참고해 주십시오.

HTTP만 지원하며, HTTPS는 지원하지 않습니다.
GET, HEAD, OPTIONS 메서드만 허용합니다. 그 외 메서드는 405 Method Not Allowed를 반환합니다.
버킷 이름은 호스트 이름({Bucket}.kr.website.ncloudstorage.com)으로만 지정합니다. 경로에 버킷 이름을 넣는 /{Bucket}/{Key} 형식은 사용할 수 없습니다.
인증 정보와 무관하게 익명(Anonymous) 요청으로 처리하므로, PutBucketPolicy로 공개한 범위만 응답합니다.
오류 응답의 바디는 XML이 아닌 HTML 형식입니다.

요청 헤더

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

필드	필수 여부	설명
`Authorization`	Required	인증을 위한 서명 AWS Signature Version 4 사용 네이버 클라우드 플랫폼에서 발급받은 Access Key와 Secret Key 사용 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
400	MalformedPolicy	정책 문서의 형식이 올바르지 않거나 유효하지 않은 값 입력	Y
400	MaxMessageLengthExceeded	요청 바디가 허용된 최대 크기 초과	Y
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
404	NoSuchBucketPolicy	존재하지 않는 버킷 정책	Y
404	NoSuchWebsiteConfiguration	존재하지 않는 정적 웹 사이트 호스팅 설정	Y
405	MethodNotAllowed	리소스에 대해 허용되지 않은 메서드 요청	N
409	BucketAlreadyExists	사용할 수 없는 버킷 이름	N
409	BucketAlreadyOwnedByYou	이미 소유 중인 버킷 생성 요청	Y
409	BucketNotEmpty	비어 있지 않은 버킷 삭제 요청	Y
409	BucketNotEmptyInUnversioned	비어 있지 않은 버킷 삭제 요청(버전 관리 비활성화 상태)	N
409	RestoreAlreadyInProgress	객체 복원을 이미 진행 중	Y
409	InvalidBucketState	현재 버킷 상태에 대해 유효하지 않은 작업 요청	Y
411	MissingContentLength	Content-Length 헤더 누락	N
412	PreconditionFailed	지정한 전제 조건 중 적어도 하나가 성립하지 않음	Y
416	InvalidPartNumber	요청한 파트 번호가 적합하지 않음	Y
416	InvalidRange	요청된 범위가 요청에 적합하지 않음	Y
429	SlowDown	너무 많은 요청률	N
500	InternalError	서버 내부 오류	N
501	NotSupported	지원하지 않는 기능 요청	N
503	ServiceUnavailable	서비스에서 요청 처리 불가	N

참고

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

Ncloud Storage API

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

Bucket

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

API	설명
CreateBucket	Ncloud Storage 버킷 생성
GetBucketCors	Ncloud Storage 버킷의 CORS(Cross-Origin Resource Sharing) 설정 조회
GetBucketEncryption	Ncloud Storage 버킷의 기본 서버측 암호화(SSE) 설정 조회
GetBucketLifecycleConfiguration	Ncloud Storage 버킷 수명주기 조회
GetBucketLocation	Ncloud Storage 버킷 리전 정보 조회
GetBucketLogging	Ncloud Storage 버킷의 서버 액세스 로깅 설정 조회
GetBucketPolicy	Ncloud Storage 버킷의 버킷 정책(Bucket Policy) 조회
GetBucketPolicyStatus	Ncloud Storage 버킷의 버킷 정책(Bucket Policy) 공개 여부 조회
GetBucketOwnershipControls	Ncloud Storage 버킷의 객체 소유권(Object Ownership) 설정 조회
GetBucketVersioning	Ncloud Storage 버킷 버전 상태 조회
GetBucketWebsite	Ncloud Storage 버킷의 정적 웹 사이트 호스팅 설정 조회
GetObjectLockConfiguration	Ncloud Storage 버킷의 Object Lock 설정 조회
GetPublicAccessBlock	Ncloud Storage 버킷의 공개 액세스 차단(Public Access Block) 설정 조회
HeadBucket	Ncloud Storage 버킷 메타데이터 조회
ListBuckets	Ncloud Storage 버킷 목록 조회
PutBucketCors	Ncloud Storage 버킷의 CORS(Cross-Origin Resource Sharing) 설정 변경
PutBucketEncryption	Ncloud Storage 버킷의 기본 서버측 암호화(SSE) 설정 변경
PutBucketLifecycleConfiguration	Ncloud Storage 버킷 수명주기 변경
PutBucketLogging	Ncloud Storage 버킷의 서버 액세스 로깅 설정 변경
PutBucketPolicy	Ncloud Storage 버킷의 버킷 정책(Bucket Policy) 변경
PutBucketOwnershipControls	Ncloud Storage 버킷의 객체 소유권(Object Ownership) 설정 변경
PutBucketVersioning	Ncloud Storage 버킷 버전 상태 변경
PutBucketWebsite	Ncloud Storage 버킷의 정적 웹 사이트 호스팅 설정 변경
PutObjectLockConfiguration	Ncloud Storage 버킷의 Object Lock 설정 변경
PutPublicAccessBlock	Ncloud Storage 버킷의 공개 액세스 차단(Public Access Block) 설정 변경
DeleteBucket	Ncloud Storage 버킷 삭제
DeleteBucketCors	Ncloud Storage 버킷의 CORS(Cross-Origin Resource Sharing) 설정 삭제
DeleteBucketEncryption	Ncloud Storage 버킷의 기본 서버측 암호화(SSE) 설정 삭제
DeleteBucketLifecycle	Ncloud Storage 버킷 수명주기 삭제
DeleteBucketOwnershipControls	Ncloud Storage 버킷의 객체 소유권(Object Ownership) 설정 삭제(지원하지 않음)
DeleteBucketPolicy	Ncloud Storage 버킷의 버킷 정책(Bucket Policy) 삭제
DeleteBucketWebsite	Ncloud Storage 버킷의 정적 웹 사이트 호스팅 설정 삭제
DeletePublicAccessBlock	Ncloud Storage 버킷의 공개 액세스 차단(Public Access Block) 설정 삭제

Object

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

API	설명
CopyObject	Ncloud Storage 버킷에 저장한 객체 복사
PutObject	Ncloud Storage 버킷에 객체 저장
GetObject	Ncloud Storage 버킷에 저장한 객체 다운로드 및 조회
GetObjectAttributes	Ncloud Storage 버킷에 저장한 객체의 속성 조회
HeadObject	Ncloud Storage 버킷에 저장한 객체 메타데이터 조회
ListObjects	Ncloud Storage 버킷 내 객체 목록 조회
ListObjectsV2	Ncloud Storage 버킷 내 객체 목록 조회(최신 버전)
ListObjectVersions	버전 관리가 설정된 버킷에 저장한 객체의 모든 버전 메타데이터 조회
GetObjectRetention	Ncloud Storage 객체에 설정된 보존(Retention) 정보 조회
PutObjectRetention	Ncloud Storage 객체에 보존(Retention) 설정
GetObjectLegalHold	Ncloud Storage 객체에 설정된 법적 보존(Legal Hold) 상태 조회
PutObjectLegalHold	Ncloud Storage 객체에 법적 보존(Legal Hold) 설정
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에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.

Ncloud Storage API 사용 방법
- Sub Account 사용 가이드: 요청 헤더에 추가할 Access Key 발급 방법
- Ncloud 공통 응답 상태 코드: Ncloud Storage 서비스에서 사용하는 네이버 클라우드 플랫폼의 공통 응답 상태 코드 정보
Ncloud Storage 서비스 사용 방법
- Ncloud Storage 사용 가이드: 네이버 클라우드 플랫폼 콘솔에서 Ncloud Storage를 사용하는 방법
- Ncloud 사용 환경 가이드: VPC, Classic 환경 및 지원 여부에 대한 가이드
- 요금 소개, 특징, 상세 기능: Ncloud Storage의 요금 체계, 특징, 상세 기능 요약
- 서비스 최신 소식: Ncloud Storage 서비스 관련 최신 소식
- 자주 하는 질문: Ncloud Storage 서비스 사용자들이 자주 하는 질문
- 고객 지원: API 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의