[중요] File Storage 설명서 문서 지원 종료 (Deprecated) 안내


  • 네이버 클라우드 플랫폼 서비스 정책상 장기적으로 File Storage는 서비스 및 유지보수 지원을 중지할 계획입니다.

    • 현재 이용중인 서비스에는 문제가 없도록 유지할 계획이지만, 부가 기능 및 연동 상품 이용 개선에 대해서는 제약이 있을 수 있습니다.
  • 편리한 기능 제공과, 상품간 원활한 인터페이스 및 연동을 위해서 Object Storage로 전환하는 것을 고객분들께 권고드립니다.

    • 단기적으로 Object Storage로 전환이 어려우시더라도 중장기적으로 Object Storage로의 전환에 대해 긍정적으로 검토 부탁드립니다.
    • Object Storage로 전환하실 때 필요하신 데이터 이관 등은 저희가 최대한 지원해드리도록 하겠습니다.

File Storage에서 Object Storage로의 마이그레이션에 대해서는 고객지원으로 문의하여 주시기 바랍니다.

개요

NFS(네이버 클라우드 플랫폼 File Storage) REST API는 NFS에 존재하는 컨테이너, 폴더, 파일을 외부에서 제어할 수 있게 해주는 외부 인터페이스입니다. NFS REST API를 이용해서 컨테이터 조회, 폴더 생성 및 삭제, 파일 업로드, 다운로드, 삭제, 권한 변경 및 목록 조회를 할 수 있습니다.

URI 형태

NFS의 모든 자원은 URI 형태로 표현됩니다.
자원은 컨테이너, 폴더, 파일 및 각 자원의 ACL, 메타데이터 등을 통칭합니다.
NFS REST API에서 사용하는 URI 형태는 다음과 같습니다.

  • URI는 POSIX 파일 시스템과 유사한 경로 표기법을 사용합니다. 최상위 요소는 컨테이너 이름입니다.

    /container
    /container/folder
    /container/folder/file.txt
    
  • 특정 자원의 ACL이나 메타데이터를 나타내기 위해서 URI의 query 시작 부분에 특정 파라미터를 명시합니다.

    /container?acl
    /container/folder?folder
    /container/folder?list
    /containter?meta
    
  • 명령어에 따라서는 추가적인 파라미터를 URI의 query 부분에 명시하기도 합니다. 이러한 파라미터는 key=value 형태로 표현되며, 각 파라미터는 &로 분리됩니다.

    /container/folder?list&list-size=10
    

REST API 서버 도메인 정보와 포트 정보는 아래와 같습니다.

restapi.fs.ncloud.com:80

공통 요청 헤더

다음은 HTTP 요청에 들어가는 공통 헤더에 대한 설명입니다.

헤더 이름 설명 비고
Authorization 인증을 위한 헤더(RFC2616 section 14.8 참고)
2-legged OAuth 방식 사용(RFC5849 참고)
선택 사항
anonymous 접근을 하지 않는 이상 항상 명시합니다.

나머지 헤더는 명령어별로 정의됩니다. 이 문서에서 정의하는 것 이외의 헤더들은 무시됩니다.

공통 응답 헤더

다음은 HTTP 응답에 들어가는 공통 헤더에 대한 설명입니다.

헤더 이름 설명 비고
Server 서버 이름 항상 명시
Date 서버가 응답을 보낸 시간 항상 명시

나머지 헤더는 명령어별로 정의됩니다.

확장 헤더

파일 업로드 시 메타데이터 설정 등의 NFS 고유 기능을 수행하기 위해 확장 헤더를 사용할 수 있습니다.
확장 헤더는 "x-ncloud- " 문자열로 시작합니다. 각 API의 Request Header 항목 설명을 참고합니다.

인증

NFS는 2-legged OAuth 방식을 사용합니다.
2-legged OAuth 방식은 client/server 인증을 위한 OAuth 프로토콜 사용 방식의 하나로서, resource owner와 client가 같기 때문에 client가 resource owner로부터 oauth_token을 얻기 위해 상호 연동하는 단계가 생략된 형태입니다. NFS에서 OAuth 기반의 요청을 작성할 때 사용될 프로토콜 파라미터는 다음과 같습니다.
자세한 내용은 RFC 5849 section 3.1을 참고합니다.

파라미터 비고
oauth_consumer_key 네이버 클라우드 플랫폼에서 발급받은 액세스 키
oauth_timestamp
oauth_nonce
oauth_version 1.0 고정
oauth_signature_method HMAC-SHA1 고정

