PostObject
所有文档
menu

对象存储 BOS

PostObject

产品详情自助选购

接口描述

此接口使用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