You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/API 参考/对象/基础操作/PostObject
PostObject
最近更新时间：2024.11.14 16:39:31首次发布时间：2022.08.08 17:51:11
我的收藏

功能描述

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

注意事项

  • 表单数据和边界的大小（不包括 file 内容）不能超过 20KiB。
  • 表单域中没有 policy 的请求被认为是匿名的，并且只能在可公开写入的存储桶上成功。
  • 构建请求时，请确保该 file 字段是表单中的最后一个字段（ file 后的字段将忽略）。
  • 上传的对象的大小不能超过 5GiB。

请求消息样式

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"
<your-access-key-id>/<date>/<region>/<service>/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 编码的安全策略，描述请求中允许的内容。
默认值：无

注意

如果存储桶不允许公开写入，则需要携带 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 后的字段将忽略）。

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（广州）处于邀测状态，如您需要在华南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 加密方式。
  • kms: 使用 SSE-KMS 加密方式。
    关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。

说明

使用 SSE-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 KMS 计费说明。

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 时间开始计算，单位为天。
设置对象过期时间后，TOS 将于到达该过期时间后的零点开始执行删除任务，例如对象的 Last‑Modified 时间为 2024-09-26 12:00，对象的过期时间为 3 天，该对象将于 2024-09-30 00:00 过期。

说明

  • 对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。
  • TOS 支持通过 SetObjectMeta 为对象添加过期时间或修改对象的过期时间，通过 GetObject或 HeadObject 查询对象的过期时间。

响应消息头

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

名称

参数类型

示例值

说明

x-tos-server-side-encryption

String

AES256

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

  • AES256：使用 SSE-TOS 加密方式。
  • 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 值。

请求示例

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--

响应示例

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