OAuth 인증 파라미터는 HTTP 요청의 authorization 헤더값이나, URI query의 파라미터 형태로 전송될 수 있습니다.

에러 응답

사용자 요청에 대해 에러가 발생한 경우 응답 헤더에는 다음과 같은 정보를 보냅니다.

  • Content-Type: application/xml
  • HTTP 상태 코드(에러별로 매핑)

응답에는 에러에 대한 상세한 내용이 포함됩니다. 상세 포맷은 "XML 포맷 명세"의 "Error" 절을 참고합니다.
다음은 NFS에서 정의한 에러 코드와 간략한 설명, 해당되는 HTTP 상태 코드입니다.

에러코드 설명 HTTP 상태 코드
ENTRY_NOT_FOUND 요청된 자원이 없음 404 Not Found
ENTRY_TRANSIENT 자원에 대한 처리가 이루어지고 있는 경우 409 Conflict
ENTRY_NOT_A_FOLDER_OR_CONTAINER 폴더나 컨테이너가 아님 409 Conflict
ENTRY_NOT_A_CONTAINER 컨테이너가 아님 409 Conflict
ENTRY_NOT_A_FOLDER 폴더가 아님 409 Conflict
ENTRY_NOT_A_FILE 파일이 아님 409 Conflict
ENTRY_NOT_A_LARGE_FILE 큰 파일이 아님 409 Conflict
ENTRY_NOT_A_PART 큰 파일의 부분 파일이 아님 409 Conflict
ENTRY_FOLDER_NOT_EMPTY 폴더가 비어 있지 않음 409 Conflict
ENTRY_EXISTS 이미 존재함 409 Conflict
ENTRY_BAD_STATE 비정상 상태 409 Conflict
PERMISSION_DENIED 접근이 거부됨 403 Forbidden
FILE_TOO_BIG 파일이 너무 큼 400 Bad Request
UNSUPPORTED_COMMAND 지원하지 않는 명령어 400 Bad Request
INCOMPLETE_HEADER 잘못된 헤더 포맷 400 Bad Request
INCOMPLETE_BODY 잘못된 내용 포맷 400 Bad Request
BAD_QUERY_STRING 잘못된 쿼리 400 Bad Request
BAD_URI 잘못된 URI 400 Bad Request
BAD_ARGUMENT 잘못된 쿼리 파라미터
INTERNAL_ERROR 서버 에러 500 Internal Server Error
REQUEST_DATE_EXPIRED 요청 날짜의 헤더 시간 초과 403 Forbidden
OAUTH_SYNTAX OAuth 인증 포맷 에러 400 Bad Request
OAUTH_UNAUTHORIZED OAuth 인증 실패 401 Unauthorized

에러 응답 예제

다음은 존재하지 않는 컨테이너의 파일 또는 폴더 목록을 조회할 때 에러 응답을 보여줍니다.

  • 요청
GET /nonExistContainer/?list&list-size=100 HTTP/1.1
Date: Fri, 20 Jul 2012 08:01:25 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive
  • 응답
HTTP/1.1 404 Not Found Server: CloudFileStorage
Date: Fri, 20 Jul 2012 08:01:37 GMT
Content-Type: application/xml
Content-Length: 183

<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>ENTRY_NOT_FOUND</code>
<message>{"message":"nonExistContainer","messagePrameters":[]}</message>
<uri>/nonExistContainer/</uri>
</error>

REST API 설명

파일 업로드

Description

파일 업로드 명령을 이용해 최대 2GB 크기의 파일을 올릴 수 있습니다.
Content-Type, Content-Length와 같은 기본 헤더 이외에, "x- ncloud-meta-" 문자열로 시작하는 확장 헤더를 추가해 파일에 대한 메타데이터를 설정할 수 있습니다.
2GB 이상의 파일을 업로드하려면 큰 파일 업로드 시작 API를 사용해야 합니다.
파일 업로드 시 파일 이름에는 다음의 제약 사항이 있습니다.

  • 특수 문자 <, >, :, ", /, \, |, ?, *는 입력할 수 없습니다.
  • 최대 입력 가능한 길이는 영문 4000byte, 한글 1333자입니다.

Request

항목 내용 설명
HTTP method PUT
URI <URI>
Query argument 없음
Request header Content-Type 업로드할 파일의 속성. 텍스트 파일의 경우 text/plain입니다. 필수값입니다.
파일 속성값에 대해서는 http://www.iana.org/assignments/media-types/media-types.xhtml를 참고합니다.
Content-Length 업로드할 파일 크기(단위: byte). 필수값입니다.
x-ncloud-meta-<key> 포함할 경우 1개 이상
Request body 파일 내용
  • Request Example

