功能描述

此接口可以将本地不超过 5GiB 的对象以HTML表单的形式上传至指定存储桶中。此接口的请求者需要对存储桶有写权限。

注意事项

表单数据和边界的大小（不包括 file 内容）不能超过 20KiB。

表单域中没有 policy 的请求被认为是匿名的，并且只能在可公开写入的存储桶上成功。

构建请求时，请确保该 file 字段是表单中的最后一个字段（ file 后的字段将忽略）。

上传的对象的大小不能超过 5GiB。

请求消息样式

请求参数和消息头

该操作的实现不使用请求参数。

请求元素

名称	参数类型	是否必选	示例值	说明
policy	String	是，有条件	eyJleHBpcmF0aW9uIjoiMjAyMi0wMS0wNVQwMDowMDowM C4wMDBaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZXhhbXB sZWJ1Y2tldCJ9LFsic3RhcnRzLXdpdGgiLCIka2V5IiwiZXhhbX BsZSJdXX0=	Base64 编码的安全策略，描述请求中允许的内容。默认值：无注意如果存储桶不允许公开写入，则需要携带 policy，携带了 policy，必须携带签名相关表单字段。
x-tos-algorithm	String	是，有条件	TOS4-HMAC-SHA256	该参数表明使用的签名算法。对于 TOS，该值为 TOS4-HMAC-SHA256。注意如果该请求包含了安全策略 policy 参数时，则必须提供此参数。
x-tos-credential	String	是，有条件	testAK/20220101/cn-beijing/tos/request	除了您的访问密钥 ID之外，这还提供了您在计算签名密钥以进行签名计算时使用的范围信息。格式为 <your-access-key-id>/<date>/<region>/tos/request。注意如果该请求包含了安全策略 policy 参数时，则必须提供此参数。
x-tos-date	String	是，有条件	20220101T000000Z	ISO8601 格式的日期值。例如，20130728T000000Z。与在创建签名密钥时使用的日期相同，也必须是 policy 中指定的 x-tos-date 相同的值。注意如果该请求包含了安全策略 policy 参数时，则必须提供此参数。
x-tos-signature	String	是，有条件	94d72cb3bbd094f6d8eaa0b7e56905500029813febc9fee352474f88d093c3e5	基于安全策略 policy 和 SigningKey 计算的 HMAC-SHA256 哈希值。注意如果该请求包含了安全策略policy参数时，则必须提供此参数。
x-tos-acl	String	否	public-read	在文件表单域中指定Object的访问权限。默认值：private 有效值：private
x-tos-tagging	String	否	{ "TagSet": { "Tags": [{ "Key": "Tag1", "Value": "Tag1" }, { "Key": "Tag2", "Value": "Tag2" }] } }	要添加到对象的指定标签集合。默认值：无
key	String	是	exampleobject	要上传对象的名称。
file	File	是	test	文件或文本内容，无需编码。浏览器会自动根据文件类型来设置 Content-Type，并覆盖您的设置。TOS 一次只能上传一个文件。注意构建请求时，请确保该 file 字段是表单中的最后一个字段（file 后的字段将忽略）。浏览器自动根据文件类型设置 Content-Type（即 file 参数）目前处于邀测状态，如需使用，请联系客户经理。
Cache-Control	String	否	no-cache	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
Content-Type	String	否	image/jpeg	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
Content-Disposition	String	否	form-data; name="key"	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
Content-Encoding	String	否	gzip	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
Content-Language	String	否	en-US	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
Content-MD5	String	否	XrY7u+Ae7tCTyyK7j1rNww==	消息体的 Base64MD5 摘要。
Expires	String	否	Wed, 18 Jul 2024 18:00:00 GMT	HTTP 标准头域，详细信息，请参见 RFC 2616。默认值：无
success_action_redirect	String	否	http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html	上传成功后客户端跳转到的 URL。如果未指定该表单域，返回结果由 success_action_status 表单域指定。如果上传失败，返回错误码，并不进行跳转。默认值：无
success_action_status	Integer	否	201	未指定 success_action_redirect 表单域时，该表单域指定了上传成功后返回给客户端的状态码。默认值：204 有效值：200、201、204 说明如果该域的值设置为 200 或者 204，TOS 返回一个空文档和相应的状态码。如果该域的值设置为 201，TOS 返回一个 JSON 内容和 201 状态码。如果该域的值未设置或者设置为一个非法值，TOS 返回一个空文档和 204 状态码。
x-tos-storage-class	String	否	STANDARD	设置对象的存储类型。如果未设置，则和桶的默认存储类型保持一致。默认值：无有效值如下： STANDARD：标准存储。 IA：低频访问存储。 INTELLIGENT_TIERING：智能分层存储。 ARCHIVE_FR：归档闪回存储。 ARCHIVE：归档存储。 COLD_ARCHIVE：冷归档存储。 DEEP_COLD_ARCHIVE：深度冷归档存储。说明当前仅华北2（北京）、华东2（上海）和华南1（广州）支持冷归档存储。当前仅华北2（北京）、华东2（上海）和华南1（广州）支持深度冷归档存储，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。
x-tos-meta-*	String	否	x-tos-meta-tag:image	您指定的 user meta 值。默认值：无说明如果请求中携带以 x-tos-meta- 为前缀的表单域，则视为 user meta，例如 x-tos-meta-location。
x-tos-security-token	String	否	STSeyJBY2NvdW50SWQiOjIxMDAwMDUyMjQsIklkZW50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MTE3MjI5NiwiQ2hhbm5lbCI6IlVzZXIiLCJBY2Nlc3NLZXlJZCI6IkFLVFBZbUkxWkdRd01EQTBOamxoTkdGa016aGpOek0wTjJRME9UU****	如果本次访问是使用 STS 临时授权方式，则需要指定该项为 SecurityToken 的值，同时 AccessKeyId 需要使用与之配对的临时 AccessKey Id。默认值：无
x-tos-website-redirect-location	String	否	/anotherPage.html	当桶设置了 Website 配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的 URL，TOS 将这个值从头域中取出，保存在对象的元数据中。默认值：无
x-tos-server-side-encryption	String	否	AES256	设置目标对象的加密方式，如果未设置，默认为非加密对象，取值说明如下： AES256：使用 SSE-TOS 加密方式，并采用 AES256 加密算法。 SM4：使用 SSE-TOS 加密方式，并采用 SM4 加密算法。 kms: 使用 SSE-KMS 加密方式。关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。说明使用 SSE-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 KMS 计费说明。
x-tos-server-side-data-encryption	String	否	AES256	使用 SSE-KMS 加密方式时的加密算法，取值说明如下： AES256： AES256 加密算法。 SM4: SM4 加密算法。默认为 AES256 算法。
x-tos-server-side-encryption-kms-key-id	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	String	否，使用 SSE-C 加密时，必选。	AES256	指定 SSE-C 加密对象要使用的算法，取值说明如下： AES256：使用 AES256 算法加密对象。
x-tos-server-side-encryption-customer-key	String	否，使用 SSE-C 加密时，必选。	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=	与 x-tos-server-side-encryption-customer-algorithm 配套使用，指定 SSE-C 加密目标对象的密钥，格式为 base64 编码的 256 bit 的加密密钥。
x-tos-server-side-encryption-customer-key-MD5	String	否，使用 SSE-C 加密时，必选。	ACdH+Fu9K3HlXdIUBu8GdA==	与 x-tos-server-side-encryption-customer-key 配套使用，该元素表示加密对象使用的密钥的MD5值。该元素由密钥的 128-bit MD5 值经过 base64-encoded 得到，该值用于消息完整性检查，确认加密密钥在传输过程中没有出错。
x-tos-traffic-limit	String	否	819200	TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：取值范围：245760-838860800，单位为 bit/s。
x-tos-forbid-overwrite	String	否	false	是否允许覆盖同名 Object，取值说明如下：不指定或者指定为 false ：表示允许覆盖同名 Object。指定为 true 时：表示禁止覆盖同名 Object。说明当目标 Bucket 处于已开启或已暂停的版本控制状态时，x-tos-forbid-overwrite 参数设置无效，即允许覆盖同名 Object。
x-tos-object-expires	String	否	3	设置对象的过期时间，过期后，TOS 将自动删除对象。单位为天，支持设置为正整数，表示对象将在指定时间过期，从对象的 Last‑Modified 时间开始计算，在到达该过期时间后的零点开始执行删除任务。例如设置 x-tos-object-expires 参数的值为 3，对象的 Last‑Modified 时间为 2024-09-26 12:00，则该对象将于 2024-09-30 00:00 过期。说明对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。 TOS 支持通过 GetObject或 HeadObject 查询对象的过期时间。
x-tos-object-lock-mode	String	否	COMPLIANCE	保留策略的模式，取值仅为 COMPLIANCE，表示合规模式。说明为对象设置保留策略时，您需要先开启保留策略功能，详细介绍，请参见PutBucketObjectLockConfiguration。
x-tos-object-lock-retain-until-date	String	否	2025-01-01T00:00:00Z	对象被锁定的截止日期，在该日期内，对象不能被删除或覆盖。遵循 ISO 8601 时间格式。说明 x-tos-object-lock-retain-until-date 参数需要和 x-tos-object-lock-mode 参数一起使用。

