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

PostObject

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

首次发布时间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 提供单链接限速功能,在上传、下载文件等操作中进行流控控制,以保证其他应用的网络带宽。取值说明如下:

  • 取值范围:819200-838860800,单位为 bit/s。

x-tos-forbid-overwrite

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

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