Multipart Upload

멀티파트 업로드 기능은 파일을 특정 크기의 데이터 청크 시퀀스로 분할한 후, 각 청크를 서버에 개별적으로 업로드하고, 모든 청크 업로드가 완료되면 이 데이터 청크들을 서버에서 하나의 리소스로 병합할 수 있도록 지원합니다.

주요 제한사항:
1. 반환값 메커니즘: 멀티파트 업로드는 returnBody 모드만 지원하며, returnUrl 모드는 지원하지 않습니다.
2. 필수 파일 이름: 파일 key는 반드시 지정해야 하며(업로드 정책 또는 요청 헤더를 통해 설정 가능, 업로드 정책이 더 높은 우선순위를 가짐), 반드시 설정되어야 합니다.
3. 도메인 타입: 오브젝트 스토리지에서 제공하는 업로드 도메인은 일반 도메인입니다.

주요 개념

멀티파트 업로드는 2단계 구조를 도입합니다:

1. 블록(Block): 리소스를 구성하는 단위입니다.
2. 청크(Chunk): 블록을 구성하는 단위입니다.
   

참고: 오브젝트 스토리지 서버 측에서는 파일로 병합되지 않은 블록과 청크를 약 한 달에 한 번씩 주기적으로 정리(삭제)합니다.

기본 프로세스

멀티파트 업로드에 관련된 API에는 Create block(mkblk), upload chunk(bput), create file(mkfile)이 있습니다. 멀티파트 업로드 프로세스는 아래와 같습니다:

주요 포인트는 다음과 같습니다:

• 업로드할 파일을 설정된 블록 크기(예: 4MB)에 따라 여러 블록으로 분할합니다. 파일의 마지막 블록은 실제 크기를 적용합니다. 파일이 블록 크기보다 작을 경우 블록은 1개만 생성됩니다.
• 블록 크기는 반드시 4MB의 배수(4MB, 8MB, 12MB 등)여야만 하며, 그렇지 않으면 파일의 ETag 값 계산에 영향을 줄 수 있습니다.
• 각 블록을 사전에 정의된 청크 크기로 분할한 후, mkblk 호출로 서버에 해당 블록을 생성하고, bput 호출로 나머지 모든 청크를 업로드하여 블록의 업로드를 완료합니다.
• 모든 블록의 업로드가 완료되면 mkfile 호출을 통해 업로드된 블록 정보를 지정된 순서대로 하나의 리소스 파일로 병합하여 전체 리소스의 멀티파트 업로드 과정을 마칩니다.

중단 후 이어받기(Resuming Upload from Breakpoint)

멀티파트 업로드 기능을 활용하면 업로드를 중단한 이후에도 이어서 업로드를 계속할 수 있습니다.

멀티파트 업로드 과정에서 각 청크가 성공적으로 업로드될 때마다, 클라이언트는 지금까지 몇 개의 청크가 업로드되었는지 나타내는 서버의 진행 상태 정보를 받을 수 있으며, 이를 통해 다음에 업로드해야 할 청크를 알 수 있습니다. 업로드가 이미 완료된 청크는 서버에 영구적으로 저장되지 않더라도, 이 기능만으로도 이어받기(재시작) 기능을 구현할 수 있습니다.
클라이언트에서는 매번 진행 상태 정보를 받을 때마다 이를 반드시 로컬에 지속적으로 저장해야 합니다. 이를 통해 사용자의 프로그램이 예기치 않게 종료되거나 정상적으로 재시작되어도, 시작 시 남은 청크를 계속 업로드할 수 있습니다. 이 기능을 이용하면 파일 업로드 프로세스 중 특정 파일의 업로드를 일시 중지하거나 재개할 수 있습니다.

동시 업로드(Concurrent Upload)

멀티파트 업로드 시 각 블록 내부의 청크들은 반드시 순서대로 하나씩 업로드되어야 하지만, 블록 간에는 상호 독립적이기 때문에 여러 블록을 동시에 업로드하는 것이 가능합니다.
이로 인해 동시 업로드(Concurrent Upload)를 구현할 수 있습니다.

블록 생성(Create Block)

이 작업은 추후 멀티파트 업로드를 위한 새로운 블록을 생성하고, 동시에 첫 번째 청크 데이터를 업로드합니다.

요청 설명

POST /mkblk/<blockSize>/<blockOrder>
    Host: <UploadDomain>
    Authorization:<UploadToken>
    Content-Length:<firstChunkSize>
    Content-Type:application/octet-stream
    UploadBatch:<uuid>
    Key:<key>
    <firstChunkBinary>

헤더 설명

파라미터	필수여부	설명
Host	예	Upload Domain Name, 콘솔 Overview 화면에서 확인 가능
Authorization	예	Upload Credential
Content-Length	예	첫 번째 청크의 컨텐츠 길이(단위: Byte)
Content-Type	예	application/octet-stream으로 고정
UploadBatch	예	멀티파트 업로드 작업 ID(UUID, 랜덤 문자열). 파일업로드 마다 ID가 다르며, 동일한 작업에는 동일한 UploadBatch 사용
Key	아니오	Custom File Name, 반드시 URL-Safe Base64 Encoded 형식이어야 함

