初始化分片上传

最近更新时间:2020-02-13 16:47:44

我的收藏
注意
您目前查阅的是历史版本 API 文档,已不再更新和维护,我们建议您查阅新版 API 文档

功能描述

使用 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"
}
}