分片上传

分片上传功能支持将文件拆分为一系列特定大小的数据块，分别将这些数据块上传到服务器端，然后在所有数据块上传完成后，在服务器端将所有数据块合并为一个资源。

关键约束：
1. 返回值机制：分片上传仅支持returnBody返回模式，不支持returnUrl模式
2. 强制文件名：必须指定文件Key（可通过上传策略或请求头设置，上传策略优先级更高）
3. 域名类型：对象存储提供的上传域名均属普通域名

核心概念

分片上传引入两个层级结构：

1. 块(Block)：资源的组成单元
2. 片(Chunk)：块的组成单元

注意：对象存储的服务器端将定期清除未合并为文件的已上传块和块片，大约每月一次。

基本流程

与分片上传相关的API包括：创建块（mkblk）、上传块片（bput）和创建文件（mkfile）。分片上传流程如下所示：

其中，关键点如下：

• 根据设定的块大小（例如4MB）将要上传的文件拆分为多个块。实际大小用于文件的最后一个块。如果文件小于设定的块大小，则只有一个块。
• 设定的块大小必须是4MB的倍数，例如4MB、8MB和12MB。否则，会影响文件的ETag值计算。
• 根据预定义的块片大小，将每个块拆分为多个块片，通过调用mkblk在服务器端创建相应的块，通过调用bput完整地上传所有剩余的块片，最后完成整个块的上传。
• 在所有块上传完成后，通过调用mkfile按指定顺序将已上传块的信息合并为资源文件，从而完成整个资源的分片上传过程。

断点续传

可以通过利用分片上传功能来实现断点续传。

在分片上传过程中，每成功上传一个片，客户端都会接收到来自服务器端的进度信息，显示到目前为止已上传了多少片，从而知道下一个需要上传的片。虽然已成功上传的片不会永久存储在服务器端，但这些信息足以实现断点续传机制。

为了实现断点续传，客户端需在每次接收到这样的进度信息时将其持久化存储在本地。这样即使用户端程序意外崩溃或正常重启，也可以在启动时继续传输剩余的块片。借助断点续传功能，客户端可以暂停或继续某个文件的上传过程。

并发上传

在分片上传期间，同一个块内拆分的所有片只能按顺序逐一上传，所有块彼此独立。因此，可以同时传输多个块而不会互相干扰。这一特性使得可以实现并发上传。

创建块

为后续的分片上传创建一个新块，并同时上传第一块片的数据。

请求描述

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

Header 描述

参数	是否必需	描述
Host	是	上传域名，可在控制台的空间概览界面获取。
Authorization	是	上传凭证
Content-Length	是	第一个块片内容的长度，单位：字节。
Content-Type	是	固定值为application/octet-stream。
UploadBatch	是	分片上传任务ID，UUID随机字符串。不同文件的分片上传会使用不同ID。相同分片上传任务使用相同的UploadBatch。
Key	否	自定义文件名。必须是URL安全Base64编码。

参数描述

参数	是否必需	描述
<blockSize>	是	块大小，必须是4MB的倍数（如4MB, 8MB, 12MB...）；最后一个块适用实际大小。单位：字节。
<blockOrder>	是	顺序中的块编号，从0开始。

请求内容

第一个块片的二进制内容。

 <firstChunkBinary>

响应描述

• 如果请求成功，将返回包含以下内容的JSON字符串：

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

字段名称	是否必需	描述
ctx	是	上传成功后生成的块级上传控制信息，随后用于上传块片和生成文件。此字段是CDNetworks对象存储服务器可理解的不可视字段，上传端不应修改其内容。每次返回的<ctx>将始终仅对应于紧接在该块片之后上传的下一个数据块片。如果上传了非对应的数据块片，将返回401状态码。
checksum	是	上传块的校验码。
crc32	是	上传块的Crc32。可使用此字段验证上传块的完整性。
offset	是	分割块中下一个上传块片的偏移量。如果块片大小等于块大小，则该返回值将是当前块的大小。

• 如果请求失败，将返回包含以下内容的JSON字符串：

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

字段名称	是否必需	描述
code	是	HTTP请求响应代码。请参阅HTTP响应状态代码
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"

上传块片

上传指定块的一块数据。根据现场环境可调整具体数据量。相同块的所有数据块必须串行上传。

请求描述

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

Header 描述

参数	是否必需	描述
Host	是	上传域名，可通过用户管理接口获取。
Authorization	是	上传凭证
Content-Length	是	当前块片内容的长度，单位：字节。
Content-Type	是	固定值为application/octet-stream。
UploadBatch	是	分片上传任务ID，UUID随机字符串。不同文件的分片上传会使用不同ID。相同分片上传任务使用相同的UploadBatch。
Key	否	自定义文件名。必须是URL安全Base64编码。

参数描述

参数	是否必需	描述
<ctx>	是	从上一次上传返回的块级上传控制信息。
<nextChunkOffset>	是	整个块中当前块片的初始偏移量。

请求内容

当前块片的二进制内容。

<ChunkBinary>

响应描述

• 如果请求成功，将返回包含以下内容的JSON字符串：

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

字段名称	是否必需	描述
ctx	是	上传成功后生成的块级上传控制信息，随后用于上传块片和生成文件。此字段是CDNetworks对象存储服务器可理解的不可视字段，上传端不应修改其内容。每次返回的将始终仅对应于紧接在该块片之后上传的下一个数据块片。如果上传了非对应的数据块片，将返回401状态码。
checksum	是	上传块的校验码。
crc32	是	上传块的Crc32。可使用此字段验证上传块的完整性。
offset	是	分割块中下一个上传块片的偏移量。

• 如果请求失败，将返回包含以下内容的JSON字符串：

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

字段名称	是否必需	描述
code	是	HTTP请求响应代码。请参阅HTTP响应状态代码
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"

合并文件

将所有已上传的数据块按指定顺序合并为一个资源文件。

请求描述

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>

Header 描述

参数	是否必需	描述
Host	是	上传域名，可通过用户管理接口获取。
Authorization	是	上传凭证。
Content-Length	是	所有块的<ctx>和分隔符的长度，单位：字节。
Content-Type	是	固定值为text/plain。
UploadBatch	是	分片上传任务ID，UUID随机字符串。不同文件的分片上传会使用不同ID。相同分片上传任务使用相同的UploadBatch。
Key	否	自定义文件名。必须是URL安全Base64编码。
MimeType	否	自定义文件的MIME-Type。
Deadline	否	文件存储期限。超过存储天数的文件将自动删除，单位：天。例如：1, 2, 3... 注意：0表示尽快删除。不建议在文件上传时配置0

参数描述

参数	是否必需	描述
<fileSize>	是	资源文件大小。
<UserParam>	否	自定义变量。注意，它必须以x:开头。
<encodedUserVars>	否	指定自定义变量的值。必须是URL安全Base64编码。

请求内容

本次请求的内容是每个数据块的最后一个数据块片上传后的信息列表，用逗号（,）分隔，并按照其在源文件中的位置排序。注意：列表的最后一项后不需要逗号。

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

响应描述

• 如果请求成功，将返回包含以下内容的JSON字符串：

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

字段名称	是否必需	描述
code	是	HTTP请求响应代码。请参阅HTTP响应状态代码
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"