다음은 hello.txt 파일을 업로드하는 요청 예입니다.

PUT /restapi/hello.txt HTTP/1.1
Date: Mon, 23 Jul 2012 02:38:30 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Content-Type: text/plain
x-ncloud-meta-chapter: 1
Content-Length: 24
Connection: Keep-Alive

Hello cloud file storage
  • Response
항목 내용 설명
Response header ETag 파일 구분값
Response body 없음
  • Response Example

다음은 파일 업로드 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Mon, 23 Jul 2012 02:38:30 GMT
ETag: 828732913345955938
Content-Length: 0

Remark

REST API를 사용할 때 파일명에 한글이 포함되어 있으면 전송 대상 URL을 인코딩해야 합니다.
예를 들어, Java API를 이용해 한글 파일을 업로드할 때, 전송 대상이 "sampleContainer/한글.txt"이면 다음과 같이 처리합니다.

  • 한글 처리 방법

update 대상 폴더명 또는 파일명에 한글이 포함되어 있으면, URL을 만들 때 아래와 같이 해당 한글 부분을 인코딩합니다.

String fileName = java.net.URLEncoder.encode("한글.txt", "UTF-8"); sampleContainer/fileName
  • 한글 + 공백 처리 방법

공백이 있는 파일명을 위와 같이 인코딩하면 공백이 자동으로 +로 변경됩니다. 다음과 같이 +를 변환합니다.

String fileName = java.net.URLEncoder.encode("한글.txt", "UTF-8").replaceAll("+", "%20");
sampleContainer/filename

Put 도중 예외 처리방법

Connection closed

파일 업로드 도중 연결된 connection이 끊어지는 경우 retry해서 재시도하는 처리를 합니다.

업로드 응답이 50X가 발생되는 경우

파일 업로드 응답코드가 50X인 경우 업로드 파일 사이즈를 확인 후 파일 사이즈가 0kbyte이면 해당 파일을 삭제 후 재 업로드를 해야 합니다.

업로드 정상여부 확인

파일 업로드 후 정상적으로 업로드가 완료되었는지 확인하는 방법은 업로드된 파일의 메타정보를 조회해서 업로드된 파일 사이즈가 현재 업로드 중인 파일과 사이즈가 동일한지 여부를 확인합니다.

복사 방식의 파일 업로드

Description

이미 컨테이너에 업로드된 파일의 전체나 일부를 복사해서 다른 위치에 붙여 넣어 새로운 파일을 생성하는 형태로 파일을 업로드합니다.
"x-ncloud-copy-meta"가 "TRUE"면 원본 파일의 메타데이터를 복제하고, "FALSE"면 요청 헤더에 지정된 메타데이터를 이용합니다.

Request

항목 내용 설명
HTTP method PUT
URI <URI>
Query argument 없음
Request header Content-Type 업로드할 파일의 속성. 텍스트 파일의 경우 text/plain입니다. 필수값입니다.
파일 속성값에 대해서는 http://www.iana.org/assignments/media-types/media-types.xhtml를 참고합니다.
Content-Length 업로드할 파일 크기(단위: byte). 필수값입니다.
x-ncloud-meta-<key> 메타데이터 설정
x-ncloud-copy-source 복사할 원본 URI
x-ncloud-copy-range 원본에서 복사할 부분.
이 헤더값은 HTTP Range Header Specification을 따른다. 단, range를 여러 개 설정(multiple range)할 수는 없습니다. 예시) bytes=10-20
x-ncloud-copy-meta 원본 메타데이터 복사 여부.
값: TRUE 또는 FALSE(기본값은 TRUE)
Request body 파일 내용
  • Request Example

다음은 복사 방식의 파일 업로드 요청 예입니다.

PUT /restapi/helloCopy.txt HTTP/1.1
Date: Mon, 23 Jul 2012 03:02:59 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
x-ncloud-copy-source: restapi/hello.txt
x-ncloud-copy-range: bytes=0-5
Content-Length: 0
Connection: Keep-Alive
  • Response
항목 내용 설명
Response header ETag 파일 구분값
Response body 없음
  • Response Example 다음은 복사 방식의 파일 업로드 응답 예입니다.
HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Mon, 23 Jul 2012 03:03:00 GMT
ETag: 828732916355919338
Last-Modified: Mon, 23 Jul 2012 03:03:00 GMT
Content-Length: 0

파일 다운로드

Description

