Multipart Upload

Multipart Upload 기능을 사용하면 하나의 비디오를 여러 부분(블록)으로 분할하여 동시에 또는 순차적으로 업로드할 수 있습니다. 이 방식은 대용량 비디오 업로드 시 높은 신뢰성과 업로드 중단 시 이어받기를 지원하므로 권장됩니다.

1. 개요 및 개념

이 방법으로 비디오를 성공적으로 업로드하려면 두 가지 핵심 개념인 블록과 청크를 이해해야 합니다.

• 블록: 비디오는 고정 크기의 블록으로 분할됩니다.
• 크기 제약: 블록 크기는 반드시 4MB의 배수여야 합니다(예: 4MB, 8MB, 12MB). 이는 비디오의 ETag 계산이 이 정렬에 의존하기 때문에 매우 중요합니다.
• 마지막 블록: 마지막 블록은 비디오의 실제 남은 크기이며, 4MB의 배수일 필요는 없습니다.
• 소형 비디오: 전체 비디오가 설정된 블록 크기보다 작으면, 비디오는 단일 블록으로 구성됩니다.
• 청크(Chunk): 각 블록 내부에서는 데이터가 순차적으로 “청크” 단위로 업로드됩니다. 청크란 전송을 위해 블록 내에서 분할된 데이터 조각을 의미합니다.

기본 작업 흐름:

1. 비디오 분할: 선택한 크기(반드시 4MB의 배수)로 전체 비디오를 블록 단위로 분할합니다.
2. 블록 슬라이싱: 각 블록을 전송을 위해 더 작은 "청크"로 분할합니다.
3. 블록 초기화(/mkblk): 서버에 해당 블록의 첫 번째 청크를 업로드하여 블록을 생성합니다.
4. 나머지 청크 업로드(/bput): 해당 블록의 모든 이후 청크를 업로드하여 블록을 완성합니다.
5. 반복: 비디오의 모든 블록에 대해 3번과 4번 단계를 반복합니다(블록 업로드는 병렬로 수행할 수 있습니다).
6. 병합(/mkfile): 모든 블록 업로드가 완료되면, 지정된 순서대로 서버에 블록 정보를 병합 요청하여 최종 비디오를 생성합니다.

2. 사전 준비 사항

이 문서에 있는 어떤 엔드포인트를 호출하기 전에도, 반드시 업로드 권한을 획득해야 합니다.

1. Get Upload Token (/vod/videoManage/getUploadToken)을 호출합니다.
2. 응답에서 다음 값을 추출하여 Multipart Upload 요청에 사용합니다.

토큰 응답 값	Multipart Header/Parameter에 매핑	설명
uploadUrl	Host (Base URL)	업로드 요청을 전송할 Domain입니다.
uploadToken	Authorization	업로드 요청에 대한 인증 토큰입니다.
fileKey	Key	비디오 저장을 위한 고유 식별자/경로입니다.

3. API Reference

Step 1: 블록 생성 및 첫 번째 청크 업로드

이 Endpoint는 새 블록을 초기화하고 해당 블록의 첫 번째 데이터 청크를 업로드합니다.

Endpoint: POST <uploadUrl>/mkblk/<BlockSize>/<BlockIndex>

경로 매개변수

매개변수	타입	필수 여부	설명
BlockSize	Integer	Yes	블록의 크기(바이트 단위)입니다. **4 MB(4194304)**의 배수여야 하며, 마지막 블록만 실제 남은 크기가 될 수 있습니다.
BlockIndex	Integer	Yes	블록의 0부터 시작하는 인덱스입니다(예: 첫 번째 블록은 0, 두 번째는 1).

요청 헤더

Header	Value	Required	Description
Authorization	String	예	업로드 토큰 요청 API로부터 획득한 uploadToken입니다.
Content-Length	Integer	예	현재 청크의 크기(바이트 단위)입니다.
Content-Type	String	예	고정 값: application/octet-stream.
UploadBatch	UUID	예	클라이언트가 생성한 임의의 UUID 문자열로, 해당 비디오 업로드 세션을 식별합니다. 이 비디오와 관련된 모든 요청에 동일한 UUID를 사용해야 합니다.
Key	String	예	fileKey(또는 업로드할 비디오 경로)입니다. 업로드 정책에서 지정할 수도 있습니다.

요청 본문

• 바이너리 데이터: 첫 번째 청크의 원시 바이너리 콘텐츠입니다.

응답 예시

