首页对象存储 OSS开发参考API参考关于Object操作基础操作PostObject
输入文档关键字查找

PostObject

更新时间：2024-12-30 06:19
产品详情
社区

调用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操作提交表单编码必须为multipart/form-data，即Header中Content-Type为multipart/form-data;boundary=xxxxxx的形式。

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

此接口还需要包含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-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：深度冷归档存储

    重要

    如果要上传的文件数量较多，直接指定上传的文件类型为深度冷归档类型会造成较高的PUT类请求费用。建议您先将文件的存储类型指定为标准存储进行上传，然后通过生命周期规则将其转储为深度冷归档类型，从而降低PUT类请求费用。

关于更多信息，请参见存储类型介绍。

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。

说明

一个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

SDK

此接口所对应的各语言SDK如下：

错误码

错误码

HTTP状态码

描述

错误码

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。如果设置为其他值，将返回此错误。

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的正确性，包括协议、域名、路径等部分。

POST policy

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

POST signature

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

常见问题

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

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

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

更多参考

上一篇：GetObjectMeta下一篇：Callback
  • 本页导读 （1）
  • 注意事项
  • 版本控制
  • 请求语法
  • 请求头
  • 表单元素
  • 响应头
  • 响应元素
  • 示例
  • SDK
  • 错误码
  • POST policy
  • POST signature
  • 常见问题
  • 报错Your proposed upload exceeds the maximum allowed size.如何处理？
  • 更多参考
文档反馈
phone 联系我们

立即和Alibaba Cloud在线服务人员进行交谈，获取您想了解的产品信息以及最新折扣。

alicare alicarealicarealicare