컨테이너에 있는 파일을 다운로드합니다. 파일만 다운로드할 수 있고, 폴더 또는 컨테이너 전부를 다운로드하는 기능은 제공하지 않습니다.
다음의 메타데이터를 설정하면 파일 다운로드 시 HTTP 응답 헤더에 포함되어 전송되므로, 원본 파일이 가지고 있는 속성 정보를 원하는 형태의 메타데이터로 변경해서 받을 수 있습니다.

  • Cache-control: 캐시 제어 정보(max-age, s-maxage, public, private, no-cache, no-store, must-revalidate, proxy-revalidate)
  • Content-disposition: 파일 속성을 추가로 설명하는 내용
    • inline: 브라우저에서 보여줌.
    • attachment: 파일 다운로드 대화상자가 나타나도록 처리.
  • Content-language: 파일의 문자셋 정보(다국어의 경우 UTF-8, euc-kr)
  • Content-type: 파일 속성
  • Expires: 만기일

Request

항목 내용 설명
HTTP Method GET
URI 형태 <URI>
Query argument 없음
Request header Range 파일의 일부를 다운로드할 때 다운로드 범위를 설정하는 값
Request body 없음

Request Example

다음은 파일 전체를 다운로드할 때 요청 예입니다.

GET /restapi/hello.txt HTTP/1.1
Date: Thu, 26 Jul 2012 06:59:27 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

다음은 파일의 일부를 다운로드할 때 요청 예입니다.

GET /restapi/hello.txt HTTP/1.1
Date: Thu, 26 Jul 2012 07:12:00 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Range: bytes=0-5
Connection: Keep-Alive
  • Response
항목 내용 설명
Request header ETag 파일 구분값
Content-Length 다운로드한 파일의 크기
Content-Range 파일의 일부를 다운로드할 때 요청 range를 전달하는 값
Last-Modified 최종 변경 시간
x-ncloud-meta-<key> 포함할 경우 1개 이상
Response body 없음

Response Example

다음은 파일 전체를 다운로드할 때 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 06:59:29 GMT
ETag: 828732913345955938
Last-Modified: Mon, 23 Jul 2012 02:38:30 GMT
Content-Type: text/plain
Content-Length: 24

Hello cloud file storage

다음은 파일의 일부를 다운로드할 때 응답 예입니다.

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-5/24
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 07:12:02 GMT
ETag: 828732913345955938
Last-Modified: Mon, 23 Jul 2012 02:38:30 GMT
Content-Type: text/plain
Content-Length: 6

Hello

파일 삭제

Description

컨테이너에 있는 파일을 삭제합니다. 존재하지 않는 컨테이너나 파일은 삭제할 수 없습니다.

Request

항목 내용
HTTP Method DELETE
URI 형태 <URI>

Request Example

다음은 파일 삭제 요청 예입니다.

DELETE /restapi/largeHello.txt HTTP/1.1
Date: Fri, 27 Jul 2012 08:29:50 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 없음

Response Example

다음은 파일 삭제 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 08:29:53 GMT
Content-Length: 0

목록 조회

Description

컨테이너나 폴더에 있는 폴더와 파일 목록을 조회합니다. 목록 조회 최대 개수는 1000개로 제한됩니다.

Request

항목 내용 설명
HTTP Method GET
URI 형태 <URI>?list
Query argument list-marker=<name> 지정된 이름 이후 목록
list-size=<size> 목록 최대 개수
Request header 없음
Request body 없음

Request Example

다음은 컨테이너 목록 조회 요청 예입니다.

GET /restapi/?list&list-marker=TEST-FILE&list-size=10 HTTP/1.1
Date: Thu, 26 Jul 2012 06:40:18 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 목록 조회 결과 목록 조회 결과를 XML로 전달합니다. 자세한 내용은 "List result"를 참고합니다.

Response Example

다음은 컨테이너 목록 조회 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 06:40:20 GMT
Content-Type: application/xml
Content-Length: 1020

<?xml version="1.0" encoding="UTF-8"?>
<list-result>
<entries>
<entry><name>1</name>
<resource-type>2</resource-type>
<etag>828732946872912393</etag>
<resource-status>2</resource-status>
<last-modified>1343027651262</last-modified>
<size>0</size>
</entry>
<entry>
<name>hello.txt</name>
<resource-type>3</resource-type>
<etag>828732913345955938</etag>
<resource-status>2</resource-status>
<last-modified>1343011110428</last-modified>
<content-type>text/plain</content-type>
<size>24</size>
</entry>
</entries>
…
</list-result>

폴더 생성

Description

