分片上传

分块上传（Multipart Upload）允许将一个视频分割为多个部分（块），并支持并发或顺序上传。该方式建议用于大文件上传，可以提升可靠性，并支持断点续传。

1. 概述与基本概念

要通过该方式成功上传视频，需要理解两个核心概念：块（Blocks） 和 分片（Chunks）。

• 块（Block）： 视频被划分为固定大小的块。
  • 大小限制： 块的大小必须为 4 MB 的整数倍（例如：4 MB、8 MB、12 MB）。这是关键要求，因为视频的 ETag 计算依赖此对齐规则。
  • 最后一个块： 最终的块为视频实际剩余的数据大小（不需要是 4 MB 的整数倍）。
  • 小视频： 如果整个视频小于配置的块大小，则该视频只包含一个块。
• 片（Chunk）： 在每个Block内部，数据以“片”形式依次上传。Chunk是Block中的一部分数据片段，用于数据传输。

基本流程：

1. 分割视频： 按照指定大小将整个视频划分为若干Block（Block大小需为4 MB的倍数）。
2. 切片分块： 进一步将每个Block划分为更小的"Chunk"进行传输。
3. 初始化Block（/mkblk）： 通过上传该Block的首个Chunk，在服务器端创建对应Block。
4. 上传剩余Chunk（/bput）： 上传该Block内除首块外的所有后续Chunk，直到该Block全部上传完毕。
5. 重复上述操作： 对视频中的每个Block都执行步骤3和步骤4（多个Block支持并行上传）。
6. 合并（/mkfile）： 所有Block上传后，通知服务器按照指定顺序将各Block信息合并为最终的视频。

2. 前提条件

在调用本文档中的任何接口前，您必须获取上传凭证。

1. 调用 获取上传凭证（/vod/videoManage/getUploadToken）接口。
2. 从响应中提取以下参数，以便在分片上传请求中使用：

从Token响应获取的值	对应Multipart头/参数	说明
uploadUrl	Host（基础URL）	用于发送上传请求的Domain。
uploadToken	Authorization	上传请求的验证令牌。
fileKey	Key	用于视频存储的唯一标识符/路径。

3. API参考

步骤1：创建分块并上传首个分片

该接口用于初始化一个新的数据块，并上传该数据块的首个数据分片。

接口地址：POST <uploadUrl>/mkblk/<BlockSize>/<BlockIndex>

路径参数

参数	类型	是否必填	描述
BlockSize	整型	是	数据块大小（字节）。除最后一个数据块外，必须为**4 MB (4194304)**的整数倍。最后一个数据块大小为实际剩余数据大小。
BlockIndex	整型	是	数据块的索引（从 0 开始，例如第一个数据块为 0，第二个为 1）。

请求头部

Header	Value	是否必填	描述
Authorization	字符串	是	通过获取上传令牌接口获得的uploadToken。
Content-Length	整数	是	当前上传分片的大小（以字节为单位）。
Content-Type	字符串	是	固定值：application/octet-stream。
UploadBatch	UUID	是	由客户端生成的用于标识本次视频上传会话的随机UUID字符串，此视频相关的所有请求都需使用相同的UUID。
Key	字符串	是	fileKey（或目标视频路径）。也可以在上传策略中指定。

请求体

• 二进制数据：第一块的原始二进制内容。

响应示例

{
    "ctx": "用于下一个数据块的示例上下文字符串...",
    "checksum": "checksum_string",
    "crc32": 123456789,
    "offset": 4194304
}

• ctx：下一个 bput 请求所需的上下文字符串。请务必将其保存，以备下一次分片上传使用。
• checksum：已上传分片的校验和。
• crc32：已上传分片的 CRC32 值。您可以用它来校验上传数据的完整性。
• offset：该块下一个预期的偏移量。

步骤 2：上传后续分片

使用此接口上传指定块的剩余分片。您需要重复调用该接口，直到当前块全部上传完成。

接口地址：POST <uploadUrl>/bput/<Ctx>/<NextChunkOffset>

路径参数

参数	类型	是否必填	说明
Ctx	String	是	上一个 /mkblk 或 /bput 响应返回的上下文字符串，用于将当前数据分片关联到正确的数据块。
NextChunkOffset	Integer	是	当前分片在数据块中的起始偏移量，与上一个响应返回的 offset 一致。

请求头

Header	Value	是否必填	说明
Authorization	String	是	uploadToken。
Content-Length	整数	必填	正在上传的当前分片的大小（单位：字节）。
Content-Type	字符串	必填	固定值：application/octet-stream。
UploadBatch	UUID	必填	与第1步中所用的 UUID 相同。
Key	字符串	必填	fileKey。

请求体

• 二进制数据：当前分片的原始二进制内容。

响应示例

{
    "ctx": "下一个分片的示例上下文字符串...",
    "checksum": "校验和字符串",
    "crc32": 123456789,
    "offset": 8388608
}

• ctx：后续 bput 请求所需的更新后的上下文字符串。
• checksum：已上传数据块的校验和。
• crc32：CRC32 校验值。
• offset：该数据块下一个预期的偏移量。

第三步：完成上传（生成视频文件）

在所有数据块上传成功后，调用此接口将各块合并为最终视频。

接口地址：POST <uploadUrl>/mkfile/<FileSize>

注意：您可以在URL格式后追加可选参数：<uploadUrl>/mkfile/<FileSize>/x:<UserParam>/<EncodedValue>。

路径参数

参数	类型	是否必填	描述
FileSize	整数	是	整个视频的总字节数。

请求头

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 字符串列表，按照区块索引排序。

格式：

<第0个区块的LastCtx>,<第1个区块的LastCtx>,<第2个区块的LastCtx>

响应示例

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

4. 最佳实践与注意事项

• 并发性： 您可以并行上传不同的 Block，以加快上传速度。但同一 Block 内的 Chunk 必须按顺序依次上传。
• 断点续传： 如果上传失败，无需重新开始。您可以通过对比本地进度与服务器返回的 offset，从上次成功的 Block 或 Chunk 继续上传。
• 清理机制： 服务器会定期清理未完成的 Block（大约每 30 天一次）。请确保您执行了 /mkfile 步骤，以最终完成视频上传。