PostObject_对象存储(OSS)-阿里云帮助中心

注意事项

要通过 HTML 表单上传的方式上传文件，您必须有 oss:PutObject 权限。具体操作，请参见为 RAM 用户授权自定义的权限策略。
通过 PostObject 上传的 Object 大小不能超过 5 GB。
Post 请求需要对 Bucket 拥有写权限。如果 Bucket 为 public-read-write，可以不上传签名信息，否则要求对该操作进行签名验证。
与 Put 操作不同，Post 操作使用 AccessKey Secret 对 policy 进行签名，计算出签名字符串作为 Signature 表单域的值，OSS 通过验证该值从而判断签名的合法性。
提交表单的 URL 为 Bucket 域名，不需要在 URL 中指定 Object。即请求行是 POST / HTTP/1.1 ，不能写为 POST /ObjectName HTTP/1.1 。
如果 POST 请求中包含 Header 签名信息或 URL 签名信息，OSS 不会对此类信息做检查。

版本控制

在开启了版本控制的 Bucket 中发起 PostObject 请求时，OSS 将为新添加的 Object 自动生成唯一的版本 ID，并在响应 Header 中通过 x-oss-version-id 的形式返回。

在暂停了版本控制的 Bucket 中发起 PostObject 请求时，OSS 将为新添加的 Object 自动生成一个 null 的版本 ID，并在响应 Header 中通过 x-oss-version-id 的形式返回。同一个 Object 仅允许一个 null 的版本 ID。

请求语法

POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length：ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="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 OSS
--9431149156168--

请求头

名称

类型

是否必选

描述

Content-Type

字符串

否

指定文件的类型和网页的编码，确定浏览器读取文件的形式和编码方式。

Post 操作提交表单编码必须为 multipart/form-data ，即 Header 中 Content-Type 为 multipart/form-data;boundary=xxxxxx 的形式。

boundary 为边界字符串，是由表单随机生成的一个随机值，无需指定。如果通过 SDK 拼接表单，则 SDK 也会生成一个随机值。

名称	类型	是否必选	描述
Cache-Control	字符串	否	指定该 Object 被下载时网页的缓存行为。更多信息，请参见 RFC 2616 。默认值：无
Content-Disposition	字符串	否	指定该 Object 被下载时的名称。更多信息，请参见 RFC 2616 。默认值：无
Content-Encoding	字符串	否	指定该 Object 被下载时的内容编码格式。更多信息，请参见 RFC 2616 。默认值：无
Expires	字符串	否	过期时间。更多信息，请参见 RFC 2616 。默认值：无
policy	字符串	是，有条件	policy 规定了请求表单域的合法性。不包含 policy 表单域的请求被认为是匿名请求，并只能访问 public-read-write 的 Bucket。默认值：无限制：当 Bucket 为非 public-read-write 或者提供了 OSSAccessKeyId（或 Signature）表单域时，必须提供 policy 表单域。
x-oss-server-side-data-encryption	字符串	否	仅当加密方式为 KMS 时，通过此选项将默认加密算法 AES256 修改为 SM4。取值：SM4
x-oss-server-side-encryption-key-id	字符串	否	表示 KMS 托管的用户主密钥。此选项仅当 x-oss-server-side-encryption 值为 KMS 时有效。
x-oss-content-type	字符串	否	由于浏览器会自动在文件表单域中增加 Content-Type，为了解决此问题，OSS 支持用户在 Post 请求体中增加 x-oss-content-type，该项允许用户指定 Content-Type，且拥有最高优先级。优先级顺序：x-oss-content-type > file 表单域的 Content-Type 默认值：无
x-oss-forbid-overwrite	字符串	否	指定 PostObject 操作时是否覆盖同名 Object。当目标 Bucket 处于已开启或已暂停的版本控制状态时， x-oss-forbid-overwrite 请求 Header 设置无效，即允许覆盖同名 Object。不指定 x-oss-forbid-overwrite ，或将 x-oss-forbid-overwrite 指定为 false 时，表示允许覆盖同名 Object。指定 x-oss-forbid-overwrite 为 true 时，表示禁止覆盖同名 Object；设置 x-oss-forbid-overwrite 请求 Header 会导致 QPS 处理性能下降，如果您有大量的操作需要使用 x-oss-forbid-overwrite 请求头（QPS > 1000），请联系技术支持，避免影响您的业务。
x-oss-object-acl	字符串	否	在文件表单域中指定 Object 的访问权限。此项支持在文件表单域中指定。取值： default （默认）：Object 遵循所在存储空间的访问权限。 private ：Object 是私有资源。只有 Object 的拥有者和授权用户有该 Object 的读写权限，其他用户没有权限操作该 Object。 public-read ：Object 是公共读资源。只有 Object 的拥有者和授权用户有该 Object 的读写权限，其他用户只有该 Object 的读权限。请谨慎使用该权限。 public-read-write ：Object 是公共读写资源。所有用户都有该 Object 的读写权限。请谨慎使用该权限。关于访问权限的更多信息，请参见设置 Object ACL 。
x-oss-storage-class	字符串	否	指定 Object 的存储类型。对于任意存储类型的 Bucket，如果上传 Object 时指定此参数，则此次上传的 Object 将存储为指定的类型。例如在 IA 类型的 Bucket 中上传 Object 时，如果指定 x-oss-storage-class 为 Standard，则该 Object 直接存储为 Standard。取值： Standard ：标准存储 IA ：低频访问 Archive ：归档存储 ColdArchive ：冷归档存储 DeepColdArchive ：深度冷归档存储
key	字符串	是	上传 Object 的名称，无需编码。如果名称包含路径，例如 `destfolder/example.jpg` ，则 OSS 会自动创建相应的文件夹。默认值：无
success_action_redirect	字符串	否	上传成功后客户端跳转到的 URL。如果未指定该表单域，返回结果由 success_action_status 表单域指定。如果上传失败，OSS 返回错误码，并不进行跳转。默认值：无
success_action_status	字符串	否	未指定 success_action_redirect 表单域时，该表单域指定了上传成功后返回给客户端的状态码。有效值：200、201、204（默认）。如果该域的值设置为 200 或者 204，OSS 返回一个空文档和相应的状态码。如果该域的值设置为 201，OSS 返回一个 XML 文件和 201 状态码。如果该域的值未设置或者设置为一个非法值，OSS 返回一个空文档和 204 状态码。
x-oss-meta-*	字符串	否	用户指定的 user meta 值。默认值：无如果请求中携带以 x-oss-meta-为前缀的表单域，则视为 user meta，例如 `x-oss-meta-location` 。
x-oss-security-token	字符串	否	安全令牌。仅当使用 STS 构造 URL 签名时，才需要设置此参数。您可以通过调用 STS 服务的 AssumeRole 接口获取安全令牌。默认值：无
file	字符串	是	文件或文本内容，无需编码。浏览器会自动根据文件类型来设置 Content-Type，并覆盖用户的设置。OSS 一次只能上传一个文件。默认值：无

