文档简介：
POST Object
POST操作使用HTML表单将对象上传到指定的Bucket。POST是另一种形式的PUT操作，POST可以让使用者通过Browser-based的方式，将对象上传到指定bucket中。PUT的参数是通过HTTP Header提交的，而POST通过使用multipart/form-data编码的消息体中的字段进行提交。用户必须对操作的Bucket有写权限。OOS不存储部分对象：如果收到成功的响应，那么对象就是存储成功了。
为了保证数据在网络传输过程中没有损坏，可以使用Content-MD5字段进行校验。如果请求参数中有Content-MD5，OOS将会计算用户提交的对象的MD5值。如果计算出的值与用户提供的值不一致，OOS将会返回一个错误给用户。或者，用户可以在上传对象到OOS时计算对象的MD5值，并与OOS在响应中返回的ETag进行比较。ETag是对象内容的MD5值，不包括metadata。
请求语法
|
POST /HTTP/1.1 Host: BucketName.oos-cn.ctyunapi.cn User-Agent: browser_data Accept: file_types Accept-Language: Regions Accept-Encoding: encoding Accept-Charset: character_set Keep-Alive: 300 Connection: keep-alive Content-Type: multipart/form-data; boundary=9431149156168 Content-Length: length
--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-Type"
content_type --9431149156168 Content-Disposition: form-data; name="x-amz-meta-uuid"
uuid --9431149156168 Content-Disposition: form-data; name="x-amz-meta-tag"
metadata --9431149156168 Content-Disposition: form-data; name="AWSAccessKeyId"
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 OOS --9431149156168— |
请求参数
本实现不使用请求参数。
表单字段
说明：表单中指定的每个表单字段（AWSAccessKeyId、签名、文件、策略和带x-ignore-前缀的字段名称除外）必须包含在policy条件列表中,两者需要保持一致。
|
名称 |
描述 |
是否必需 |
|
AWSAccessKeyId |
根用户或拥有权限的子用户的访问密钥ID，该用户将授予匿名用户对满足策略中一组约束的请求的访问权限。如果请求包含Policy，对于V2签名，则此字段为必填字段。 类型：String 默认值：无 |
条件 |
|
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires |
特定于REST的请求头。有关更多信息，请参阅PUT Object。 类型：String 默认值：无 |
否 |
|
file |
文件或文本内容。文件或文本内容必须是Form表单的最后一个字段。一次只能上传一个文件。 类型：文件或文本内容 默认值：无 |
是 |
|
key |
上传对象的名称。 可以使用${filename}变量来使用用户提供的文件名。例如，如果用户Betty上传的文件名为lolcatz.jpg, 字段值指定为/user/betty/${filename}，那么保存的对象名称将会是/user/betty/lolcatz.jpg。 类型：String 默认值：无 |
是 |
|
policy |
描述请求中允许的内容的安全策略。对于非匿名请求，Policy字段是必须的。 Policy的设置参见Bucket Policy字段的构造。 类型：String 默认值：无 |
条件 |
|
signature |
使用AWSAccessKeyId对应的秘钥对policy的签名。如果请求包含Policy，对于V2签名，则此字段为必填字段。 signature = Base64(HMAC-SHA1(YourSecrectKey,policy))，具体计算方法请查看Signature字段的构造步骤。 |
条件 |
|
X-Amz-Algorithm |
签名算法。如果请求包含Policy，对于V4签名，则此字段为必填字段。 取值：AWS4-HMAC-SHA256。 默认值：无 |
条件 |
|
X-Amz-Credential |
用户的accessKeyId和范围信息，范围信息包括请求日期、区域、服务、终止字符串aws4_request，格式如下： ////aws4_request 其中： l date格式为YYYYMMDD。 l region：访问域名，对象存储域名详见 Endpoint列表； l service：取值s3。 如果请求包含Policy，对于V4签名，则此字段为必填字段。 |
条件 |
|
X-Amz-Date |
日期和时间格式必须遵循ISO 8601标准，并且必须使用“yyyyMMddT HHmmssZ”格式进行格式化。例如，如果日期和时间是“08/01/2018 15：32：41.982-700”，则必须首先将其转换为UTC（协调世界时），然后提交为“20180801T083241Z”。 如果请求包含Policy，对于V4签名，则此字段为必填字段。 |
条件 |
|
X-Amz-Signature |
认证签名，此签名必须与OOS计算的签名相匹配;否则，OOS拒绝该请求。 如果请求包含Policy，对于V4签名，则此字段为必填字段。 |
条件 |
|
success_action_redirect,redirect |
上传成功后客户端重定向到的URL。OOS将Bucket、对象名和etag值作为查询字符串参数附加到URL。 如果未指定 success_action_redirect，OOS将返回在success_action_status字段中指定的空文档类型。 如果OOS无法识别用户提供的URL，将忽略该字段。 如果上传失败，OOS将显示错误且不会执行重定向操作。 类型：String 默认值：无 注意：redirect将在可能会移除，建议使用success_action_redirect |
否 |
|
success_action_status |
如果没有指定success_action_redirect，上传成功后状态代码将返回到客户端。 有效值：200、201或204（默认）。 l 如果值被设置为200或204，OOS将返回一个空文档和一个200或204状态代码。 l 如果值被设置为201，OOS将返回一个XML文档和一个201状态代码。有关XML文档内容的信息，请参阅POST对象。 l 如果没有设置值或者设置了无效的值，OOS将返回一个空文档和一个204状态代码。 注意： 某些版本的AdobeFlashplayer无法正确处理使用空白正文的HTTP响应。要通过AdobeFlash支持上传，建议您将success_action_status设置为201。 |
否 |
|
x-amz-storage-class |
数据的存储类型。 类型: String 取值: l STANDARD：标准存储 l REDUCED_REDUNDANCY：低冗余存储 l STANDARD_IA：低频访问存储 默认值为STANDARD。 |
否 |
|
x-amz-meta-* |
任何头以这个前缀开始都会被认为是用户的元数据，当用户检索时，它将会和对象一起被存储并返回。更多信息请参考PUT Object 类型：String 默认值：无 |
否 |
|
x-amz-website-redirect-location
|
如果Bucket配置为网站，重定向对这个对象的请求到相同Bucket的另外一个对象或者到一个其他的URL。OOS会保存这个值到对象的metadata。对象的metadata信息请参考Object Key和Metadata部分。 下面这个例子表示请求头设置重定向到相同Bucket的另一个对象(anotherPage.html)。 x-amz-website-redirect-location: /anotherPage.html 重定向到其他网站的例子： x-amz-website-redirect-location: /span>www.example.com/ 注意：这个值必须以”/”、/span>或/span>开头，且长度不能超过2KB。 |
否 |
|
x-ctyun-data-location |
设置Bucket的数据位置。 类型：key-value形式。 有效值： 格式为：type=Local,scheduleStrategy=scheduleStrategy或者type=Specified,location=location,scheduleStrategy=scheduleStrategy l type：指定数据存储位置的类型，取值为Local或者Specified。Local表示就近写入，Specified表示指定位置。如果type取值为Specified，则需要指定具体的数据位置location，location可以填写多个，以逗号分隔，可取值为ChengDu、GuiYang、LaSa、LanZhou、QingDao、SH2、ShenYang、ShenZhen、SuZhou、WuHan、WuHu、WuLuMuQi、ZhengZhou。 l scheduleStrategy：调度策略，取值为： Ø Allowed：允许OOS自动调度数据存储位置 Ø NotAllowed：不允许OOS自动调度数据存储位置。 |
否 |
响应格式
响应头
除了通用的响应头以外，本操作可以包括以下响应头。
|
名称 |
描述 |
|
x-amz-expiration |
如果对象设置了过期时间（参考PUT Bucket Lifecycle章节），响应头会增加过期信息。过期信息包括过期日期和rule-id的key和value。rule-id的value是经过URL编码的。 类型：String |
|
success_action_redirect, redirect |
上传成功重定向的URL。 类型：String |
响应体
|
名称 |
描述 |
|
Bucket |
存储Object的Bucket名称。 类型：字符串 父元素：PostResponse |
|
ETag |
ETag是对象内容经过MD5哈希后得到的值。用户可以在GET请求中使用If-Match请求头。ETag仅反映对象内容的变化，不包括元数据。 类型：String 父元素：PostResponse |
|
Key |
对象名称。 类型：String 父元素：PostResponse |
|
Location |
对象的URL。 类型：String 父元素: PostResponse |
请求示例
|
POST / HTTP/1.1 Content-Length: 4 Host: BucketName.oos-cn.ctyunapi.cn Date: Wed, 01 Mar 2009 12:00:00 GMT Content-Type: text/plain Expect: the 100-continue HTTP status code ObjectContent |
响应示例
下面的代码演示了一个简单的响应头。
|
HTTP/1.1 200 OK x-amz-request-id: 0A49CE4060975EAC Date: Wed, 12 Oct 2009 17:50:00 GMT ETag: "1b2cf535f27731c974343645a3985328" Content-Length: 0 Connection: close Server: OOS |
说明
表单声明包含三个部分：action、method和enctype。如果这些值当中的任意一个设置不正确，请求将失败。action指定处理请求的URL，必须将它设置为Bucket的URL。例如：Bucket的名称是BucketName，则URL为/。
method必须是POST。enctype设置为“multipart/form-data”。
|
|
Post Policy是使用UTF-8和Base64编码的JSON文档，它指定了请求必须满足的条件并且用于对内容进行身份验证。根据您设计策略文档的方式，您可以对每次上传、每个用户、所有上传或根据其他能够满足您需要的设计来使用它们。
下面是一个简单的Post Policy示例
|
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ { "bucket": "johnsmith" }, [ "starts-with", "$key", "user/eric/" ] ] } |
策略文档由过期(expiration)和条件(conditions)两部分构成。
过期
过期元素采用ISO 8601UTC日期格式来指定策略的过期日期。例如，“2007-12-01T12:00:00.000Z”指定策略在2007年12月1日午夜UTC之后失效。在策略文档中过期字段是必需的。
条件
策略文档中的条件验证上传的对象的内容。您在表单中指定的每个表单字段（AWSAccessKeyId、签名、文件、策略和带x-ignore-前缀的字段名称除外）必须包含在条件列表中。如果您有多个具有相同名称的字段，使用逗号进行分隔。例如，如果您有两个名为x- amz-meta-tag的字段，第一个字段的值为Ninja，第二个字段的值为Stallman，您可以将策略文档设置为Ninja,Stallman。
针对扩展的字段执行前缀匹配。例如，如果您将对象名称字段设置为user/betty/${filename}，您的策略可能是["starts-with", "$key", "user/betty/" ]。请勿输入["starts-with", "$key", "user/betty/${filename}"]。
|
元素名称 |
说明 |
|
bucket |
指定上传内容允许的Bucket。 支持精确匹配和starts-with。 |
|
content-length-range |
指定已上传内容允许的最小和最大大小。 支持范围匹配。 |
|
Cache-Control, Content-Type, Content-Disposition, Content- Encoding, Expires |
特定于 REST 的标头。 支持精确匹配和starts-with。 |
|
Key |
已上传的密钥的名称。 支持精确匹配和 starts-with。 |
|
success_action_redirect, redirect |
上传成功后客户端重定向到的URL。 支持精确匹配和starts-with。 |
|
success_action_status |
如果没有指定 success_action_redirect，上传成功后状态代码将返回到客户端。 支持精确匹配。 |
|
其他以 x-amz-meta- 为前缀的字段名称 |
特定于用户的元数据。 支持精确匹配和 starts-with。 |
注意：
如果您的工具包添加了其他字段（例如，Flash添加了文件名），您必须将它们添加到策略文档。如果您可以控制此功能，将 x-ignore- 添加为字段的前缀以使OOS忽略此功能并使其不影响此功能的未来版本。
条件匹配
下表介绍条件匹配类型。尽管您必须为您在表单中指定的每个表单字段指定一个条件，您也可以通过为某个表单字段指定多个条件来创建更复杂的匹配条件。
|
条件 |
说明 |
|
精确匹配 |
精确匹配将验证字段是否匹配特定的值。此示例指示bucket必须设置为BucketName： {"bucket": "BucketName"} 也可写为： [ "eq", "bucket": "BucketName"] |
|
Starts With |
如果值必须从某个特定的值开始，请使用starts-with。本示例指示密钥必须从 user/betty 开始： ["starts-with", "$key", "user/betty/"] |
|
匹配任何内容 |
要配置策略以允许字段中的任何内容，请使用 starts-with 和一个空值。本示例允许任何 success_action_redirect： ["starts-with", "$success_action_redirect", ""] |
|
指定范围 |
对于接受范围的字段，请使用逗号来分隔上限和下限值。本示例允许1到10 MB 的文件大小： ["content-length-range", 1048579, 10485760] |
字符串转义
|
转义序列 |
描述 |
|
\\ |
反斜杠。 |
|
\$ |
美元符号。 |
|
\b |
退格键。 |
|
\f |
换页。 |
|
\n |
新建行。 |
|
\r |
回车。 |
|
\t |
水平选项卡。 |
|
\v |
垂直选项卡。 |
|
\uxxxx |
所有Unicode 字符。 |
Signature字段的构造步骤
|
步骤 |
说明 |
|
1 |
使用UTF-8对策略进行编码。 |
|
2 |
使用Base64对这些UTF-8字节进行编码。 |
|
3 |
使用HMAC SHA-1，通过您的秘密访问密钥签署策略。 |
|
4 |
使用Base64对SHA-1签名进行编码。 |