폴더를 생성합니다. 폴더 이름으로 입력 가능한 문자는 UTF-8을 지원합니다.
다음은 폴더 이름 입력 시 제약 사항입니다.

  • 특수 문자 <, >, :, ", /, \, |, ?, *는 입력할 수 없습니다.
  • 최대 입력 가능한 길이는 영문 4000byte, 한글 1333자까지 지원합니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?folder
Request header 없음
Request body 없음

Request Example

다음은 폴더 생성 요청 예입니다.

PUT /restapi/testfolder?folder HTTP/1.1
Date: Thu, 26 Jul 2012 07:54:41 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Content-Length: 0
Connection: Keep-Alive

Response

항목 내용 설명
Response header ETag 폴더 구분값
Response body 없음

Response Example

다음은 폴더 생성 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 07:54:44 GMT
ETag: 828733483045624007
Content-Length: 0

폴더 삭제

Description 폴더를 삭제합니다. 폴더 내부에 파일 또는 폴더가 존재하면 삭제할 수 없습니다.
내부의 파일 및 폴더를 먼저 삭제해야 해당 폴더를 삭제할 수 있습니다.

Request

항목 내용 설명
HTTP Method DELETE
URI 형태 <URI>?folder
Request header 없음
Request body 없음

Request Example

다음은 폴더 삭제 요청 예입니다.

DELETE /restapi/testfolder?folder HTTP/1.1
Date: Thu, 26 Jul 2012 07:54:41 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 없음

Response Example

다음은 폴더 삭제 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 07:54:44 GMT
Content-Length: 0

메타데이터 설정

Description

메타데이터는 파일이나 폴더, 컨테이너에 대한 추가적인 정보를 의미합니다.
메타데이터는 key-value 형태로 설정하며, 파일 또는 폴더에 추가 정보를 설정하면 다운로드 시 헤더에 해당 정보를 포함해서 전달합니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?meta
Query argument 없음
Request header x-ncloud-meta-<key> 포함할 경우 1개 이상
Request body 없음

Request Example

다음은 메타데이터 설정 요청 예입니다.

PUT /restapi/hello.txt?meta HTTP/1.1
Date: Thu, 26 Jul 2012 09:20:21 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
x-ncloud-meta-key1: value1
Content-Length: 0
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 없음

Response Example

다음은 메타데이터 설정 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 09:20:24 GMT
Content-Length: 0

메타데이터 조회

Description

파일이나 폴더에 설정한 메타데이터를 조회합니다.
메타데이터 이외에도 최근 변경 시간 등의 기타 정보를 얻을 수 있습니다.

Request

항목 내용 설명
HTTP Method GET
URI 형태 <URI>?meta
Request header 없음
Request body 없음

Request Example

다음은 메타데이터 조회 요청 예입니다.

GET /restapi/hello.txt?meta HTTP/1.1
Date: Thu, 26 Jul 2012 09:20:21 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 메타데이터 조회 결과 메타데이터 조회 결과를 XML로 전달합니다. 자세한 내용은 "Resource meta info"를 참고합니다.

Response Example

다음은 메타데이터 조회 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Thu, 26 Jul 2012 09:20:24 GMT
Content-Type: application/xml
Content-Length: 332

<?xml version="1.0" encoding="UTF-8"?>
<resource-meta-info>
<resource-type>3</resource-type>
<etag>828732913345955938</etag>
<resource-status>2</resource-status>
<last-modified>1343294424008</last-modified>
<content-type>text/plain</content-type>
<size>24</size>
<meta-data>
<item key="key1" value="value1"/>
</meta-data>
</resource-meta-info>

ACL 설정

Description

NFS는 컨테이너와 파일의 접근 권한을 관리할 수 있는 기능을 제공합니다.
추후 기능 확장을 고려해 컨테이너 및 파일에 대해 접근 제어 목록(ACL)을 설정합니다.
접근 제어는 (grantee, operation, policy) 형태로 명시됩니다.
자세한 내용은 "XML 포맷 명세"의 "ACL"을 참고합니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?acl
Query argument 없음
Request header Content-Type application/xml
Content-Length Request body의 길이
Request body 요청 결과 요청 결과를 XML로 전달합니다. 자세한 내용은 "ACL"을 참고합니다.

Request Example

다음은 파일에 대한 ACL 설정 요청 예입니다.

PUT /restapi/hello.txt?acl HTTP/1.1
Date: Fri, 27 Jul 2012 05:01:24 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Content-Length: 113
Content-Type: application/xml
Connection: Keep-Alive

