该接口用于初始化一个分片上传任务。在上传分片数据之前,需要先通过此接口初始化一个分片任务的 UploadId,后续的上传分片、合并分片、取消分片和列举已上传分片都需要传入 UploadId参数。初始化分片上传任务不影响已存在的同名对象。
如果您配置了生命周期规则来中止不完整的分片上传,则合并必须在桶生命周期配置中指定的天数内完成。否则,不完整的分片上传将符合中止操作的条件,TOS 将中止分片上传,回收不完整的分片上传数据。
初始化的分片上传任务,在未合并和取消前,可以通过 ListMultipartUploads 接口列举出来。
如果您使用服务端加密,TOS在收到您上传的数据时,在文件级别加密这些数据,再将加密的数据持久化存储;您下载文件时,TOS自动将加密数据解密后返回给您。关于服务端加密的更多详细信息,请参见服务端加密概述。
POST /objectName?uploads HTTP/1.1 Host: bucketname.tos-cn-beijing.volces.com Date: GMT Date Authorization: authorization string
该请求使用的公共请求消息头,请参见公共参数。
名称 | 位置 | 参数类型 | 是否必选 | 示例值 | 说明 |
---|---|---|---|---|---|
uploads | Query | String | 是 | - | 代表 CreateMultipartUpload 请求的特殊标识。 |
encoding-type | Query | String | 否 | url | 指定对返回的内容进行编码的编码类型,取值说明如下:
|
Content-Type | Header | String | 否 | text/plain | 对象类型。 |
Cache-Control | Header | String | 否 | no-cache, no-store, must-revalidate | 指定该对象被下载时网页的缓存行为。 |
Expires | Header | String | 否 | Mon, 04 Jul 2022 02:57:31 GMT | RFC2616 中定义的缓存失效时间。 |
Content-Disposition | Header | String | 否 | attachment; filename=123.txt | 对象被下载时的名称。 |
Content-Encoding | Header | String | 否 | gzip | 对象被下载时的内容编码类型。 |
Content-Language | Header | String | 否 | en-US | 对象被下载时的内容语言格式。 |
x-tos-acl | Header | String | 否 | private | 对象的访问权限,有效的权限设置包括:
|
x-tos-grant-full-control | Header | String | 否 | id=账号id | 创建对象时,使用此头域授权用户具有对象的读(READ)、读(READ) ACP、写(WRITE) ACP 的权限。格式:id=账号1,id=账号2。 |
x-tos-grant-read | Header | String | 否 | id=账号id | 允许被授权者读取对象和对象元数据的权限。格式:id=账号1,id=账号2。 |
x-tos-grant-read-acp | Header | String | 否 | id=账号id | 允许被授权者读取对象 ACL。格式:id=账号1,id=账号2。 |
x-tos-grant-write-acp | Header | String | 否 | id=账号id | 允许被授权者修改对象 ACL。格式:id=账号1,id=账号2。 |
x-tos-meta-* | Header | String | 否 | x-tos-meta-key: value | 创建对象时,可以在 HTTP 请求中加入以 x-tos-meta-开头的消息头,用来加入自定义的元数据,以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时,加入的自定义元数据将会在返回消息的头中出现。 |
x-tos-server-side-encryption | Header | String | 否 | AES256 | 设置目标对象的加密方式,如果未设置,默认为非加密对象,取值说明如下:
说明 使用 SSE-KMS 进行服务端加密会产生 API 调用费用,创建 KMS 密钥会产生密钥托管费用,由 KMS 收取,更多信息,请参见 KMS 计费说明。 |
x-tos-server-side-encryption-kms-key-id | Header | String | 否,使用 SSE-KMS 加密时,必选。 | trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test | 指定 SSE-KMS 加密目标对象使用的主密钥,格式如下: 说明 目前不支持默认主密钥,如果指定 SSE-KMS 加密而没有提供该头域,服务端会返回 |
x-tos-server-side-encryption-customer-algorithm | Header | String | 否,使用 SSE-C 加密时,必选。 | AES256 | 指定 SSE-C 加密对象要使用的算法,取值说明如下:
|
x-tos-server-side-encryption-customer-key | Header | String | 否,使用 SSE-C 加密时,必选。 | YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE= | 与 |
x-tos-server-side-encryption-customer-key-MD5 | Header | String | 否,使用 SSE-C 加密时,必选。 | 0gYVWExOAz67jX5A6qY4+A== | 与 x-tos-server-side-encryption-customer-key 配套使用,该头域表示加密对象使用的密钥的MD5值。该头域由密钥的 128-bit MD5 值经过 base64-encoded 得到,该值用于消息完整性检查,确认加密密钥在传输过程中没有出错。 |
x-tos-website-redirect-location | Header | String | 否 | /anotherObjectName | 当桶设置了 Website 配置,可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的 URL,TOS 将这个值从头域中取出,保存在对象的元数据中。 |
x-tos-storage-class | Header | String | 否 | STANDARD | 设置目的对象的存储类型。如果未设置,则目的对象的存储类型,和所在桶的默认存储类型保持一致,取值说明如下:
|
x-tos-tagging | Header | String | 否 | Key1=Value1&Key2=Value2 | 设置对象的标签信息, 格式为 说明
|
x-tos-forbid-overwrite | Header | String | 否 | false | 是否允许覆盖同名 Object,取值说明如下:
注意 当目标 Bucket 处于已开启或已暂停的版本控制状态时, |
该请求中无请求消息元素。
该请求返回的公共响应消息头,请参见公共参数。
名称 | 参数类型 | 说明 |
---|---|---|
x-tos-server-side-encryption | String | 对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域,该头域表示对象的服务端加密方式,取值如下:
|
x-tos-server-side-encryption-kms-key-id | String | 对象采用 SSE-KMS 加密方式时返回该头域,该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。 |
x-tos-server-side-encryption-customer-algorithm | String | 对象是 SSE-C 加密时返回此头域,确认使用的加密算法。 |
x-tos-server-side-encryption-customer-key-MD5 | String | 对象是 SSE-C 加密时返回此头域,该头域表示加密使用的密钥的 MD5 值。 |
名称 | 参数类型 | 示例值 | 说明 |
---|---|---|---|
Bucket | String | bucketName | 桶名。 |
Key | String | objectName | 对象名。 |
UploadId | String | f93f6fc9da94371f321e1008 | 返回的初始化任务 ID。 |
EncodingType | String | url | 返回结果中 Key 的编码类型。如果请求的参数中指定了 encoding-type,那返回的结果会对 Key 进行编码。 |
POST /objectName?uploads HTTP/1.1 Host: bucketname.tos-cn-beijing.volces.com Date: Fri, 30 Jul 2021 00:07:49 GMT Authorization: authorization string
HTTP/1.1 200 OK x-tos-id-2: 4fac130c7d550034-a444ed0 x-tos-request-id: 4fac130c7d550034-a444ed0 Date: Fri, 30 Jul 2021 00:07:49 GMT server: TosServer Content-Length: 210 { "Bucket": "bucketName", "Key": "objectName", "UploadId": "f93f6fc9da94371f321e1008" }