PostObject

更新时间：2026-09-18

接口描述

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

PostObject 需要对 Bucket 有写权限。公共可读写的 bucket 不需要上传签名信息；否则需要通过 accessKey、policy 和 signature 进行签名校验。使用 STS 临时凭证鉴权时，还需要在表单域中传入 x-bce-security-token。

请求

请求结构

Http

1POST / HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Content-Length: <ContentLength>
4Date: <Date>
5Content-Type: multipart/form-data; boundary=<Boundary>
6
7--<Boundary>
8Content-Disposition: form-data; name="accessKey"
9
10<AccessKey>
11--<Boundary>
12Content-Disposition: form-data; name="policy"
13
14<Base64Policy>
15--<Boundary>
16Content-Disposition: form-data; name="signature"
17
18<Signature>
19--<Boundary>
20Content-Disposition: form-data; name="key"
21
22<ObjectKey>
23--<Boundary>
24Content-Disposition: form-data; name="Content-Disposition"
25
26<ContentDisposition>
27--<Boundary>
28Content-Disposition: form-data; name="x-bce-meta-object-tag"
29
30<CustomMetaValue>
31--<Boundary>
32Content-Disposition: form-data; name="x-bce-storage-class"
33
34<StorageClass>
35--<Boundary>
36Content-Disposition: form-data; name="success-redirect-url"
37
38<SuccessRedirectUrl>
39--<Boundary>
40Content-Disposition: form-data; name="file"; filename="<UploadFileName>"
41Content-Type: <FileContentType>
42
43<FileContent>
44--<Boundary>--

如需指定 Object 的存储类型，请使用表单域 x-bce-storage-class。file 必须是表单中的最后一个域，如果 file 后面有其他域会被忽略。

请求头域

名称	类型	是否必须	描述
Host	String	是	请求的 Bucket 域名，格式为 `<BucketName>.bj.bcebos.com`。
Content-Length	Integer	是	HTTP 请求内容长度。
Date	String	是	请求时间，使用 GMT 时间格式。
Content-Type	String	是	请求内容类型，必须为 `multipart/form-data; boundary=<Boundary>`。

参数名（名词）	类型	位置	是否必须	描述
accessKey	String	Body（表单域）	否	用户的 AccessKey。公共可读写 Bucket 可不传；非公共可读写 Bucket 需要配合 `policy` 和 `signature` 使用。
Cache-Control、Content-Type、Content-Disposition、Expires	String	Body（表单域）	否	上传 Object 支持的 Header。上传时设置这些 Header，下载时会带着这些 Header 返回。
file	File	Body（表单域）	是	上传的文件内容，必须是表单中最后一个域，如果 `file` 后面有其他域会被忽略。
key	String	Body（表单域）	是	上传 Object 的名称。没有这个字段会报错。
policy	String	Body（表单域）	否	policy 描述表单的限制条件。不包含 policy 的匿名请求只能访问公共可读写的 Bucket。policy 必须为 Base64 编码格式，最大限制为 4096 个字符。policy 格式参见下方说明。
signature	String	Body（表单域）	否	signature 是根据 SecretKey 和 policy 计算的签名信息，BOS 验证 signature 从而验证 Post 请求的合法性。
success-redirect-url	String	Body（表单域）	否	上传成功之后跳转的 URL。
success-action-status	Integer	Body（表单域）	否	支持 `200`、`201`、`204`，默认为 `200`。取值为 `201` 时，`Location` 字段返回 Object 的位置。
x-bce-meta-*	String	Body（表单域）	否	用户自定义 meta。
x-bce-storage-class	String	Body（表单域）	否	指定 Object 的存储类型。`STANDARD_IA` 代表低频存储，`COLD` 代表冷存储，`ARCHIVE` 代表归档存储，不指定时默认是标准存储类型；如果是多 AZ 类型 Bucket，`MAZ_STANDARD_IA` 代表多 AZ 低频存储，不指定时默认是 `MAZ_STANDARD` 多 AZ 标准存储类型，不能是其他取值。
x-bce-acl	String	Body（表单域）	否	CannedACL 支持的 Header，用户设置 Object 的权限，取值为 `private` 和 `public-read`。
x-bce-grant-read	String	Body（表单域）	否	CannedACL 支持的 Header，用户设置 Object 的读权限。支持多个 ID，以逗号分隔。
x-bce-grant-full-control	String	Body（表单域）	否	CannedACL 支持的 Header，用户设置 Object 的 `FULL_CONTROL` 权限。支持多个 ID，以逗号分隔。
x-bce-security-token	String	Body（表单域）	否	使用临时 AccessKey、SecretAccessKey 和 SessionToken 鉴权时必加字段。
x-bce-server-side-encryption	String	Body（表单域）	否	服务端加密算法，当前支持 `AES256` 和 `SM4` 加密。
x-bce-content-crc32	String	Body（表单域）	否	上传 Object 的 CRC 值（循环冗余校验码）。

policy 需要为 UTF-8 字符，支持过期时间设置和对 Bucket、key、文件长度的限制。Bucket 只支持精确匹配，Object 支持精确匹配和前缀匹配，格式如下：

                JSON
                
            

                {
  "expiration": "2015-03-01T12:00:00Z",
  "conditions": [
    {
      "bucket": "testbucket"
    },
    {
      "key": "testkey"
    },
    {
      "key": "testkey*"
    },
    [
      "content-length-range",
      0,
      4096
    ]
  ]
}
            

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

                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)
            

响应

响应头域

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

响应参数

无。

示例

请求示例#### 标准存储的请求示例

Http

1POST / 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--

低频/冷存储的请求示例

Http

1POST / 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="x-bce-storage-class"
33
34STANDARD_IA
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--

STS 鉴权方式请求示例

Http

1POST / 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--

响应示例

Http

1HTTP/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

评价此篇文章

有帮助没帮助

PutObject

CopyObject

百度智能云

BOS 对象存储

BOS 对象存储

PostObject

接口描述

请求

请求结构

请求头域

响应

响应头域

响应参数

示例

请求示例#### 标准存储的请求示例

低频/冷存储的请求示例

STS 鉴权方式请求示例

响应示例