调用PostObject用于通过HTML表单上传的方式将文件(Object)上传到指定存储空间(Bucket)。
注意事项
要通过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--
请求头
PostObject的消息实体通过多重表单格式(multipart/form-data)编码,在PutObject操作中参数通过HTTP请求头传递,在PostObject操作中参数作为消息体中的表单域传递。
PostObject操作过程中不支持通过传入x-oss-tagging请求头的方式为Object添加标签。您可以在PostObject操作完成后调用PutObjectTagging接口为Object添加标签。
名称 | 类型 | 是否必选 | 描述 |
Content-Type | 字符串 | 否 | 指定文件的类型和网页的编码,确定浏览器读取文件的形式和编码方式。 Post操作提交表单编码必须为 boundary为边界字符串,是由表单随机生成的一个随机值,无需指定。如果通过SDK拼接表单,则SDK也会生成一个随机值。 |
x-oss-object-acl | 字符串 | 否 | 在请求头中指定Object的访问权限。 当请求头和文件表单域中同时指定x-oss-object-acl时,文件表单域中设置的访问权限的优先级高于请求中设置的访问权限。 取值:
关于访问权限的更多信息,请参见设置Object ACL。 |
此接口还需要包含Host、Date等公共请求头。更多信息,请参见公共请求头(Common Request Headers)。
表单元素
以下表格列举了POST V1和V4签名共有的表单元素。关于POST V4签名独有的表单元素,请参见V4签名表单。关于POST V1签名独有的表单元素,请参见V1签名表单。
file必须为最后一个表单域,除file以外的其他表单域无顺序要求。
所有表单域的key大小不能超过8 KB,表单域的value不能超过2 MB。
名称 | 类型 | 是否必选 | 描述 |
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表单域。 重要 表单和policy必须使用UTF-8编码,且policy表单域要经过Base64编码。 |
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请求Header会导致QPS处理性能下降,如果您有大量的操作需要使用x-oss-forbid-overwrite请求头(QPS > 1000),请联系技术支持,避免影响您的业务。 |
x-oss-object-acl | 字符串 | 否 | 在文件表单域中指定Object的访问权限。此项支持同时在请求头和文件表单域中指定。 当请求头和文件表单域中同时指定x-oss-object-acl时,文件表单域中设置的访问权限的优先级高于请求中设置的访问权限。 取值:
关于访问权限的更多信息,请参见设置Object ACL。 |
x-oss-storage-class | 字符串 | 否 | 指定Object的存储类型。 对于任意存储类型的Bucket,如果上传Object时指定此参数,则此次上传的Object将存储为指定的类型。例如在IA类型的Bucket中上传Object时,如果指定x-oss-storage-class为Standard,则该Object直接存储为Standard。 取值:
关于更多信息,请参见存储类型介绍。 |
key | 字符串 | 是 | 上传Object的名称,无需编码。如果名称包含路径,例如 默认值:无 |
success_action_redirect | 字符串 | 否 | 上传成功后客户端跳转到的URL。如果未指定该表单域,返回结果由success_action_status表单域指定。如果上传失败,OSS返回错误码,并不进行跳转。 默认值:无 |
success_action_status | 字符串 | 否 | 未指定success_action_redirect表单域时,该表单域指定了上传成功后返回给客户端的状态码。 有效值:200、201、204(默认)。
|
x-oss-meta-* | 字符串 | 否 | 用户指定的user meta值。 默认值:无 如果请求中携带以x-oss-meta-为前缀的表单域,则视为user meta,例如 说明 一个Object可以有多个类似的参数,但所有的user meta总大小不能超过8 KB。 |
x-oss-security-token | 字符串 | 否 | 安全令牌。仅当使用STS构造URL签名时,才需要设置此参数。您可以通过调用STS服务的AssumeRole接口获取安全令牌。 默认值:无 |
file | 字符串 | 是 | 文件或文本内容,无需编码。浏览器会自动根据文件类型来设置Content-Type,并覆盖用户的设置。OSS一次只能上传一个文件。 默认值:无 重要 file必须为最后一个表单域。 |
响应头
名称 | 类型 | 示例值 | 描述 |
x-oss-server-side-encryption | 字符串 | KMS | 如果请求Header中指定了x-oss-server-side-encryption,则响应Header中将包含该头部,指明所使用的服务器端加密算法。 |
Content-MD5 | 字符串 | 1B2M2Y8AsgTpgAmY7PhC**** | 表示文件的MD5值。 重要 文件的MD5值指的是客户端上传完成后获取到的文件MD5,并非响应体的MD5。 |
x-oss-hash-crc64ecma | 字符串 | 316181249502703**** | 表示文件的CRC64值。 |
x-oss-version-id | 字符串 | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** | 表示文件的版本ID。仅当您将文件上传至已开启版本控制状态的Bucket时,会返回该响应头。 |
此接口还涉及其他公共响应头,例如Date、x-oss-request-id等。更多信息,请参见公共响应头(Common Response Headers)。
响应元素
名称 | 类型 | 描述 |
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" 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
错误码
错误码 | 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内的数据处于被保护状态时,如果您尝试删除或修改这些数据,将返回此错误码。 |
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常见错误及排查。