파라미터 설명

파라미터	필수여부	설명
<blockSize>	예	블록 크기. 반드시 4MB의 배수(4MB, 8MB, 12MB 등)여야 하며, 마지막 블록은 실제 크기 적용. 단위: Byte
<blockOrder>	예	블록의 순서 번호(0부터 시작)

요청 데이터

첫 청크의 바이너리 데이터

<firstChunkBinary>

응답 설명

• 요청이 성공하면 아래와 같은 JSON 문자열을 반환합니다:

{
    "ctx": "<Ctx string>",
    "checksum": "<Checksum string>",
    "crc32": "<Crc32 int64>",
    "offset": "<Offset int64>"
}

필드명	필수여부	설명
ctx	예	이 업로드를 통해 생성된 블록 수준 업로드 제어 정보. 향후 청크 업로드 및 파일 생성에 사용됨. CDNetworks Object Storage 서버에만 유효하며, 업로드 측에서 내용 변경 불가. 매번 반환되는 <ctx>는 바로 다음 청크 업로드에만 대응되며, 맞지 않은 청크를 업로드 시 401 코드 반환
checksum	예	업로드한 블록의 검증 코드
crc32	예	업로드한 블록의 CRC32, 업로드된 블록의 무결성 검증에 사용 가능
offset	예	분할된 블록 내 다음 업로드 청크의 오프셋. 청크 크기와 블록 크기가 동일하면 해당 반환값은 현재 블록의 크기와 같음

• 요청 실패 시 아래와 같은 JSON 문자열이 반환됩니다:

{
    "code": "<code string>",
    "message": "<message string>"
}

필드명	필수여부	설명
code	예	HTTP 요청 응답 코드, HTTP Response Status Code 참조
message	예	안내 메시지

예시

curl -v -X POST --data-binary "@/home/test/0" -H "Authorization:86622e227a50d49d858c2494a935bc2e4ac543a7:ZTIzYjFiZmFkYWRjODdiNjJlMTI4NDgyZGI1MGJmMWYzZGE2MjllNA==:eyJzY29wZSI6ImltYWdlczpzbGljZS50eHQiLCJkZWFkbGluZSI6IjE0Mzg1ODg0MDYxMDkiLCJvdmVyd3JpdGUiOjAsImZzaXplTGltaXQiOjEwNzM3NDE4MjQsImluc3RhbnQiOjB9" -H "Content-Type:application/octet-stream" -H "Content-Length:4194304" -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd"--url "http://uploadDomain/mkblk/4194304/0"

청크 업로드(Upload Chunk)

지정된 블록의 청크 중 하나를 업로드합니다. 데이터 양은 환경에 따라 조절할 수 있습니다. 동일한 블록의 모든 청크는 반드시 순서대로 업로드해야 합니다.

요청 설명

POST /bput/<ctx>/<nextChunkOffset>
   Host: <UploadDomain>
   Authorization:<UploadToken>
   Content-Length:<ChunkSize>
   Content-Type:application/octet-stream
   UploadBatch:<uuid>
   Key:<key>
   <ChunkBinary>

헤더 설명

파라미터	필수여부	설명
Host	예	Upload Domain Name
Authorization	예	Upload Credential
Content-Length	예	청크 데이터의 길이(단위: Byte)
Content-Type	예	application/octet-stream으로 고정
UploadBatch	예	멀티파트 업로드 작업 ID(UUID, 랜덤 문자열)
Key	아니오	Custom File Name, 반드시 URL-Safe Base64 Encoded 형식이어야 함

파라미터 설명

파라미터	필수여부	설명
<ctx>	예	이전 업로드에서 반환받은 블록 업로드 제어 정보
<nextChunkOffset>	예	블록 내 이번 청크의 시작 오프셋(위치)

요청 데이터

현재 청크의 바이너리 데이터

<ChunkBinary>

응답 설명

• 요청이 성공하면 아래와 같은 JSON 문자열이 반환됩니다:

{
    "ctx": "<Ctx string>",
    "checksum": "<Checksum string>",
    "crc32": "<Crc32 int64>",
    "offset": "<Offset int64>"
}

필드명	필수여부	설명
ctx	예	해당 청크 업로드 성공 후 생성된 블록 수준 업로드 제어 정보로, 이후 청크 업로드 및 파일 생성에 사용. 매번 반환되는 는 바로 다음 청크 업로드에만 적용(불일치 시 401 코드 반환)
checksum	예	업로드한 블록의 검증 코드
crc32	예	업로드 블록의 CRC32, 무결성 검증에 사용 가능
offset	예	분할된 블록 내부에서 다음에 업로드할 청크의 오프셋(위치)

• 요청 실패 시 아래와 같은 JSON 문자열이 반환됩니다:

{
    "code": "<code string>",
    "message": "<ErrMsg string>"
}