{
    "ctx": "다음 청크를 위한 ExampleContextString...",
    "checksum": "checksum_string",
    "crc32": 123456789,
    "offset": 4194304
}

• ctx: 다음 bput 요청을 위해 필요한 Context 문자열입니다. 다음 청크 업로드를 위해 이 값을 반드시 저장해야 합니다.
• checksum: 업로드된 블록의 체크섬입니다.
• crc32: 업로드된 블록의 CRC32 값입니다. 이 값을 사용하여 업로드된 데이터의 무결성을 검증할 수 있습니다.
• offset: 이 블록에 대한 다음 예상 오프셋입니다.

2단계: 이후 청크 업로드

이 엔드포인트를 사용하여 특정 블록의 나머지 청크를 업로드합니다. 현재 블록이 완전히 업로드될 때까지 이 호출을 반복해야 합니다.

엔드포인트: POST <uploadUrl>/bput/<Ctx>/<NextChunkOffset>

경로 매개변수

파라미터	타입	필수	설명
Ctx	String	예	이전 /mkblk 또는 /bput 응답에서 반환된 컨텍스트 문자열입니다. 이 값은 청크를 올바른 블록과 연결합니다.
NextChunkOffset	Integer	예	현재 청크가 블록 내에서 시작되는 오프셋입니다. 이전 응답에서 반환된 offset과 일치합니다.

요청 헤더

헤더	값	필수	설명
Authorization	String	예	uploadToken입니다.
Content-Length	Integer	예	업로드 중인 현재 청크의 크기(바이트 단위).
Content-Type	String	예	고정 값: application/octet-stream.
UploadBatch	UUID	예	1단계에서 사용된 동일한 UUID.
Key	String	예	fileKey.

요청 Body

• 바이너리 데이터: 현재 청크의 원본 바이너리 콘텐츠.

응답 예시

{
    "ctx": "ExampleContextStringForNextChunk...",
    "checksum": "checksum_string",
    "crc32": 123456789,
    "offset": 8388608
}

• ctx: 다음 bput 요청에 필요한, 업데이트된 컨텍스트 문자열입니다.
• checksum: 업로드된 블록의 체크섬입니다.
• crc32: CRC32 값입니다.
• offset: 이 블록에 대해 다음에 기대되는 offset입니다.

3단계: 업로드 완료(비디오 파일 생성)

모든 블록이 성공적으로 업로드된 후, 이 엔드포인트를 호출하여 최종 비디오로 병합하십시오.

엔드포인트: POST <uploadUrl>/mkfile/<FileSize>

참고: URL 형식에 선택적 파라미터를 추가할 수 있습니다. <uploadUrl>/mkfile/<FileSize>/x:<UserParam>/<EncodedValue>.

경로 파라미터

파라미터	타입	필수	설명
FileSize	Integer	예	전체 비디오의 총 크기(바이트 단위).

요청 헤더

Header	Value	필수 여부	설명
Authorization	String	예	uploadToken입니다.
Content-Type	String	예	고정 값: text/plain;charset=UTF-8.
UploadBatch	UUID	예	이전 단계에서 사용된 동일한 UUID입니다.
Key	String	예	fileKey입니다.
MimeType	String	아니오	비디오의 사용자 지정 MIME 타입입니다.
DeleteAfterDays	Integer	아니오	비디오를 보관할 일수입니다. 0은 즉시 삭제를 의미합니다(권장하지 않음).

요청 본문

각 블록의 인덱스 순서대로, 각 블록에 대해 마지막으로 반환된 ctx 문자열을 쉼표로 구분한 목록입니다.

형식:

<LastCtxOfBlock0>,<LastCtxOfBlock1>,<LastCtxOfBlock2>

응답 예시

{
    "hash": "FqlKj-9023...",
    "key": "video/2023/example.mp4"
}

4. 모범 사례 및 참고 사항

• 동시성: 서로 다른 Block들은 병렬로 업로드하여 속도를 높일 수 있습니다. 단, 하나의 블록 내에서 Chunk들은 반드시 순차적으로 업로드해야 합니다.
• 업로드 재시도: 업로드가 실패하더라도 처음부터 다시 시작할 필요가 없습니다. 서버의 offset 응답을 참고해 로컬의 진행 상태와 비교하여 마지막으로 성공한 블록 또는 청크부터 이어서 업로드할 수 있습니다.
• 정리: 서버는 완료되지 않은 블록을 주기적으로 정리합니다(약 30일마다). 반드시 /mkfile 단계를 완료하여 영상 업로드를 마무리해 주시기 바랍니다.