初始化分片上传

最近更新时间:2019-03-14 15:06:28

功能描述

使用 API 对大于20MB 的文件进行分片上传之前,需要先使用本 API 创建「分片上传会话」,即获取此次上传的 session。使用该接口前请确认对应上传目录已存在,如果 Bucket 中没有目录则请求不成功。

操作流程

第一步:发送「初始化分片上传」请求。
第二步:腾讯云会判断文件的上传状态,若未完成上传,会返回 -4019 错误,用户需调用查询上传分片接口查询已经上传完的分片,并进行断点续传的操作;若文件从未传输过,则返回用户上传的 session。
第三步:设置 session 和 offset 参数,构造「逐个分片上传」请求,逐片上传后续文件。
第四步:循环执行第三步直到文件的分片数据上传完成。
第五步: 调用 finish 接口结束分片上传。

请求

语法示例:

POST /files/v2/124566667/xy2/uploader1500000000  HTTP/1.1
Host: <Region>.file.myqcloud.com
Authorization: <MultiEffectSignature>
Content-Type: multipart/form-data
Content-Length: <ContentLength>

Authorization: 多次有效签名(详细请参阅 签名算法 章节)。
Content-Length: RFC 2616 中定义的 HTTP 请求内容长度(字节)。

请求参数

该请求的请求体为空。

请求体

该请求的请求体如下:

--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="op"
Content-Length: 17

upload_slice_init
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="sha"
Content-Length: 40

1
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="slice_size"
Content-Length: 7

1048576
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="filesize"
Content-Length: 5

26585
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="uploadparts"
Content-Length: 83

[{"offset":0,"datalen":26585,"datasha":"e98c925a97a8ae4ffec264ae674e28b8f975eba3"}]
--9fd48fba-1ea2-4789-8e6e-64c40c243480--

节点参数具体描述如下:

参数名称 描述 类型 必选
op 操作类型,填 “upload_slice_init” String
sha 文件的 SHA-1 校验码, 如果需要做上传校验,则带上该参数。(您需要另外计算文件的 SHA-1校验码 ) String
slice_size 分片大小,单位为 Byte,有效值:1048576 (1MB) Number
filesize 文件总大小,单位为 Byte Number
biz_attr COS 服务调用方自定义属性,可通过 查询目录属性 获取该属性值 String
uploadparts 内容为 UploadPart 结构的 JSON 数据的数组。如果指定了 sha 参数,该参数也必须携带。 UploadPart 结构: offset 为该数据块的距离文件头部的偏移量, datalen 为该数据块的长度, datasha 为上一个分片数据的中间 sha 与本分片数据结合,计算的未经过 final 的中间 sha 摘要值校验码 String

响应

响应体

该响应体返回为 application/json 数据,包含完整节点数据的内容展示如下:

{
    "code":0,
     "message":"SUCCESS",
     "request_id":"NTliNzhlOGRfMTliMjk0MGFDg0N1diY2E=",
     "data":{
     "session":"8ad1d23f1b1f3452a1bda9bfbf5f810a3dac6a73371c632e47baf12d",
     "slice_size":1048576}
 }

具体的参数描述如下:

参数名称 描述 类型
code 服务端返回码,如果没有发生任何错误取值为0;如果发生错误该参数指称具体的错误码,COS服务相关的错误码可以查看 COS 错误码 Number
message 服务端提示内容,如果发生错误该字段将详细描述发生错误的情况。 String
request_id 该请求的唯一标识 id String
data 服务端返回的应答数据,该内容代表了接口返回的具体的业务数据 Object

data 数据集参数描述:

参数名称 描述 类型
access_url 通过 CDN 访问该文件的资源链接(访问速度更快) String
resource_path 该文件在 COS 中的相对路径名,可作为其 ID 标识。 格式 '/appid/bucket/filename'。推荐业务端存储 resource_path,然后根据业务需求灵活拼接资源 url(通过 CDN 访问 COS 资源的 url 和直接访问 COS 资源的 url 不同)。 String
source_url (不通过 CDN )直接访问 COS 的资源链接 String
vid 当业务上传成功并触发了其他异步操作,该字段表示该异步操作的唯一标记。可调用其他接口来查询该异步任务的状态 String

说明:

腾讯云对象存储会默认为每个资源生成经 CDN 的访问链接 access_url,当业务端尚未开通 CDN 时,仍然可以获得该链接,但是无法访问。

实际案例

请求

POST /files/v2/124566667/xy2/uploader1500000000  HTTP/1.1
Host: gz.file.myqcloud.com
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: cos-python-sdk-v4
Authorization: irCtRo2BYVMOxzSooigDrmtJ4G9hPTEyNTE2Njg1Nzcmaz1BS0lEem9RbXNrVG9oUHVJVVJUYW5uWDBEQXNLWllIcWxDelomZT0xNTA1MjAyMTA1JnQ9MTUwNTIwMTgwNSZy8xMjUxNjY4NTc3L2lhaW55dS9zYW1wbGVfYmlnZmlsZS50eHQmYj1pYWlueXU=^M
Content-Length: 618
Content-Type:  multipart/form-data; boundary=9fd48fba-1ea2-4789-8e6e-64c40c243480

--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="op"
Content-Length: 17

upload_slice_init
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="sha"
Content-Length: 40

1
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="slice_size"
Content-Length: 7

1048576
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="filesize"
Content-Length: 5

26585
--9fd48fba-1ea2-4789-8e6e-64c40c243480
Content-Disposition: form-data; name="uploadparts"
Content-Length: 83

[{"offset":0,"datalen":26585,"datasha":"e98c925a97a8ae4ffec264ae674e28b8f975eba3"}]
--9fd48fba-1ea2-4789-8e6e-64c40c243480--

响应

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 321
Connection: keep-alive
Date: Tue, 12 Sep 2017 07:36:45 GMT
Server: tencent-cos
x-cos-request-id: NTliNzhlOGRfMTliMjk0MGFfNDg0N18xMTdiY2E=

{
"code":0,
"message":"SUCCESS",
"request_id":"NTllOWQ2YjVfYzlhMzNiMGFfMTY0OV9jMzYwZTU=",
"data":
     {
         "access_url":"http://xy2-124566667.file.myqcloud.com/uploader1500000000",
    "resource_path":"/124566667/xy2/uploader1508497108630",
    "source_url":"http://xy2-124566667.cosgz.myqcloud.com/uploader1500000000",
    "url":"http://gz.file.myqcloud.com/files/v2/124566667/xy2/uploader1500000000",
    "vid":"4396314caa204d61f5d070d45248d9981508497077"
     }
}