You need to enable JavaScript to run this app.
导航

CreateMultipartUpload

最近更新时间2024.01.15 15:20:42

首次发布时间2021.10.13 16:14:08

功能描述

该接口用于初始化一个分片上传任务。在上传分片数据之前,需要先通过此接口初始化一个分片任务的 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

指定对返回的内容进行编码的编码类型,取值说明如下:

  • url:进行 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

对象的访问权限,有效的权限设置包括:

  • private:私有的。
  • public-read:公共读。
  • public-read-write:公共读写。
  • authenticated-read:认证用户读。
  • bucket-owner-read :桶所有者读。
  • bucket-owner-full-control:桶所有者完全权限。
  • bucket-owner-entrusted:受桶策略控制,桶所有者完全权限。

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

设置目标对象的加密方式,如果未设置,默认为非加密对象,取值说明如下:

  • AES256:使用 SSE-TOS 加密方式。
  • kms: 使用 SSE-KMS 加密方式。
    关于 SSE-TOS、 SSE-KMS 加密方式详细说明,请参见服务端加密概述

说明

使用 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 加密目标对象使用的主密钥,格式如下:
trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>:KMS 主密钥的 TRN,其中 region 为使用密钥所属 Region ID,accountID 为密钥所属账号的 ID,keyring 为密钥环别名,key 为主密钥别名。

说明

目前不支持默认主密钥,如果指定 SSE-KMS 加密而没有提供该头域,服务端会返回 400 InvalidRequest 错误。

x-tos-server-side-encryption-customer-algorithm

Header

String

否,使用 SSE-C 加密时,必选。

AES256

指定 SSE-C 加密对象要使用的算法,取值说明如下:

  • AES256:使用 AES256 算法加密对象。

x-tos-server-side-encryption-customer-key

Header

String

否,使用 SSE-C 加密时,必选。

YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=

x-tos-server-side-encryption-customer-algorithm 配套使用,指定 SSE-C 加密目标对象的密钥,格式为 base64 编码的 256 bit 的加密密钥。

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

设置目的对象的存储类型。如果未设置,则目的对象的存储类型,和所在桶的默认存储类型保持一致,取值说明如下:

  • STANDARD:标准存储。
  • IA:低频访问存储。
  • INTELLIGENT_TIERING:智能分层存储。
  • ARCHIVE_FR:归档闪回存储。
  • ARCHIVE:归档存储。
  • COLD_ARCHIVE:冷归档存储。
  • DEEP_COLD_ARCHIVE:深度冷归档存储。

    说明

    深度冷归档目前处于邀测状态,如您需要使用该存储类型,请联系客户经理。

x-tos-tagging

Header

String

Key1=Value1&Key2=Value2

设置对象的标签信息, 格式为 {Key}={Value},支持同时设置多个标签,设置多个标签时使用 & 分隔。

说明

  • 对象标签的 Key 和 Value 需要先进行 URL 编码。
  • 如果某个对象未使用 = 设置 Value,则 TOS 会认为该标签的 Value 为空字符串。
  • 关于对象标签的更多限制信息,请参见对象标签

x-tos-forbid-overwrite

Header

String

false

是否允许覆盖同名 Object。 当目标 Bucket 处于已开启或已暂停的版本控制状态时,可通过在 Header 中指定 x-tos-forbid-overwrite,设置是否允许覆盖同名 Object,说明如下:

  • 不指定或者指定为 false :表示允许覆盖同名 Object。
  • 指定为 true 时:表示禁止覆盖同名 Object。

请求元素

该请求中无请求消息元素。

响应消息头

该请求返回的公共响应消息头,请参见公共参数

名称

参数类型

说明

x-tos-server-side-encryption

String

对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域,该头域表示对象的服务端加密方式,取值如下:

  • AES256:使用 SSE-TOS 加密方式。
  • kms:使用 SSE-KMS 加密方式。
    关于 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

桶名。

Key

String

对象名。

UploadId

String

返回的初始化任务 ID。

EncodingType

String

返回结果中 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"
}