响应消息头

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

名称	参数类型	示例值	说明
x-tos-server-side-encryption	String	AES256	对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域，该头域表示对象的服务端加密方式，取值如下： AES256：使用 SSE-TOS 加密方式，并采用 AES256 加密算法。 SM4：使用 SSE-TOS 加密方式，并采用 SM4 加密算法。 kms: 使用 SSE-KMS 加密方式。关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	对象采用 SSE-KMS 加密方式时返回该头域，该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。
x-tos-server-side-encryption-customer-algorithm	String	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=	对象是 SSE-C 加密时返回此头域，确认使用的加密算法。
x-tos-server-side-encryption-customer-key-MD5	String	ACdH+Fu9K3HlXdIUBu8GdA==	对象是 SSE-C 加密时返回此头域，该头域表示加密使用的密钥的 MD5 值。
x-tos-version-id	String	19EA1B32CEEB56721221	对象的版本号。如果不存在版本号，则该消息头不会出现在响应消息中。
x-tos-hash-crc64ecma	Integer	6186290338114851376	表示该对象的 64 位 CRC 值。该 64 位 CRC 根据 ECMA-182 标准计算得出。说明当上传对象使用服务端加密时，该值为对象明文内容的 CRC64 校验值。
x-tos-qos-delay-time	Integer	10	该头域表示请求被流控时长，单位为ms。上传类请求会返回精确的被流控的时长；copy类请求或者下载类请求会返回根据流控程度和文件大小估算出的被流控的时长。

响应元素

当 success_action_status 的值设置为 201，TOS 会返回一个 JSON 内容。

名称	参数类型	示例值	说明
Bucket	String	examplebucket	存储对象的存储桶的名称。
Key	String	exampleobject	对象名称。
Location	String	https://buketname.tos-cn-beijing.volces.com/object	新创建对象的带域名的 URL。
ETag	String	"ab7abb0da4bca5323ab6119bb5dcd296"	在创建每个对象的时候生成，唯一标识一个对象的内容。
HashCrc64ecma	String	6186290338114851376	上传文件的 CRC64 值。

请求示例

响应示例

对象存储