You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

PostObject

最近更新时间：2024.04.16 11:55:37

首次发布时间：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

是

/

文件或文本内容，无需编码。浏览器会自动根据文件类型来设置 Content-Type，并覆盖您的设置。TOS 一次只能上传一个文件。

注意

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

Cache-Control

String

否

/

HTTP 标准头域，详细信息，请参见 RFC 2616。
默认值：无

Content-Type

String

否

/

HTTP 标准头域，详细信息，请参见 RFC 2616。
默认值：无

Content-Disposition

String

否

/

HTTP 标准头域，详细信息，请参见 RFC 2616。
默认值：无

Content-Encoding

String

否

/

HTTP 标准头域，详细信息，请参见 RFC 2616。
默认值：无

Content-Language

String

否

/

HTTP 标准头域，详细信息，请参见 RFC 2616。
默认值：无

Content-MD5

String

否

XrY7u+Ae7tCTyyK7j1rNww==

消息体的 Base64MD5 摘要。

Expires

String

否

/

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：深度冷归档存储。

      说明

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

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

否

/

如果本次访问是使用 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-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 值。

x-tos-version-id

String

对象的版本号。如果不存在版本号，则该消息头不会出现在响应消息中。

x-tos-hash-crc64ecma

Integer

表示该对象的 64 位 CRC 值。该 64 位 CRC 根据 ECMA-182 标准计算得出。

说明

当上传对象使用服务端加密时，该值为对象明文内容的 CRC64 校验值。

响应元素

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

名称

参数类型

说明

Bucket

String

存储对象的存储桶的名称。

Key

String

对象名称。

Location

String

新创建对象的带域名的 URL。

ETag

String

在创建每个对象的时候生成，唯一标识一个对象的内容。

HashCrc64ecma

String

上传文件的 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