## **功能描述** 此接口可以将本地不超过 5GiB 的对象以HTML表单的形式上传至指定存储桶中。此接口的请求者需要对存储桶有写权限。 ## **注意事项** * 表单数据和边界的大小（不包括 `file` 内容）不能超过 20KiB。 * 表单域中没有 policy 的请求被认为是匿名的，并且只能在可公开写入的存储桶上成功。 * 构建请求时，请确保该 `file` 字段是表单中的最后一个字段（ `file` 后的字段将忽略）。 * 上传的对象的大小不能超过 5GiB。 ## **请求消息样式** ```JSON POST / HTTP/1.1 Host: buketname.tos-cn-beijing.volces.com Accept-Encoding: encoding Accept-Charset: character_set Keep-Alive: 300 Connection: keep-alive Content-Type: multipart/form-data; boundary=9431149156168 Content-Length: length --9431149156168 Content-Disposition: form-data; name="key" objectname --9431149156168 Content-Disposition: form-data; name="success_action_redirect" success_redirect --9431149156168 Content-Disposition: form-data; name="x-tos-meta-uuid" uuid --9431149156168 Content-Disposition: form-data; name="x-tos-meta-tag" metadata --9431149156168 Content-Disposition: form-data; name="Content-Disposition" attachment;filename=download.jpg --9431149156168 Content-Disposition: form-data; name="x-tos-algorithm" TOS4-HMAC-SHA256 --9431149156168 Content-Disposition: form-data; name="x-tos-date" 20220411T000000Z --9431149156168 Content-Disposition: form-data; name="x-tos-credential" ////request --9431149156168 Content-Disposition: form-data; name="policy" encoded_policy --9431149156168 Content-Disposition: form-data; name="x-tos-signature" signature --9431149156168 Content-Disposition: form-data; name="file"; filename="MyFilename.jpg" Content-Type: image/jpeg file_content --9431149156168 Content-Disposition: form-data; name="submit" Upload to TOS --9431149156168-- ``` ## **请求参数和消息头** 该操作的实现不使用请求参数。 ## **请求元素** |**名称** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---| |policy |String |是，有条件 |eyJleHBpcmF0aW9uIjoiMjAyMi0wMS0wNVQwMDowMDowM C4wMDBaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZXhhbXB sZWJ1Y2tldCJ9LFsic3RhcnRzLXdpdGgiLCIka2V5IiwiZXhhbX BsZSJdXX0= |Base64 编码的安全策略，描述请求中允许的内容。|\ | | | | |默认值：无|\ | | | | |:::warning|\ | | | | |如果存储桶不允许公开写入，则需要携带 policy，携带了 policy，必须携带签名相关表单字段。|\ | | | | ||\ | | | | |:::| |x\-tos\-algorithm |String |是，有条件 |TOS4\-HMAC\-SHA256 |该参数表明使用的签名算法。对于 TOS，该值为 `TOS4-HMAC-SHA256`。|\ | | | | |:::warning|\ | | | | |如果该请求包含了安全策略 policy 参数时，则必须提供此参数。|\ | | | | ||\ | | | | |:::| |x\-tos\-credential |String |是，有条件 |testAK/20220101/cn\-beijing/tos/request |除了您的访问密钥 ID之外，这还提供了您在计算签名密钥以进行签名计算时使用的范围信息。|\ | | | | |格式为 `///tos/request`。|\ | | | | |:::warning|\ | | | | |如果该请求包含了安全策略 policy 参数时，则必须提供此参数。|\ | | | | ||\ | | | | |:::| |x\-tos\-date |String |是，有条件 |*20220101T000000Z* |ISO8601 格式的日期值。例如，20130728T000000Z。与在创建签名密钥时使用的日期相同，也必须是 policy 中指定的 `x-tos-date` 相同的值。|\ | | | | |:::warning|\ | | | | |如果该请求包含了安全策略 policy 参数时，则必须提供此参数。|\ | | | | ||\ | | | | |:::| |x\-tos\-signature |String |是，有条件 |94d72cb3bbd094f6d8eaa0b7e56905500029813febc9fee352474f88d093c3e5 |基于安全策略 policy 和 SigningKey 计算的 HMAC\-SHA256 哈希值。|\ | | | | |:::warning|\ | | | | |如果该请求包含了安全策略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 一次只能上传一个文件。|\ | | | | |:::warning|\ | | | | ||\ | | | | |* 构建请求时，请确保该 `file` 字段是表单中的最后一个字段（file 后的字段将忽略）。|\ | | | | |* 浏览器自动根据文件类型设置 `Content-Type`（即 `file` 参数）目前处于邀测状态，如需使用，请联系客户经理。|\ | | | | ||\ | | | | |:::| |Cache\-Control |String |否 |no\-cache |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |Content\-Type |String |否 |image/jpeg |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |Content\-Disposition |String |否 |form\-data; name="key" |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |Content\-Encoding |String |否 |gzip |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |Content\-Language |String |否 |en\-US |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |Content\-MD5 |String |否 |XrY7u+Ae7tCTyyK7j1rNww== |消息体的 Base64MD5 摘要。 | |Expires |String |否 |Wed, 18 Jul 2024 18:00:00 GMT |HTTP 标准头域，详细信息，请参见 [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt?spm=a2c4g.11186623.0.0.6d016ac1feoDjC&file=rfc2616.txt)。|\ | | | | |默认值：无 | |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|\ | | | | ||\ | | | | |:::tip|\ | | | | ||\ | | | | |* 如果该域的值设置为 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`：深度冷归档存储。|\ | | | | | :::tip|\ | | | | | * 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持冷归档存储。|\ | | | | | * 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持深度冷归档存储，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。|\ | | | | ||\ | | | | | :::| |x\-tos\-meta\-\* |String |否 |x\-tos\-meta\-tag:image |您指定的 `user meta` 值。|\ | | | | |默认值：无|\ | | | | |:::tip|\ | | | | |如果请求中携带以 `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 加密方式详细说明，请参见[服务端加密概述](/docs/6349/129228)。|\ | | | | ||\ | | | | |:::tip|\ | | | | |使用 SSE\-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 [KMS 计费说明](../6476/71331)。|\ | | | | ||\ | | | | |:::| |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:::keyrings//keys/`：KMS 主密钥的 TRN，其中 `region` 为使用密钥所属 Region ID，`accountID` 为密钥所属账号的 ID，`keyring` 为密钥环别名，`key` 为主密钥别名。|\ | | | | |:::tip|\ | | | | |目前不支持默认主密钥，如果指定 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。|\ | | | | ||\ | | | | |:::tip|\ | | | | |当目标 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 过期。|\ | | | | |:::tip|\ | | | | ||\ | | | | |* 对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。|\ | | | | |* TOS 支持通过 [GetObject](/docs/6349/74856)或 [HeadObject](/docs/6349/74864) 查询对象的过期时间。|\ | | | | ||\ | | | | |:::| |x\-tos\-object\-lock\-mode |String |否 |COMPLIANCE |保留策略的模式，取值仅为 `COMPLIANCE`，表示合规模式。|\ | | | | |:::tip|\ | | | | |为对象设置保留策略时，您需要先开启保留策略功能，详细介绍，请参见[PutBucketObjectLockConfiguration](https://arcosite.bytedance.net/sites/1699502194068/654cc15af4ae8802eada576c/editor/683e9057e5ba6a053931f9e8/?docLang=zh)。|\ | | | | ||\ | | | | |:::| |x\-tos\-object\-lock\-retain\-until\-date |String |否 |2025\-01\-01T00:00:00Z |对象被锁定的截止日期，在该日期内，对象不能被删除或覆盖。遵循 ISO 8601 时间格式。|\ | | | | |:::tip|\ | | | | |`x-tos-object-lock-retain-until-date` 参数需要和 `x-tos-object-lock-mode` 参数一起使用。|\ | | | | ||\ | | | | |:::| ## **响应消息头** 该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 |**名称** |**参数类型** |**示例值** |**说明** | |---|---|---|---| |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 加密方式详细说明，请参见[服务端加密概述](/docs/6349/129228)。 | |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 标准计算得出。|\ | | | |:::tip|\ | | | |当上传对象使用服务端加密时，该值为对象明文内容的 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 值。 | ## **请求示例** ```JSON POST / HTTP/1.1 Host: examplebucket.tos-cn-beijing.volces.com Accept-Encoding: encoding Accept-Charset: character_set Keep-Alive: 300 Connection: keep-alive Content-Type: multipart/form-data; boundary=9431149156168 Content-Length: length --9431149156168 Content-Disposition: form-data; name="key" exampleobject --9431149156168 Content-Disposition: form-data; name="success_action_redirect" http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html --9431149156168 Content-Disposition: form-data; name="x-tos-meta-tag" metadata --9431149156168 Content-Disposition: form-data; name="Content-Type" image/jpg --9431149156168 Content-Disposition: form-data; name="x-tos-server-side-encryption" AES256 --9431149156168 Content-Disposition: form-data; name="x-tos-algorithm" TOS4-HMAC-SHA256 --9431149156168 Content-Disposition: form-data; name="x-tos-date" 20220101T000000Z --9431149156168 Content-Disposition: form-data; name="x-tos-credential" testAK/20220101/cn-beijing/tos/request --9431149156168 Content-Disposition: form-data; name="policy" ewogICAgICAgICJleHBpcmF0aW9uIjogIjIwMjItMDEtMDVUMDA6MDA6MDAuMDAwWiIsCiAgICAgICAgImNvbmRpdGlvbnMiOiBbCiAgICAgICAgeyJidWNrZXQiOiAiZXhhbXBsZWJ1Y2tldCJ9LAogICAgICAgIFsic3RhcnRzLXdpdGgiLCAiJGtleSIsICJleGFtcGxlIl0sIAogICAgICAgIHsiYWNsIjogInB1YmxpYy1yZWFkIn0sIAogICAgICAgIHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiAiaHR0cDovL2V4YW1wbGVidWNrZXQudG9zLWNuLWJlaWppbmcudm9sY2VzLmNvbS9zdWNjZXNzZnVsX3VwbG9hZC5odG1sIn0sCiAgICAgICAgWyJzdGFydHMtd2l0aCIsICIkQ29udGVudC1UeXBlIiwgImltYWdlLyJdLCAKICAgICAgICBbInN0YXJ0cy13aXRoIiwgIiR4LXRvcy1tZXRhLXRhZyIsICIiXSwgCiAgICAgICAgCiAgICAgICAgeyJ4LXRvcy1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9LCAKICAgICAgICB7IngtdG9zLWNyZWRlbnRpYWwiOiAidGVzdEFLLzIwMjIwMTAxL2NuLWJlaWppbmcvdG9zL3JlcXVlc3QifSwgCiAgICAgICAgeyJ4LXRvcy1hbGdvcml0aG0iOiAiVE9TNC1ITUFDLVNIQTI1NiJ9LCAKICAgICAgICB7IngtdG9zLWRhdGUiOiAiMjAyMjAxMDFUMDAwMDAwWiJ9CiAgICAgICAgXQp9 --9431149156168 Content-Disposition: form-data;f name="x-tos-signature" 94d72cb3bbd094f6d8eaa0b7e56905500029813febc9fee352474f88d093c3e5 --9431149156168 Content-Disposition: form-data; name="file"; filename="MyFile.jpg" Content-Type: image/jpeg file_content --9431149156168 Content-Disposition: form-data; name="submit" Upload to TOS --9431149156168-- ``` ## **响应示例** ```JSON HTTP/1.1 204 No Content x-tos-id-2: 367be10900210004-a444ed0 x-tos-request-id: 367be10900210004-a444ed0 Date: Fri, 1 Jul 2022 01:00:36 GMT Server: TosServer Content-Length: 0 ETag: "ab7abb0da4bca5323ab6119bb5dcd296" Location: http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html x-tos-hash-crc64ecma: 6186290338114851376 ```

对象存储