注意事项

• 通过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"
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--

请求头

此接口还需要包含Host、Date等公共请求头。更多信息，请参见公共请求头（Common Request Headers）。

请求元素

响应头

此接口还需包含公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

响应元素

示例

• 请求示例：

  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"
  200
  --9431149156168
  Content-Disposition: form-data; name="Content-Disposition"
  content_disposition
  --9431149156168
  Content-Disposition: form-data; name="x-oss-meta-uuid"
  uuid
  --9431149156168
  Content-Disposition: form-data; name="x-oss-meta-tag"
  metadata
  --9431149156168
  Content-Disposition: form-data; name="OSSAccessKeyId"
  44CF9590006BF252F707
  --9431149156168
  Content-Disposition: form-data; name="policy"
  eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
  --9431149156168
  Content-Disposition: form-data; name="Signature"
  kZoYNv66bsmc10+dcGKw5x2PRrk=
  --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  
  Server: AliyunOSS

错误码

附录：Post Policy

Post请求的Policy表单域用于验证请求的合法性。Policy为一段经过UTF-8和Base64编码的JSON文本，声明了Post请求必须满足的条件。虽然对于public-read-write的Bucket上传时，Post表单域为可选项，但强烈建议使用该域来限制Post请求。

Post Policy示例如下：

{ "expiration": "2014-12-01T12:00:00.000Z",
  "conditions": [
    {"bucket": "johnsmith" },
    ["starts-with", "$key", "user/eric/"]
  ]
}

Post Policy中必须包含Expiration和Conditions。

• Expiration

  Expiration项指定了Policy的过期时间，以ISO8601 GMT时间表示。例如2014-12-01T12:00:00.000Z指定了Post请求必须在2014年12月1日12点之前。

• Conditions
  Conditions是一个列表，可以用于指定Post请求的表单域的合法值。

  说明 表单域对应的值在检查Policy之后进行扩展，因此，Policy中设置的表单域的合法值应当对应于扩展之前的表单域的值。

  Policy中支持的Conditions项请参见下表。

  名称	描述
  content-length-range	上传Object的最小和最大允许大小。该Condition支持contion-length-range匹配方式。
  Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires	HTTP请求Header。该Condition支持精确匹配和starts-with匹配方式。 注意 建议您在Policy中增加Content-Type限制，防止通过表单上传时Content-Type被恶意修改。
  key	Object名称。该Condition支持精确匹配和starts-with匹配方式。
  success_action_redirect	上传成功后的跳转URL地址。该Condition支持精确匹配和starts-with匹配方式。
  success_action_status	未指定success_action_redirect时，上传成功后的返回状态码。该Condition支持精确匹配和starts-with匹配方式。
  x-oss-meta-*	用户指定的user meta。该Condition支持精确匹配和starts-with匹配方式。

  如果Post请求中包含额外的表单域，OSS可以将这些额外的表单域加入到Policy的Conditions中并检查合法性。

• Conditions匹配方式

  Conditions匹配方式	描述
  精确匹配	表单域的值必须精确匹配Conditions中声明的值。如指定key表单域的值必须为a：{“key”: “a”} ，则可以写为[“eq”, “$key”, “a”]
  Starts With	表单域的值必须以指定值开始。例如指定key的值必须以user/user1开始：[“starts-with”, “$key”, “user/user1”]
  指定文件大小范围	指定所允许上传的文件最大和最小范围，例如允许的文件大小为1~10字节：[“content-length-range”, 1, 10]

在Post Policy中$表示变量。如果要描述$，需要使用转义字符\$。下表描述了在Post Policy的JSON中需要进行转义的字符。

附录：Post Signature

对于验证的Post请求，HTML表单中必须包含Policy和Signature信息。Policy控制请求中哪些值是允许的。

计算Signature的具体流程如下：

1. 创建一个UTF-8编码的Policy。
2. 将Policy进行Base64编码，其值即为Policy表单域填入的值，将该值作为将要签名的字符串。
3. 使用AccessKeySecret对要签名的字符串进行签名，签名方法为Signature = base64(hmac-sha1(base64(policy), AccessKeySecret)) 。

更多参考

• Web端表单直传OSS示例：JavaScript客户端签名直传
• Java示例：表单上传
• 常见问题：调用PostObject接口的常见错误及解决方法