필드명	필수여부	설명
code	예	HTTP 요청 응답 코드, HTTP Response Status Code 참조
message	예	안내 메시지

예시

curl -v -X POST --data-binary "@/home/test/0" -H "Authorization:86diNjJlMTI4NDgyZGI1MGJmMWYzZGE2MjllNA==:eyJzY29wZSI6ImltYWdlczpzbGljZS50eHQiLCJkZWFkbGluZSI6IjE0Mzg1ODg0MDYxMDkiLCJvdmVyd3JpdGUiOjAsImZzaXplTGltaXQiOjEwNzM3NDE4MjQsImluc3RhbnQiOjB9" -H "Content-Type:application/octet-stream" -H "Content-Length:2097152" -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd" --url "http://uploadDomain/bput/34514eab06922ff67ac7a16cdd28e994/2097152"

파일 생성(Create file)

업로드된 모든 데이터 블록을 지정된 순서에 따라 하나의 리소스 파일로 병합합니다.

요청 설명

POST /mkfile/<fileSize>/<UserParam>/<encodUserVars>
    Host: <UploadDomain>
    Authorization:<UploadToken>
    Content-Length:<ctxListSize>
    Content-Type:text/plain;charset=UTF-8
    UploadBatch:<uuid>
    Key:<key>
    MimeType:<mimeType>
    Deadline:<Deadline>
    <ctxList>

헤더 설명

파라미터	필수여부	설명
Host	예	Upload Domain Name
Authorization	예	Upload Credential
Content-Length	예	모든 블록의 <ctx> 및 구분자의 전체 길이(단위: Byte)
Content-Type	예	text/plain으로 고정
UploadBatch	예	멀티파트 업로드 작업 ID(UUID, 랜덤 문자열)
Key	아니오	Custom File Name, URL-Safe Base64 Encoded 형식
MimeType	아니오	커스텀 파일의 MIME-Type
Deadline	아니오	파일 저장 기간(일 단위). 설정 일수를 초과한 파일은 자동 삭제됨. 예: 1, 2, 3… 참고: 0은 가능한 한 빨리 삭제됨을 의미하며, 업로드 시 0 설정은 권장하지 않음

파라미터 설명

파라미터	필수여부	설명
<fileSize>	예	리소스 파일의 전체 크기
<UserParam>	아니오	커스텀 변수, 반드시 x:로 시작해야 함
<encodedUserVars>	아니오	커스텀 변수 값, URL-Safe Base64 Encoded 형식이어야 함

요청 데이터

각 블록의 마지막 청크 업로드 시 반환된 정보(<ctx>) 리스트를 콤마(,)로 구분하여, 원본 파일 내 위치 순으로 나열(마지막 항목 뒤에는 콤마 불필요)

<lastCtxOfBlock1>,<lastCtxOfBlock2>,<lastCtxOfBlock3>,...,<lastCtxOfBlockN>

응답 설명

• 요청이 성공하면 아래와 같은 JSON 문자열이 반환됩니다:

{
    "hash":"<ContentHash>",
    "key":"<Key>"
}

필드명	필수여부	설명
code	예	HTTP 요청 응답 코드, HTTP Response Status Code 참조
message	예	안내 메시지

예시

curl -v -X POST -H 'Authorization:df115a7a498e873b74c2eab217e406a192f0ed14:NzJhMzRhODhhZTA5YjNmNjhkNWJlODY0MDI1NzQ0Nzc1OGExODkwNw==:eyJzY29wZSI6Indoai1zdHlsZS10ZXN0OmZlbnAt5L2g5aW9IUAjJiolZWUubXA0IiwiZGVhZGxpbmUiOiIyNDM4MDc4NjQ3ODMwIiwib3ZlcndyaXRlIjoxLCJmc2l6ZUxpbWl0IjoxMDczNzQxODI0LCJjYWxsYmFja1VybCI6Imh0dHA6Ly9kZW1vLmNvbTo4MS9jYWxsYmFja1VybCIsImNhbGxiYWNrQm9keSI6ImJ1Y2tldD0kKGJ1Y2tldCkma2V5PSQoa2V5KSZmbmFtZT0kKGZuYW1lKSZmc2l6ZT0kKGZzaXplKSZpcD0kKGlwKSZtaW1lVHlwZT0kKG1pbWVUeXBlKSZ1cmw9JCh1cmwpJmNvc3RUaW1lPSQoY29zdFRpbWUpJnVzZXJuYW1lPXdoaiZhZ2U9MTEmcG9zaXRpb249JCh4OnBvc2l0aW9uKSZtZXNzYWdlPSQoeDptZXNzYWdlKSIsImluc3RhbnQiOjB9' -H 'Content-Type:text/plain;charset=UTF-8' -H 'Content-Length:65' -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd" --url 'http://uploadDomain/mkfile/6339685/x:position/bG9jYWw=/x:message/dXBsb2Fk' -d "c636ec95ef7a8889dec882ef7eb9306e,d7243df51cb880e11c107088ce942f9c"

---