PostObject

注意事项

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

请求元素

响应头

此接口还涉及其他公共响应头，例如Date、x-oss-request-id等。更多信息，请参见公共响应头（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"
  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

错误码

附录：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" },    
    ["content-length-range", 1, 10],
    ["eq", "$success_action_status", "201"],
    ["starts-with", "$key", "user/eric/"],
    ["in", "$content-type", ["image/jpg", "image/png"]],
    ["not-in", "$cache-control", ["no-cache"]]
  ]
}

Post Policy中必须包含Expiration和Conditions。

• Expiration

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

• Conditions

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

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

  Conditions名称	描述	Conditions匹配方式
  bucket	Bucket名称。	bucket
  content-length-range	上传Object的最小和最大允许大小，单位为字节。	content-length-range
  Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires	HTTP请求Header。 重要 建议您在Policy中增加Content-Type限制，防止通过表单上传时Content-Type被恶意修改。您可以通过以下两种方式设置Content-Type： 在Post请求体中增加x-oss-content-type，该项允许您指定Content-Type，例如Content-Type: image/jpeg。关于OSS支持设置的Content-Type类型列表，请参见如何设置Content-Type（MIME）？。 通过file表单域设置Content-Type，例如Content-Type: image/png。关于OSS支持设置的Content-Type类型列表，请参见如何设置Content-Type（MIME）？。 如果您通过以上两种方式均设置了Content-Type，Content-Type的优先级说明如下： x-oss-content-type > file表单域的Content-Type	eq、starts-with、in和not-in
  key	Object名称。	eq、starts-with、in和not-in
  success_action_redirect	上传成功后的跳转URL地址。	eq、starts-with、in和not-in
  success_action_status	未指定success_action_redirect时，上传成功后的返回状态码。	eq、starts-with、in和not-in
  x-oss-meta-*	用户指定的user meta。 说明 Policy用于限定表单域的行为。当您指定了["eq", "$x-oss-meta-biedb", "biedb-test001"]，则必须在表单域中增加key为x-oss-meta-biedb，值为biedb-test001的表单域，否则将报错Invalid according to Policy: Policy Condition failed: ["eq", "$x-oss-meta-biedb", "biedb-test001"]。	eq、starts-with、in和not-in

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

• Conditions匹配方式

  Conditions匹配方式	描述
  content-length-range	指定所允许上传的文件最大和最小范围，例如允许的文件大小为1~10字节，则可以写为["content-length-range", 1, 10]。
  eq	表单域的值必须精确匹配Conditions中声明的值。例如指定key表单域的值必须为a：{"key": "a"} ，则可以写为["eq", "$key", "a"]。
  starts-with	表单域的值必须以指定前缀开始。例如指定key的值以user/user1开始，则可以写为["starts-with", "$key", "user/user1"]。
  in	以字符串列表的形式指定需包含的检查元素。例如通过PostObject接口上传图片时，需校验上传的文件为图片类型，但允许多种格式的图片，则通过in语义指定为["in", "$content-type", ["image/jpg", "image/png"]]。
  not-in	以字符串列表的形式指定需排除的检查元素。例如通过PostObject接口上传时需要指定Object缓存行为，且不支持no-cache的形式，则通过not-in语义指定为["not-in", "$cache-control", ["no-cache"]]。

在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(AccessKeySecret,base64(policy))) 。

常见问题

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

• 问题原因：上传文件的大小超出content-length-range指定的文件大小范围。

• 解决方法：content-length-range用于指定上传文件的最小和最大允许大小，单位为字节。例如，您需要上传的文件大小为1 GB，则content-length-range可以设置为["content-length-range", 1, 1073741824]。

更多参考

• 关于Web端表单直传OSS的示例，请参见JavaScript客户端签名直传。

• 关于调用PostObject接口的常见错误及解决方法，请参见PostObject常见错误及排查。