<?xml version="1.0" encoding="UTF-8"?>
<acl>
<access-control grantee="*" operations="rq" policy="ALLOW"/>
</acl>

Response

항목 내용 설명
Response header 없음
Response body 없음

Response Example

다음은 파일에 대한 ACL 설정 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 05:01:27 GMT
Content-Length: 0

Remark

접근 권한 설정 시 다음 사항을 참고합니다.

  • 접근 권한의 우선 순위는 파일이 컨테이너보다는 높습니다.
  • 파일과 컨테이너 각각 권한이 부여됐을 때 파일 권한이 먼저 적용되고, 파일에 권한이 없으면 컨테이너에 설정된 권한이 적용됩니다.
  • 파일은 접근을 허용하지 않고 컨테이너는 접근을 허용하도록 설정되어 있다면, 해당 파일은 외부 권한이 없는 사용자에게 공개되지 않습니다.(권한이 있는 사용자는 조회가 가능합니다)

ACL 조회

Description

컨테이너와 파일에 설정한 접근 권한을 조회합니다.

Request

항목 내용 설명
HTTP Method GET
URI 형태 <URI>?acl
Query argument 없음
Request header 없음
Request body 없음

Request Example 다음은 파일에 대한 ACL 조회 요청 예입니다.

GET /restapi/hello.txt?acl HTTP/1.1
Date: Fri, 27 Jul 2012 05:01:24 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body ACL 조회 결과 ACL 조회 결과를 XML로 전달합니다. 자세한 내용은 "ACL"을 참고합니다.

Response Example

다음은 파일에 대한 ACL 조회 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 05:01:27 GMT
Content-Type: application/xml
Content-Length: 109

<?xml version="1.0" encoding="UTF-8"?>
<acl>
<access-control grantee="*" operations="rq" policy="ALLOW"/>
</acl>

큰 파일 업로드 시작

Description

업로드할 수 있는 파일의 최대 크기는 2GB이므로, 2GB를 넘는 파일은 업로드가 제한됩니다.
이렇게 큰 파일의 경우 파일의 일부를 추출해서 부분 파일로 업로드할 수 있도록 지원합니다.
"큰 파일 업로드 시작"은 부분 파일을 업로드하기 전에 업로드에 필요한 준비 작업을 하는 단계입니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?largefile-initiate
Query argument 없음
Request header Content-Type 업로드할 파일의 속성. 텍스트 파일의 경우 text/plain입니다. 필수값입니다.
파일 속성값에 대해서는 http://www.iana.org/assignments/media-types/media-types.xhtml를 참고합니다.
Content-Length 항상 0으로 설정.
x-ncloud-meta-<key> 포함할 경우 1개 이상
Request body 없음

Request Example

다음은 큰 파일 업로드 시작 요청 예입니다.

PUT /restapi/largeHello.txt?largefile-initiate HTTP/1.1
Date: Fri, 27 Jul 2012 07:40:23 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Content-Type: text/plain
Content-Length: 0
Connection: Keep-Alive

Response

항목 내용 설명
Response header ETag 생성된 큰 파일의 구분값
Response body 없음

Response Example

다음은 큰 파일 업로드 시작 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 07:40:25 GMT
ETag: 828733658235491044
Content-Length: 0

큰 파일 업로드 완료/취소

Description

큰 파일의 부분 파일 업로드를 완료 또는 취소합니다.

  • commit값을 완료(Y)로 호출하면 해당 파일은 업로드가 완료된 완전한 파일로 간주되어 다운로드 가능한 상태로 설정됩니다.
  • commit값을 취소(N)로 호출하면 해당 파일은 목록 조회에서 사라지고 부분 파일들은 자동으로 삭제됩니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?largefile-complete
Query argument commit=Y/N Y: 큰 파일 업로드 완료
N: 큰 파일 업로드 취소
Request header 없음
Request body 없음 "Large File Complete" 참고.

Request Example

다음은 큰 파일 업로드 완료 요청 예입니다.

PUT /restapi/largeHello.txt?largefile-complete&commit=Y HTTP/1.1
Date: Fri, 27 Jul 2012 08:29:50 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Content-Length: 163
Connection: Keep-Alive

<?xml version="1.0" encoding="UTF-8"?>
<large-file-complete>
<part-info>
<part-num>1</part-num>
<etag>828733664313431679</etag>
</part-info>
</large-file-complete>

Response

항목 내용 설명
Response header ETag 큰 파일 구분값
Response body 없음

Response Example

다음은 큰 파일 업로드 완료 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 08:29:53 GMT
ETag: 828733664313382775
Content-Length: 0

