PostObject

更新时间：2023-03-16

接口描述

此接口使用HTML表单上传文件到指定bucket，用于实现通过浏览器上传文件到bucket。在PutObject操作中通过HTTP请求头传递参数，在PostObject操作中使用消息实体中的表单域传递参数，其中消息实体使用多重表单格式（multipart/form-data）编码。

请求（Request）

请求语法

POST / HTTP/1.1 
Host: BucketName.bj.bcebos.com
Content-Length：<ContentLength>
Storage-class: <StorageClass>
Date：<date>
Content-Type: multipart/form-data; boundary=<boundary>

--<boundary>
Content-Disposition: form-data; name="accessKey"

499d0610679c4da2a69b64086a4cc3bc
--<boundary>
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
--<boundary>
Content-Disposition: form-data; name="signature"

d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
--<boundary>
Content-Disposition: form-data; name="key"

test_object_name
--<boundary>
Content-Disposition: form-data; name="Content-Disposition"

attachment;filename="download/object"
--<boundary>
Content-Disposition: form-data; name="x-bce-meta-object-tag"

test1
--<boundary>
Content-Disposition: form-data; name="success-redirect-url"

http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
--<boundary>
Content-Disposition: form-data; name="file"; filename="upload_file"
Content-Type: text/plain

i'm test file content.
--<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支持精确匹配和前缀匹配，格式如下：

 { "expiration": "2015-03-01T12:00:00Z",
   "conditions": [
        {
            "bucket": "testbucket" 
        },
        {
            "key": "testkey"
        }, // 精确匹配
        {
            "key": "testkey*"
        }, // 前缀匹配, 有且只有一个*，且只能放到最后
        ["content-length-range", 0, 4096]
   ]
 }

注意事项

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代码：

import base64
import hashlib
import hmac

sk = bytes('<your secret key>','utf-8')
policy = bytes('your policy','utf-8')
signature = hmac.new(sk, base64.b64encode(policy), hashlib.sha256).hexdigest()
print(signature)

响应（Response）

响应头域

名称	类型	描述
Content-MD5	String	RFC2616定义的HTTP请求内容的MD5摘要，可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
ETag	String	Object的HTTP协议实体标签

响应参数

无

示例

标准存储的请求示例

POST / HTTP/1.1 
Host: BucketName.bj.bcebos.com
Content-Length：11434
Date：Tue, 29 Mar 2016 12:00:00 GMT
Content-Type: multipart/form-data; boundary=341261481596

--341261481596
Content-Disposition: form-data; name="accessKey"

499d0610679c4da2a69b64086a4cc3bc
--341261481596
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
--341261481596
Content-Disposition: form-data; name="signature"

d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
--341261481596
Content-Disposition: form-data; name="key"

test_object_name
--341261481596
Content-Disposition: form-data; name="Content-Disposition"

attachment;filename="download/object"
--341261481596
Content-Disposition: form-data; name="x-bce-meta-object-tag"

test1
--341261481596
Content-Disposition: form-data; name="success-redirect-url"

http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
--341261481596
Content-Disposition: form-data; name="file"; filename="upload_file"
Content-Type: text/plain

i'm test file content.
--341261481596--

低频/冷存储的请求示例

POST / HTTP/1.1 
Host: BucketName.bj.bcebos.com
Content-Length：11434
Storage-class: STANDARD_IA 
Date：Tue, 29 Mar 2016 12:00:00 GMT
Content-Type: multipart/form-data; boundary=341261481596

--341261481596
Content-Disposition: form-data; name="accessKey"

499d0610679c4da2a69b64086a4cc3bc
--341261481596
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
--341261481596
Content-Disposition: form-data; name="signature"

d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
--341261481596
Content-Disposition: form-data; name="key"

test_object_name
--341261481596
Content-Disposition: form-data; name="Content-Disposition"

attachment;filename="download/object"
--341261481596
Content-Disposition: form-data; name="x-bce-meta-object-tag"

test1
--341261481596
Content-Disposition: form-data; name="success-redirect-url"

http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
--341261481596
Content-Disposition: form-data; name="file"; filename="upload_file"
Content-Type: text/plain

i'm test file content.
--341261481596--

STS鉴权方式请求示例

POST / HTTP/1.1 
Host: BucketName.bj.bcebos.com
Content-Length：11434
Date：Tue, 29 Mar 2016 12:00:00 GMT
Content-Type: multipart/form-data; boundary=341261481596

--341261481596
Content-Disposition: form-data; name="accessKey"

499d0610679c4da2a69b64086a4cc3bc
--341261481596
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
--341261481596
Content-Disposition: form-data; name="signature"

d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
--341261481596
Content-Disposition: form-data; name="x-bce-security-token"

ds3wHsWRSAJFeafjkAji2OFjJIOLijRk32IRRAJfMISTRhIAJfSJHkdsa
--341261481596
Content-Disposition: form-data; name="key"

test_object_name
--341261481596
Content-Disposition: form-data; name="Content-Disposition"

attachment;filename="download/object"
--341261481596
Content-Disposition: form-data; name="x-bce-meta-object-tag"

test1
--341261481596
Content-Disposition: form-data; name="success-redirect-url"

http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
--341261481596
Content-Disposition: form-data; name="file"; filename="upload_file"
Content-Type: text/plain

i'm test file content.
--341261481596--

响应示例

HTTP/1.1 200 OK
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date：Tue, 29 Mar 2016 12:00:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-MD5: H2koac2M0YsMxDNte2XJ8A==
Content-Length: 0
Connection: close
Server: BceBOS

GetObjectMeta

ListObjects

百度智能云

对象存储 BOS