名称	类型	示例值	描述
x-oss-server-side-encryption	字符串	KMS	如果请求 Header 中指定了 x-oss-server-side-encryption，则响应 Header 中将包含该头部，指明所使用的服务器端加密算法。
Content-MD5	字符串	1B2M2Y8AsgTpgAmY7PhC****	表示文件的 MD5 值。
x-oss-hash-crc64ecma	字符串	316181249502703****	表示文件的 CRC64 值。
x-oss-version-id	字符串	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	表示文件的版本 ID。仅当您将文件上传至已开启版本控制状态的 Bucket 时，会返回该响应头。

名称	类型	描述
PostResponse	容器	保存 Post 请求结果的容器。子节点：Bucket、ETag、Key、Location
Bucket	字符串	Bucket 名称。父节点：PostResponse
ETag	字符串	ETag (Entity Tag) 在每个 Object 生成的时候被创建。Post 请求创建的 Object，ETag 值是基于一定计算规则生成的唯一值，但不是其内容的 MD5 值。ETag 值可以用于检查该 Object 内容是否发生变化。父节点：PostResponse
Location	字符串	新创建 Object 的 URL。父节点：PostResponse

POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

错误码	HTTP 状态码	描述
FieldItemTooLong	400	表单域 key 的大小不允许超过 8 KB，表单域 value 的大小不允许超过 2 MB。
InvalidArgument	400	无论 Bucket 是否为 public-read-write，一旦上传 OSSAccessKeyId、policy、Signature 表单域中的任意一个，则另两个表单域为必选项。如果缺失，将返回此错误。
InvalidDigest	400	用户上传了 Content-MD5 请求 Header，OSS 会计算 body 的 Content-MD5 并检查一致性，如果不一致，将返回此错误。
EntityTooLarge	400	请求的 body 总长度不允许超过 5 GB。如果文件长度过大，将返回此错误。
InvalidEncryptionAlgorithmError	400	如果上传时指定了 x-oss-server-side-encryption Header 请求域，则必须设置其值为 AES256、KMS 或 SM4 。如果设置为其他值，将返回此错误。
IncorrectNumberOfFilesInPOSTRequest	400	Post 请求中文件个数无效。Post 请求中只能有一个 file 表单域。
FileAlreadyExists	409	请求的 Header 中携带 x-oss-forbid-overwrite=true 时，表示禁止覆盖同名文件。如果文件已存在，将返回此错误。
KmsServiceNotEnabled	403	将 x-oss-server-side-encryption 指定为 KMS，但没有预先购买 KMS 套件。
FileImmutable	409	Bucket 内的数据处于被保护状态时，如果您尝试删除或修改这些数据，将返回此错误码。
MethodNotAllowed	405	客户端使用的 HTTP 请求方法不被服务器支持或允许。请检查请求方法和请求头，确保请求头信息正确且服务支持所使用的请求方法；检查 URL 信息，确保 URL 的正确性，包括协议、域名、路径等部分。

PostObject

注意事项

版本控制

请求语法

请求头

表单元素

响应头

响应元素

示例

SDK

错误码

POST policy

POST signature

常见问题

报错 Your proposed upload exceeds the maximum allowed size.如何处理？

更多参考