接口功能介绍
此接口用于通过HTML表单上传的方式将对象上传到指定的存储空间bucket中。
接口约束
提交表单的URL为Bucket域名，不需要在URL中指定Object。即请求行是POST / ，不能写为POST /ObjectName 。
Post请求需要对Bucket拥有写权限。如果Bucket为public-read-write，可以不上传签名信息，否则要求对该操作进行签名验证。
Post操作在签名方式上与Put有所不同，其是使用SecretAccessKey对policy进行签名，计算出签名字符串作为Signature表单域的值来验证合法性。
URI
POST /{bucketName}
路径参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| bucketName | 是 | String | 桶名称 | testBucket |
Query参数
无
请求参数
请求头header参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| Content-Type | 是 | String | Post操作提交表单编码必须为multipart/form-data，即Header中Content-Type为multipart/form-data;boundary=xxxxxx的形式 | |
| Authorization | 是 | String | 用于验证请求合法性的认证信息 |
请求体body参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| key | 是 | String | 上传Object的名称。如果名称包含路径，例如cts/1.jpg，则会自动创建相应的文件夹 | 1.jpg | |
| policy | 是（有条件） | String | Policy规定了请求表单域的合法性，是一段经过UTF-8和Base64编码的JSON文本。不包含Policy表单域的请求被认为是匿名请求，并只能访问public-read-write的Bucket， 当Bucket为非public-read-write或者提供了AccessKeyId（或Signature）表单域时，必须提供Policy表单域 | ||
| acl | 否 | String | 在文件表单域中指定Object的访问权限。取值： private,public-read， public-read-write authenticated-read， bucket-owner-read， bucket-owner-full-control。默认private | private | |
| x-amz-meta- | 否 | String | 用户指定的user meta值 | x-amz-meta-location | |
| Cache-Control | 否 | String | 指定该对象被下载时网页的缓存行为 | 请参见RFC 2616 | |
| Content-Type | 否 | String | 文件类型 | image/jpeg | |
| x-amz-security-token | 否 | String | 安全令牌。仅在通过STS构造POST签名时需要该参数。可以通过调用STS服务的AssumeRole接口获取安全令牌 | ek+NvIdz*** | |
| Content-Disposition | 否 | String | 指定该对象被下载时的名称 | 请参见RFC 2616 | |
| Content-Encoding | 否 | String | 指定该对象被下载时的内容编码格式 | 请参见RFC 2616 | |
| Expires | 否 | String | 过期时间 | 请参见RFC 2616 | |
| success_action_redirect | 否 | String | 上传成功后客户端跳转到的URL。如果未指定该表单域，返回结果由success_action_status表单域指定。如果上传失败，返回错误码，并不进行跳转 | ||
| success_action_status | 否 | String | 未指定success_action_redirect表单域时，该表单域指定了上传成功后返回给客户端的状态码。 有效值：200、201、204（默认）。其中 200或者204，返回一个空文档和相应的状态码， 201，返回一个XML文件和201状态码，如果未设置或者设置为一个非法值，返回一个空文档和204状态码。注：如果设置为null则返回400 | 201 | |
| file | 是 | String | 文件或者文本内容。一次只能上传一个文件。注意：file必须为最后一个表单域 |
上述参数是POST上传的公共参数表，而不同的POST签名版本有对应的独有参数，具体可参见POST请求签名（V2版本）以及POST请求签名（V4版本）中所说明的独有参数。
响应参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| PostResponse | 是 | Array of Objects | 保存Post请求结果,此响应参数只有在返回状态码为201的时候，才返口 | PostResponse |
表 PostResponse
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| Bucket | 是 | String | bucket的名称 | ||
| Key | 是 | String | 对象的名称 | ||
| Location | 是 | String | 新创建的Object的URL |
请求示例
POST /testBucket HTTP/1.1
请求头header
Host: Bucgdoss.xstore.ctyun.cn
Date: Wed, 28 Oct 2023 09:32:00 GMT
Content-Type: multipart/form-data;boundary=xxxxxx
Content-Length: xxx
请求体body
Content-Disposition: form-data; name="key"
key
--xxxxxx
Content-Disposition: form-data; name="success_action_status"
200
---xxxxxx
Content-Disposition: form-data; name="AWSAccessKeyId"
67CF9530006ee252****
---xxxxxx
Content-Disposition: form-data; name="policy"
XXX1dfQ==
---xxxxxx
Content-Disposition: form-data; name="Signature"
CToYNv66bsee20+dcGKw5x2P****
---xxxxxx
Content-Disposition: form-data; name="file"; filename="test.txt"
Content-Type: text/plain
file content
---xxxxxx
响应示例
HTTP/1.1 200 OK
x-amz-request-id: tx00000000000000000****
Date: Thu, 15 Sep 2022 08:36:33 GMT
Connection: keep-alive
响应示例
HTTP/1.1 200 OK
x-amz-request-id: tx00000000000000000****
Date: Thu, 15 Sep 2022 08:36:33 GMT
Connection: keep-alive
状态码
| 状态码 | 错误码 | 描述 |
|---|---|---|
| 200 | 操作成功 | |
| 400 | InvalidArgument | 缺少特定参数或者参数不合法 |
| 403 | AccessDenied | 用户没有权限执行操作 |
| 404 | NoSuchBucket | 操作指定的桶不存在 |
| 404 | NoSuchKey | key对应的对象不存在 |
错误码
请参考 请求错误码（原生接口）。
POST签名
关于POST请求Policy以及相关签名的详细介绍，请参见POST请求签名（V2版本）及POST请求签名（V4版本）介绍。
