PostObject
更新时间：2023-03-16
接口描述
此接口使用HTML表单上传文件到指定bucket，用于实现通过浏览器上传文件到bucket。在PutObject操作中通过HTTP请求头传递参数，在PostObject操作中使用消息实体中的表单域传递参数，其中消息实体使用多重表单格式（multipart/form-data）编码。
请求（Request）
Plain Text
1POST / HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length：<ContentLength>
4Storage-class: <StorageClass>
5Date：<date>
6Content-Type: multipart/form-data; boundary=<boundary>
7
8--<boundary>
9Content-Disposition: form-data; name="accessKey"
10
11499d0610679c4da2a69b64086a4cc3bc
12--<boundary>
13Content-Disposition: form-data; name="policy"
14
15eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
16--<boundary>
17Content-Disposition: form-data; name="signature"
18
19d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
20--<boundary>
21Content-Disposition: form-data; name="key"
22
23test_object_name
24--<boundary>
25Content-Disposition: form-data; name="Content-Disposition"
26
27attachment;filename="download/object"
28--<boundary>
29Content-Disposition: form-data; name="x-bce-meta-object-tag"
30
31test1
32--<boundary>
33Content-Disposition: form-data; name="success-redirect-url"
34
35http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
36--<boundary>
37Content-Disposition: form-data; name="file"; filename="upload_file"
38Content-Type: text/plain
39
40i'm test file content.
41--<boundary>--| 名词 | 类型 | 描述 | 是否必须 |
|---|---|---|---|
| accessKey | String | 用户的AccessKey | 可选 |
| Cache-Control、Content-Type、Content-Disposition、Expires | String | 上传object支持的Header，上传时设置这些header，下载时会带着这些header返回。 | 可选 |
| file | - | 上传的文本内容，必须是表单中最后一个域，如果file后面有其他域会忽略掉。 | 是 |
| key | String | 上传object的名称，没有这个字段会报错。 | 是 |
| policy | String | policy描述表单的限制条件，不包含policy的匿名请求，只能访问公共可读写的bucket。policy必须为base64编码格式，最大限制为4096个字符。policy格式参见表格下方说明。 | 可选 |
| signature | String | signature是根据secret key和policy计算的签名信息，BOS验证signature从而验证Post请求的合法性。 | 可选 |
| success-action-redirect | String | 上传成功之后跳转的URL。 | - |
| success-action-status | Int | 支持200,201,204；默认为200，201时Location字段返回object的位置。 | - |
| x-bce-meta-* | String | 用户自定义meta。 | 可选 |
| x-bce-storage-class | String | 指定Object的存储类型，STANDARD_IA代表低频存储，COLD代表冷存储，ARCHIVE代表归档存储，不指定时默认是标准存储类型；如果是多AZ类型bucket，MAZ_STANDARD_IA代表多AZ低频存储，不指定时默认是MAZ_STANDARD多AZ标准存储类型，不能是其它取值 。 |
可选 |
| x-bce-acl | String | CannedACL支持的header，用户设置Object的权限，取值为private和public-read。 | 否 |
| x-bce-grant-read | String | CannedACL支持的header，用户设置Object的读权限。支持多个id，以逗号分隔 | 否 |
| x-bce-grant-full-control | String | CannedACL支持的header，用户设置Object的FULL_CONTROL权限。支持多个id，以逗号分隔。 | 否 |
| x-bce-security-token | String | 临时AccessKey/secretAccessKey和sessionToken鉴权必加字段。 | 否 |
| x-bce-server-side-encryption | String | 服务端加密算法，当前支持AES256和SM4加密。 | 否 |
| x-bce-content-crc32 | String | 上传object的CRC值(循环冗余校验码)。 | 否 |
policy需要为UTF-8字符，支持过期时间设置和对bucket、key、文件长度的限制，bucket只支持精确匹配，object支持精确匹配和前缀匹配，格式如下：
Plain Text
1 { "expiration": "2015-03-01T12:00:00Z",
2 "conditions": [
3 {
4 "bucket": "testbucket"
5 },
6 {
7 "key": "testkey"
8 }, // 精确匹配
9 {
10 "key": "testkey*"
11 }, // 前缀匹配, 有且只有一个*，且只能放到最后
12 ["content-length-range", 0, 4096]
13 ]
14 }注意事项
- PostObject需要对Bucket有写权限，公共可读写的bucket不需要上传签名信息；否则需要验证签名。与PutObject不同，PostObject使用ak对应的sk对base64_encode之后的policy字段进行签名作为signature，BOS会验证signature，从而校验用户的合法性。
- 整个表单域key和file是必选项，如果存在上述参数列表之外的参数，会报错InvalidArgument。
- 如果PostObject里有Authorization字段，BOS不会对其检查。
- PostObject操作提交表单编码必须为“multipart/form-data”，其他格式不支持，即header中Content-Type为multipart/form-data；boundary=xxxxxx这样的形式，boundary为边界字符串。
- PostObject现已支持STS鉴权。
- 如果您的请求大小超过了policy中的content-length-range范围，会返回MaxMessageLengthExceeded错误，您可以修改content-length-range最大值为您的请求实际大小，或者删除该值。
signature的签名方式可以参考Python代码：
Plain Text
1import base64
2import hashlib
3import hmac
4
5sk = bytes('<your secret key>','utf-8')
6policy = bytes('your policy','utf-8')
7signature = hmac.new(sk, base64.b64encode(policy), hashlib.sha256).hexdigest()
8print(signature)响应（Response）
-
响应头域
名称 类型 描述 Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要，可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。 ETag String Object的HTTP协议实体标签 -
响应参数
无
示例
-
标准存储的请求示例
Plain Text1POST / HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length：11434 4Date：Tue, 29 Mar 2016 12:00:00 GMT 5Content-Type: multipart/form-data; boundary=341261481596 6 7--341261481596 8Content-Disposition: form-data; name="accessKey" 9 10499d0610679c4da2a69b64086a4cc3bc 11--341261481596 12Content-Disposition: form-data; name="policy" 13 14eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19 15--341261481596 16Content-Disposition: form-data; name="signature" 17 18d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe 19--341261481596 20Content-Disposition: form-data; name="key" 21 22test_object_name 23--341261481596 24Content-Disposition: form-data; name="Content-Disposition" 25 26attachment;filename="download/object" 27--341261481596 28Content-Disposition: form-data; name="x-bce-meta-object-tag" 29 30test1 31--341261481596 32Content-Disposition: form-data; name="success-redirect-url" 33 34http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx 35--341261481596 36Content-Disposition: form-data; name="file"; filename="upload_file" 37Content-Type: text/plain 38 39i'm test file content. 40--341261481596-- -
低频/冷存储的请求示例
Plain Text1POST / HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length：11434 4Storage-class: STANDARD_IA 5Date：Tue, 29 Mar 2016 12:00:00 GMT 6Content-Type: multipart/form-data; boundary=341261481596 7 8--341261481596 9Content-Disposition: form-data; name="accessKey" 10 11499d0610679c4da2a69b64086a4cc3bc 12--341261481596 13Content-Disposition: form-data; name="policy" 14 15eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19 16--341261481596 17Content-Disposition: form-data; name="signature" 18 19d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe 20--341261481596 21Content-Disposition: form-data; name="key" 22 23test_object_name 24--341261481596 25Content-Disposition: form-data; name="Content-Disposition" 26 27attachment;filename="download/object" 28--341261481596 29Content-Disposition: form-data; name="x-bce-meta-object-tag" 30 31test1 32--341261481596 33Content-Disposition: form-data; name="success-redirect-url" 34 35http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx 36--341261481596 37Content-Disposition: form-data; name="file"; filename="upload_file" 38Content-Type: text/plain 39 40i'm test file content. 41--341261481596-- -
STS鉴权方式请求示例
Plain Text1POST / HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Content-Length：11434 4Date：Tue, 29 Mar 2016 12:00:00 GMT 5Content-Type: multipart/form-data; boundary=341261481596 6 7--341261481596 8Content-Disposition: form-data; name="accessKey" 9 10499d0610679c4da2a69b64086a4cc3bc 11--341261481596 12Content-Disposition: form-data; name="policy" 13 14eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19 15--341261481596 16Content-Disposition: form-data; name="signature" 17 18d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe 19--341261481596 20Content-Disposition: form-data; name="x-bce-security-token" 21 22ds3wHsWRSAJFeafjkAji2OFjJIOLijRk32IRRAJfMISTRhIAJfSJHkdsa 23--341261481596 24Content-Disposition: form-data; name="key" 25 26test_object_name 27--341261481596 28Content-Disposition: form-data; name="Content-Disposition" 29 30attachment;filename="download/object" 31--341261481596 32Content-Disposition: form-data; name="x-bce-meta-object-tag" 33 34test1 35--341261481596 36Content-Disposition: form-data; name="success-redirect-url" 37 38http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx 39--341261481596 40Content-Disposition: form-data; name="file"; filename="upload_file" 41Content-Type: text/plain 42 43i'm test file content. 44--341261481596-- -
响应示例
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Date：Tue, 29 Mar 2016 12:00:00 GMT 4ETag: "1b2cf535f27731c974343645a3985328" 5Content-MD5: H2koac2M0YsMxDNte2XJ8A== 6Content-Length: 0 7Connection: close 8Server: BceBOS