큰 파일 부분 업로드

Description

큰 파일의 일부를 추출해서 부분 파일로 업로드합니다.
부분 파일을 업로드하기 전에 "큰 파일 업로드 시작"을 실행해야 합니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?largefile-part
Query argument part-id=<id> 부분 파일의 번호. 필수값입니다.
Request header 없음
Request body 업로드할 부분 파일

Request Example

다음은 큰 파일 부분 업로드 요청 예입니다.

PUT /restapi/largeHello.txt?largefile-part&part-id=1 HTTP/1.1
Date: Fri, 27 Jul 2012 07:40:25 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 정보>
Content-Length: 19
onnection: Keep-Alive

Hello this is part

Response

항목 내용 설명
Response header ETag 부분 파일의 업로드가 완료되면 전달되는 고유의 구분값
Last-Modified 업로드 완료 시간
Response body 없음

Response Example

다음은 큰 파일 부분 업로드 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 07:40:28 GMT
ETag: 828733658239793098
Last-Modified: Fri, 27 Jul 2012 07:40:28 GMT
Content-Length: 0

복사 방식의 큰 파일 부분 업로드

Description

컨테이너에 이미 존재하는 큰 파일의 부분 파일을 복사해서 붙여 넣는 방식으로 다른 위치에 동일한 파일을 생성합니다.
생성하려고 하는 위치에 이름이 같은 파일이 있으면 파일을 생성할 수 없습니다.

Request

항목 내용 설명
HTTP Method PUT
URI 형태 <URI>?largefile-part
Query argument part-id=<id> 부분 파일의 번호. 필수값입니다.
Request header x-ncloud-copy-source 복사할 원본 파일 URI
x-ncloud-copy-range 원본 파일에서 복사할 영역에 대한 start offset, end-offset을 나타냅니다.
예시) bytes=0-100
Request body 없음

Request Example

다음은 기존 파일값을 이용한 큰 파일의 부분 업로드 요청 예입니다.

PUT /restapi/largeHello.txt?largefile-part&part-id=2 HTTP/1.1
Date: Fri, 27 Jul 2012 07:40:31 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
x-ncloud-copy-source: restapi/hello.txt Content-Length: 0
Connection: Keep-Alive

Response

항목 내용 설명
Response header ETag 구분값
Last-Modified 업로드 완료 시간
Response body 없음

Response Example

다음은 큰 파일의 부분 업로드 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 07:40:33 GMT
ETag: 828733658251535421
Last-Modified: Fri, 27 Jul 2012 07:40:33 GMT
Content-Length: 0

큰 파일 부분 삭제

Description

큰 파일 중에서 이미 업로드가 완료된 부분 파일을 삭제합니다.
큰 파일의 상태가 업로드 중이고 부분 파일은 업로드가 완료되었을 때만 삭제할 수 있습니다.

Request

항목 내용 설명
HTTP Method DELETE
URI 형태 <URI>?largefile-part
Query argument part-id=<id> 부분 파일의 번호. 필수값입니다.
Request header 없음
Request body 없음

Request Example

다음은 큰 파일의 부분 삭제 요청 예입니다.

DELETE /restapi/largeHello.txt?largefile-part&part-id=2 HTTP/1.1
Date: Fri, 27 Jul 2012 08:29:50 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 없음

Response Example

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 08:29:53 GMT
Content-Length: 0

큰 파일의 부분 파일 목록 조회

Description

큰 파일을 업로드 중인 부분 파일의 목록을 조회합니다.
큰 파일의 상태가 업로드 중일 때만 조회할 수 있습니다.

Request

항목 내용 설명
HTTP Method GET
URI 형태 <URI>?largefile-part-list
Query argument part-gt 목록 조회 기준값.
한 번에 조회할 수 있는 목록의 최대 개수가 1000개이므로, 부분 파일이 1000개가 넘는 경우 이 값을 설정합니다. 즉, 부분 파일이 1000개 이상일 때 이 값을 '1'로 설정하면 part-id가 1001 이상인 목록을 조회합니다. 선택값입니다.
part-list-size 부분 파일 조회 개수
Request header 없음
Request body 없음

Request Example

다음은 업로드되어 있는 큰 파일의 부분 파일 목록 조회 요청 예입니다.

GET /restapi/largeHello.txt?largefile-part-list&part-list-size=100&part-gt=0 HTTP/1.1
Date: Fri, 27 Jul 2012 08:29:50 GMT
Host: restapi.fs.ncloud.com
User-Agent: NCloudFileStorage Java API/0.8
Authorization: <OAuth 인증>
Connection: Keep-Alive

