对象存储 OSS：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）。

表单元素

以下表格列举了POST V1和V4签名共有的表单元素。关于POST V4签名独有的表单元素，请参见V4签名表单。关于POST V1签名独有的表单元素，请参见V1签名表单。

响应头

此接口还涉及其他公共响应头，例如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

policy表单域是一种安全策略，用于定义通过HTML表单上传文件到OSS时的权限限制和约束条件。policy表单域通过JSON格式定义，通过多项参数限制上传操作，例如允许上传的Bucket名称、Object前缀、有效期、允许的HTTP方法、上传内容的大小限制、内容类型限制等。

• 关于POST请求V4签名的policy详细介绍，请参见POST请求V4签名的policy

• 关于POST请求V1签名的policy详细介绍，请参见POST请求V1签名的policy。

POST signature

POST signature是指在使用PostObject上传方式时，为保证上传请求的安全性，OSS要求每个上传请求都携带一个签名（Signature），用于确保上传请求的合法性和安全性。

• 关于POST请求V4签名的详细介绍，请参见POST请求V4签名。

• 关于POST请求V1签名的详细介绍，请参见POST请求V1签名。

常见问题

报错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常见错误及排查。