分片上传

描述

分片上传功能支持将一个文件切割为一系列特定大小的数据片，将这些数据片分别上传到服务端，全部上传完后再在服务端将这些数据片合并成为一个资源。

注：

1. 分片上传返回数据支持 returnBody，不支持 returnUrl。
2. 分片上传请求必须指定文件的key，可在上传策略中指定，或在请求头部指定，上传策略中key优先级更高。
3. 云存储提供的上传域名为普通域名，若对上传速度较为敏感，有要求的客户建议采用网宿上传加速服务。

关键概念

分片上传引入了两个概念：块（block）和片（chunk）。一个资源由一到多个块组成,而每个块由一到多个片组成。

注：云存储服务端会以约一个月为单位周期性地清除上传后未被合并为文件的块和片。

基本流程

分片上传相关的API有：创建块(mkblk)、上传片(bput)、创建文件(mkfile)。分片上传流程如下图所示。

其中的关键点如下：

• 将待上传的文件按设定的块大小（如4M）切分为若干个块。文件最后一块以实际大小为准。如果文件小于设定的块大小，则只有一个块。
• 设定的块大小需为4M的倍数，如4M，8M，12M等。否则将影响文件的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>

头部说明

参数	必填	描述
Host	是	上传域名，可在用户管理界面获取。
Authorization	是	上传凭证。
Content-Length	是	第一片的内容长度，单位：字节(Byte)。
Content-Type	是	固定为application/octet-stream。
UploadBatch	是	分片上传任务ID标识，UUID随机串。不同的文件分片上传使用不同的ID，同一个分片上传任务请使用同一个UploadBatch。
Key	否	自定义文件名。需要做URL安全的Base64编码。

参数说明

参数	必填	描述
	是	块大小，需为4M的整数倍（如4M，8M，12M…)；最后一块为实际大小。单位字节(Byte)。
	是	块的顺序号，该序号从0开始指定。

请求内容

第一个片的二进制内容。

<firstChunkBinary>

响应说明

如果请求成功，则返回如下内容的Json串:

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

字段名	必填	描述
ctx	是	本次上传成功后的块级上传控制信息，用于后续上传片及生成文件。本字段是只能被WCS服务器解读使用的不透明字段，上传端不应修改其内容。每次返回的都只对应紧随其后的下一个上传数据片，上传非对应数据片会返回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>

头部说明

参数	必填	描述
Host	是	上传域名，可在用户管理界面获取。
Authorization	是	上传凭证。
Content-Length	是	第一片的内容长度，单位：字节(Byte)。
Content-Type	是	固定为application/octet-stream。
UploadBatch	是	分片上传任务ID标识，UUID随机串。不同的文件分片上传使用不同的ID，同一个分片上传任务请使用同一个UploadBatch。
Key	否	自定义文件名。需要做URL安全的Base64编码。

参数说明

参数	必填	描述
	是	前一次上传返回的块级上传控制信息。
	是	当前片在整个块中的起始偏移。

请求内容

当前片的二进制内容

    <ChunkBinary>

响应说明

如果请求成功，则返回如下内容的Json串:

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

字段名	必填	描述
ctx	是	本次上传成功后的块级上传控制信息，用于后续上传片及生成文件。本字段是只能被WCS服务器解读使用的不透明字段，上传端不应修改其内容。每次返回的都只对应紧随其后的下一个上传数据片，上传非对应数据片会返回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>

头部说明

参数	必填	描述
Host	是	上传域名，可在用户管理界面获取。
Authorization	是	上传凭证。
Content-Length	是	所有块的及分隔符的长度，单位：字节(Byte)。
Content-Type	是	固定为text/plain。
UploadBatch	是	分片上传任务ID标识，UUID随机串。不同的文件分片上传使用不同的ID，同一个分片上传任务请使用同一个UploadBatch。
Key	否	自定义文件名。需要做URL安全的Base64编码。
MimeType	否	自定义文件的MIME-Type。
Deadline	否	文件保存期限。超过保存天数文件自动删除,单位：天。例如：1、2、3……注：0表示尽快删除，上传文件时建议不配置为0。

参数说明

参数	必填	描述
	是	资源文件大小。
	否	自定义变量。注意要以x:开头。
	否	指定自定义变量的值。需要做URL安全的Base64编码。

请求内容

该请求的内容为每个数据块最后一个数据片上传后得到的的列表，以,分隔，按其在源文件中的位置排序。

注意：列表最后一项后面不需要添加,。

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

响应说明

如果请求成功，则返回如下内容的Json串:

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

字段名	必填	描述
hash	是	资源内容的SHA1值
key	是	实际资源名

如果请求失败，则返回如下内容的Json字符串：

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

字段名	必填	描述
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"