Response

항목 내용 설명
Response header 없음
Response body 큰 파일의 부분 파일 목록 조회 결과 큰 파일의 부분 파일 목록 조회 결과를 XML로 전달합니다. 자세한 내용은 "List part result"를 참고합니다.

Response Example

다음은 업로드되어 있는 큰 파일의 부분 파일 목록 조회 응답 예입니다.

HTTP/1.1 200 OK
Server: CloudFileStorage
Date: Fri, 27 Jul 2012 08:29:53 GMT
Content-Type: application/xml
Content-Length: 325

<?xml version="1.0" encoding="UTF-8"?>
<list-part-result>
<part>
<part-num>1</part-num>
<last-modified>1343377793731</last-modified>
<etag>828733664313431679</etag>
<size>19</size>
</part>
<part>
<part-num>2</part-num>
<last-modified>1343377793786</last-modified>
<etag>828733664313508579</etag>
<size>24</size>
</part>
</list-part-result>

XML 포맷 명세

Resource meta info

NFS REST API를 이용할 때 전달되는 XML 형식의 리소스 메타 정보에 대한 설명입니다.

Element Description Content model
resource-meta-info XML 최상위 요소 (resource-id, resource-type, resource- status, last-modified, content-type?, size, meta-data)
resource-type 자원 유형
1: 컨테이너
2: 폴더
3: 파일
4: 큰 파일
5: 큰 파일의 일부
Etag 구분값
resource-status 자원 상태
1: 생성 중
2: 일반 상태
3: 삭제 중
4: 큰 파일 업로드 완료 처리 중
last-modified 최종 수정 시간(millisecond)
content-type 파일 유형
size 파일: 파일 크기
폴더: 0
컨테이너: 컨테이너 사용량
meta-data (item*)
item Key, value attribute

Error

요청 실패 시 실패의 원인에 대한 정보입니다.

Element Description Content model
error XML 최상위 요소 (code, message, uri)
code 에러 발생 시 발생 원인
message 에러에 대한 자세한 내용
uri 에러 발생 시 호출된 파일, 폴더에 대한 전체 URI 경로

List result

파일 목록, 부분 파일 목록 등 목록을 조회하는 경우에 전달되는 XML 결과 정보입니다.

Element Description Content model
list-result XML 최상위 요소 (entries)
entries 개별 entry에 대한 상위 요소 (entry*)
entry 개별 entry 요소 정보 (name, resource-type, etag, resource- status, last-modified, content-type?, size)
name 파일이나 폴더 이름
resource-type 자원 유형
1: 컨테이너
2: 폴더
3: 파일
4: 큰 파일
5: 큰 파일의 일부
etag 구분값
resource-status 자원 상태
1: 생성 중
2: 일반 상태
3: 삭제 중
4: 큰 파일 업로드 완료 처리 중
last-modified 최종 수정 시간(millisecond)
content-type 파일 타입
size 파일: 파일 크기
폴더: 0
컨테이너: 컨테이너 사용량

List part result

부분 파일을 조회하면 전달되는 XML 결과 정보입니다.

Element Description Content model
list-part-result 큰 파일의 부분 파일의 상위 요소 (part*)
part 부분 파일의 요소 (part-num,last-modified,etag,size)
part-num 부분 파일의 순서
last-modified 최종 수정 시간을 millisecond 단위로 표시
etag Etag
size 부분 파일의 크기

Large File Complete

큰 파일 업로드 완료 시 전달되는 XML 결과 정보입니다.

Element Description Content model
large-file-complete 큰 파일 업로드 완료 시 부분 파일 상위 요소 (part-info*)
part-info 부분 파일에 대한 상위 요소 (part-num, etag)
part-num 부분 파일의 순서
etag Etag

ACL

ACL 설정 후 전달되는 XML 결과 정보입니다.

Element Description Content model
acl ACL의 XML 요소 (access-control*)
access-control 허용 대상: 현재는 임의의 대상을 의미하는 '*'만 설정할 수 있습니다.

Operations: 허용할 operation을 의미합니다. 다음에 나열된 문자를 이용해 문자열을 만든다.(예: "rq")
- r: 읽기
- w: 쓰기
- l: 리스트
- q: 메타데이터, ACL 조회
- e: 메타데이터, ACL 변경

policy: operation에 대한 ACL 허용 여부
- ALLOW: 허용
- DENY: 불허

연관 정보 바로가기

아래 가이드에서 연관 정보를 확인할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...