Object相关接口

PutObject接口

接口描述

此接口用于向指定的Bucket上传一个文件,请求者必须具有Write权限。在PutObject前需要确保对应的Bucket已经存在,BOS支持Object文件的长度范围是0Byte-5GB。如果需要上传大于5GB的文件,请参考分块上传

请求(Request)

  • 请求语法

    PUT /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: text/plain
    Content-Length: <Content_Length>
    x-bce-storage-class: <Storage_class>
    
  • 请求参数

    无特殊参数

  • 请求头域

    名称 类型 描述 是否必需
    Cache-Control String 下载Object的Cache设置,常见的可取值为privateno-cachemax-agemust-revalidate
    Content-Disposition String 设置浏览器是否下载,可取值为inlineattachment; filename="download.txt"
    Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
    Expires String 用于设置下载Object时的缓存失效时间,如果不做时间设置,BOS则会默认设置缓存失效时间为三天。
    x-bce-meta-* String 用户自定义的meta
    x-bce-content-sha256 String 通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则PutObject失败
    x-bce-content-crc32 String 上传object的CRC值(循环冗余校验码)。
    x-bce-storage-class String 指定Object的存储类型,STANDARD_IA代表低频存储,COLD代表冷存储,不指定时默认是标准存储类型。
    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-server-side-encryption String 服务端加密算法,当前仅支持AES256。

响应(Response)

  • 响应元素

  • 响应头域

    名称 类型 描述
    ETag String Object的HTTP协议实体标签

注意事项

  1. Content-Length是必须参数,如果请求者指定的Content-Length比实际请求体(Object的实际数据)长度小,BOS只保存Content-Length指定长度的数据,多的这部分数据直接废弃;相反,如果Content-Length的长度大,BOS将一直等待请求者上传数据,直到超时。
  2. BOS目前不支持Version,如果请求者重复Put一个Object,之前上传的数据将被覆盖。

示例

  • 标准存储的请求示例

    PUT /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 11434
    
    [11434 bytes of object data]
    
  • 低频/冷存储的请求示例

    PUT /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 11434
    x-bce-storage-class: STANDARD_IA 
    
    [11434 bytes of object data]
    
  • 响应示例

    HTTP/1.1 100 Continue
    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    ETag: "1b2cf535f27731c974343645a3985328"
    Content-Length: 0
    Connection: close
    Server: BceBos
    

PostObject接口

接口描述

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

请求(Request)

  • 请求语法

    POST / HTTP/1.1 
    Host: BucketName.bj.bcebos.com
    Content-Length:<content length>
    x-bce-storage-class: <Storage_class>
    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代表冷存储,不指定时默认是标准存储类型。 可选
    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-server-side-encryption String 服务端加密算法,当前仅支持AES256。
    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,从而校验用户的合法性。 签名逻辑为signature = hmac.new(sk, base64.b64encode(policy), hashlib.sha256).hexdigest()
  • 整个表单域key和file是必选项,如果存在上述参数列表之外的参数,会报错InvalidArgument。
  • 如果PostObject里有Authorization字段,BOS不会对其检查。
  • PostObject操作提交表单编码必须为“multipart/form-data”,其他格式不支持,即header中Content-Type为multipart/form-data;boundary=xxxxxx这样的形式,boundary为边界字符串。

响应(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
    x-bce-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--
    
  • 响应示例

    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
    

CopyObject接口

接口描述

此接口用于把一个已经存在的Object拷贝为另外一个Object,支持Object文件的长度范围是0Byte-5GB。该接口也可以用来实现Meta更新(使用replace模式且源和目标指向同一个文件)。此接口需要请求者在header中指定拷贝源。

CopyObject接口支持跨区域文件复制,即复制文件所在的源Bucket和目标Bucket可以不在同一region(目前只支持从其它Region向本Region复制数据)。当进行跨区域文件复制时,复制产生的流量会收取跨区域流量费。跨区域收费标准参见产品定价

请求(Request)

  • 请求语法

    PUT /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    Content-Type:text/plain
    x-bce-copy-source: /Source_Bucket/Source_Object
    x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
    x-bce-metadata-directive: <Directive_String>
    x-bce-storage-class: <Storage_Class>
    
  • 请求参数

  • 请求头域

名称类型描述是否必需
x-bce-copy-sourceString源Object地址
x-bce-copy-source-if-matchString如果源Object的ETag值和用户提供的ETag相等,则执行拷贝操作,否则拷贝失败。
x-bce-metadata-directiveString目的Object的Meta信息是从源Object拷贝,还是用请求传入的meta。有效值为copyreplace,缺省值为copy。如果设置为copy,则直接用源Object的meta;如果设置为replace,则用请求传入的meta。
x-bce-copy-source-if-none-matchString如果源Object的ETag和用户提供的ETag不相等,则执行拷贝操作,否则拷贝失败。
x-bce-copy-source-if-unmodified-sinceString 如果源object在x-bce-copy-source-if-unmodified-since之后没被修改,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。
x-bce-copy-source-if-modified-sinceString如果源object在x-bce-copy-source-if-modified-since之后被修改了,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。
x-bce-storage-classString指定Object的存储类型,STANDARD_IA代表低频存储,COLD代表冷存储,不指定时默认是标准存储类型。
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-server-side-encryption String 服务端加密算法,当前仅支持AES256。

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

名称 类型 描述
ETag String 目的Object的ETag
lastModified DATE 目的Object的最后一次修改时间

注意事项

  1. 请求者必须对源Object有读操作权限。
  2. 在计算签名之前,用户需要针对x-bce-copy-source字段中为非标准ASCII字符(例如:中文)的内容做一次url-encode。
  3. 为了保持复制过程中的http连接,CopyObject接口的http结果可能使用Transfer-Encoded: Chunked编码方式。
  4. CopyObject过程中,如果发生服务器端错误,http status code可能返回2XX但是复制失败,复制结果请根据http body中的json判定。

示例

  • 标准存储的请求示例

    PUT /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    Content-Type:text/plain
    x-bce-copy-source: /SourceBucket/SourceObject
    x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
    x-bce-metadata-directive: replace
    
  • 低频/冷存储的请求示例

    PUT /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    Content-Type:text/plain
    x-bce-copy-source: /SourceBucket/SourceObject
    x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
    x-bce-storage-class: STANDARD_IA
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Connection: close
    Server: BceBos
    
    {
        "lastModified":"2009-10-28T22:32:00Z",
        "ETag":"9b2cf535f27731c974343645a3985328"
    }
    

GetObject接口

接口描述

此命令用于从BOS获取某个Object。此操作需要请求者对该Object有读权限。请求者可以在Header中设置Range来指定需要获取的Object数据的范围。

请求(Request)

  • 请求语法

    GET /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Range: <Range_String>
    
  • 请求参数

  • 请求头域

名称 类型 描述 是否必需
Range String 指定Object返回的文件范围。设定 bytes=0-9,表示传送第0到第9这10个字符。默认返回全部数据。

响应(Response)

  • 响应元素

  • 响应头域

名称 类型 描述
Cache-Control String 下载Object的Cache设置,常见的可取值为privateno-cachemax-agemust-revalidate
Content-Disposition String 设置浏览器是否下载,可取值为inlineattachment; filename="download.txt"
Content-Length Long Int 返回Object的数据大小
Content-Range String 有range的情况下返回Object的数据范围
Content-Type String Object的类型及编码方式
Expires String 下载Object时的缓存失效时间
ETag String Object的HTTP协议实体标签
x-bce-meta-* String 如果有自定meta,才返回此项
x-bce-storage-class String 标准存储返回STANDARD,低频存储返回STANDARD_IA,冷存储返回COLD
x-bce-server-side-encryption String Object的服务器端加密类型,当前只支持AES256加密。

注意事项

  • GetObject通过Range参数可以支持断点续传,对于比较大的Object建议使用该功能。
  • 如果在请求头中使用Range参数;则返回消息中会包含整个文件的长度和此次返回的范围,例如:Content-Range: bytes 0-9/44,表示整个文件长度为 44,此次返回的范围为0-9。

如您想在response请求里面获得某些特定的header信息,可通过如下两种方式:

  • 在PutObject时增加header信息,则GetObject时会直接返回在response里面,请参考PutObject接口

    注意:responseContentDisposition的设置在BOS自有域名($region.bcebos.com和*.$region.bcebos.com无效)。

  • GetObject时,在queryString里面直接增加“responseXXX=YYY”,返回的header里面会包含“XXX: YYY”。例如:GET /testBucket/testObject?responseContentType= image/jpg,在这个http请求的response里面就会有“Content-Type: image/jpg”。

    具体的形式为response$header=urlencode(value),需要注意,当前$header只支持“ContentDisposition、ContentType、ContentLanguage、Expires、CacheControl、ContentEncoding”。

示例

  • 请求示例

    GET /object
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Range: bytes=0-9
    
  • 响应示例

    HTTP/1.1 206 Partial Content
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    x-bce-storage-class: STANDARD
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
    ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
    Accept-Ranges: bytes
    Content-Range: bytes 0-9/443
    Content-Type: text/plain
    Content-Length: 10
    Server: BceBos
    
    [10 bytes of object data]
    

GetObjectMeta接口

接口描述

此命令用于获取某个Object的Meta信息,但此时并不返回数据。

请求(Request)

  • 请求语法

    HEAD /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊header参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域
名称 类型 描述
Cache-Control String 下载Object的Cache设置,常见的可取值为privateno-cachemax-agemust-revalidate
Content-Disposition String 设置浏览器是否下载,可取值为inlineattachment; filename="download.txt"
Content-Length Long Int 返回Object的数据大小
Content-Range String 有range的情况下返回Object的数据范围
Content-Type String Object的类型及编码方式
Expires String 下载Object时的缓存失效时间
ETag String Object的HTTP协议实体标签
x-bce-meta-* String 如果有自定meta,才返回此项
x-bce-storage-class String 标准存储返回STANDARD,低频存储返回STANDARD_IA,冷存储返回COLD
x-bce-server-side-encryption String Object的服务器端加密类型,当前只支持AES256加密。
  • 响应元素

注意事项

示例

  • 请求示例

    HEAD /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    x-bce-storage-class: STANDARD
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
    ETag: "fba9dede5f27731c9771645a39863328"
    Content-Length: 0
    Content-Type: text/plain
    Connection: close
    Server: BceBos
    

FetchObject接口

接口描述

此接口用于从指定URL抓取资源,并将资源存储到指定的Bucket中。此操作需要请求者对该Bucket有写权限,每次只能抓取一个Object,且用户可以自定义Object的名称。

请求(Request)

  • 请求语法

    POST /<ObjectKey>?fetch HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Content-Length: 0
    Date: <Date>
    x-bce-fetch-source: <source>
    x-bce-fetch-mode: <fetch-mode>
    x-bce-storage-class: <storage-class>
    Authorization: AuthorizationString
    
  • 请求参数

  • 请求头域

    名称 类型 描述 是否必需
    x-bce-fetch-source String 抓取文件的源地址,如http://www.abc.com/img.jpg。该参数可以放到querystring里,当放到querystring时需要做UrlEncode。
    x-bce-fetch-mode String 抓取模式,支持异步抓取async和同步抓取sync两种模式。其中异步模式下BOS收到抓取任务后立刻返回成功,同步模式下BOS需要等到抓取Object完成后才会返回成功。对于数据量小或关注抓取结果实时性的建议使用同步模式,异步模式不需要等待,适用不需要实时查看抓取结果的场景,可以后续再对抓取结果进行查询。默认值为sync。 该参数可以放到querystring里。
    x-bce-storage-class String 存储类型,支持标准存储STANDARD、低频存储STANDARD_IA和冷存储COLD。默认存储为STANDARD。 该参数可以放到querystring里。
    x-bce-server-side-encryption String 服务端加密算法,当前仅支持AES256。

响应(Response)

  • 响应头域

  • 响应元素

    名称 类型 描述
    code String 返回请求成功或失败的返回码,成功返回success,错误返回错误码
    message String 返回请求成功或失败的信息,成功返回success,错误返回code对应的错误信息
    requestId String 请求ID。
    jobId String 异步模式才会返回该参数,表示请求任务的ID号,可用于后续任务状态查询。

示例

  • 请求示例(同步模式)

    POST /my-object?fetch HTTP/1.1
    Host: my-bucket.bj.bcebos.com
    Content-Length: 0
    Date: <Date>
    x-bce-fetch-source: http://www.abc.com/demo.html
    x-bce-fetch-mode: sync
    x-bce-storage-class: STANDARD
    Authorization: AuthorizationString
    
  • 响应示例(同步模式)

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Transfer-Encoding: chunked
    Date: Wed, 25 May 2016 06:34:40 GMT
    Server: BceBos
    
    {
        "code": "success",
        "message": "success",
        "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409",
    }
    
  • 请求示例(异步模式)

    POST /my-object?fetch HTTP/1.1
    Host: my-bucket.bj.bcebos.com
    Content-Length: 0
    Date: <Date>
    x-bce-fetch-source: http://www.abc.com/demo.html
    x-bce-fetch-mode: async
    x-bce-storage-class: STANDARD_IA
    Authorization: AuthorizationString
    
  • 响应示例(异步模式)

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Content-Length: 43
    Date: Wed, 25 May 2016 06:34:40 GMT
    Server: BceBos
    
    {
        "code": "success",
        "message": "success",
        "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409",
        "jobId": "b2419b1e3fd45d596ee22bdf62aaaa2f"
    }
    

AppendObject接口

接口描述

AppendObject以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object,可以对该Object追加数据;而通过PutObject上传的Object是Normal Object,不可进行数据追加写。

说明:

  • Appendable Object大小限制为0~5G
  • AppendObject接口在进行追加写时要求对该Object有写权限

请求(Request)

  • 请求语法

    首次上传AppendObject 时,使用如下方法:

    POST /<ObjectName>?append HTTP/1.1
    Host: <BucketName>.<Region>.bcebos.com 
    Date: <GMT Date> 
    Authorization: <Authorization_String>
    Content-Type: text/plain 
    Content-Length: <Content_Length>
    x-bce-storage-class: <Storage_Class>
    

    说明:

    • 如该Object不存在,则创建一个Appendable的Object。
    • 如已存在同名的Object,则上传的数据会覆盖原有的Object,无论原有Object是否为Appendable,均创建新的Appendable Object。
    • 允许创建或者覆盖一个长度为0的Object。

    如已上传了部分AppendObject,需要进行断点续传时,使用如下方法:

    POST /<ObjectName>?append&offset=<OffsetSize> HTTP/1.1   
    Host: <BucketName>.<Region>.bcebos.com 
    Date: <GMT Date> 
    Authorization: <Authorization_String>
    Content-Type: text/plain 
    Content-Length: <Content_Length>
    

    说明:

    • 如要续传的Object不存在时,会返回错误码404 NoSuchKey。
    • 如要续传的Object并不是Appendable的,则会返回403 ObjectUnappendable。
    • 值错误,则返回409 OffsetIncorrect。
  • 请求头域

    名称 类型 描述 是否必须
    Cache-Control String 浏览器cache的一种机制设置
    Content-Disposition String 指示浏览器如何显示附加的文件
    Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
    Expires String GMT时间,缓存失效时间
    x-bce-meta-* String 用户自定义的meta
    x-bce-content-sha256 String 指本次所传数据的sha256值,必须与此匹配,否则AppendObject失败
    x-bce-content-crc32 String 本次上传object增量数据的CRC值(循环冗余校验码)。
    x-bce-storage-class String 指定Object的存储类型,STANDARD_IA代表低频存储,COLD代表冷存储,不指定时默认是标准存储类型
    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-server-side-encryption String 服务端加密算法,当前仅支持AES256。
  • 请求参数

    名称 类型 描述 是否必须
    append - 代表对Appendable Object进行追加操作
    offset - 代表数据断点,即从该点后继续追加,取值为已实际上传的数据大小

响应(Response)

  • 响应头域

    名称 类型 描述 是否必须
    Content-MD5 String 当前已成功上传的整个object的MD5值
    x-bce-next-append-offset Long Int 指明下次AppendObject请求时传入的的值。如果不使用续传方式,即请求起始行没有offset,则这个值是0
    x-bce-content-crc32 String 整个object数据的CRC值(循环冗余校验码)。
    ETag String Append后整个Object的ETag值
  • 响应元素

    使用细节说明

    对于Appendable的Object:

    • 支持AppendObject。
    • 支持RenameObject。
    • 对一个已存在的Appendable的Object执行PutObject,则Appendable的Object会被覆盖变成普通Object。
    • 对一个已存在的Appendable的Object,在<OffsetSize>值正确的情况下,追加一个长度为0的内容,不会改变Object的任何状态。
    • 不建议并发操作同一个Object,如一个线程执行AppendObject,另一线程执行PutObject/CopyObjcect/DeleteObject等操作,可能会导致操作结果错误或操作失败。
    • 如果对同一个Object做多线程或者多进程的并发追加,有可能因为并发过程的不确定性,返回409 OffsetIncorrect失败。

对其他接口的影响

对于GetObjectMeta接口,当一个Object是Appendable时,返回的结果中会多如下两个字段:

名称 类型 描述 是否必须
x-bce-next-append-offset String 当Object是由AppendObject接口创建的,会返回该字段,指明下次AppendObject时请求传入的的值。如果此时Object的大小是5G,offset依然返回5G
x-bce-object-type String 当Object的类型值。当object是由AppendObject创建的,返回的值为Appendable,其他情况暂不返回

关于用户自定义的x-bce-meta-*

  • 在首次创建AppendableObject(即Http请求起始行不带offset参数)时,携带的x-bce-meta-*Header会被存储,后续追加AppendObject(即Http请求起始行携带offset参数)时的x-bce-meta-*Header则默认被忽略。
  • 由于Appendable Object支持CopyObject,因此可以使用CopyObject自我拷贝以覆盖的形式来修改x-bce-meta-*Header的值。

数据校验

  • 每次调用AppendObject的时候,如您上传MD5或者Sha256值,BOS会对该次调用上传的数据进行校验。
  • 每次数据追加结束,会返回已上传的整个Object的MD5值。

示例

  • 标准存储的请求示例一

    POST /my-object?append  HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 1134
    
    [1134 bytes of object data]
    
  • 低频/冷存储的请求示例一

    POST /my-object?append  HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 1134
    x-bce-storage-class: STANDARD_IA 
    
    [1134 bytes of object data]
    
  • 响应示例一

    HTTP/1.1 200 OK
    x-bce-request-id: c31b374e-048a-41f0-9a9a-31bc4bc57509
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    ETag: "7c935a3947e3a684333480bd6b58b7c2"
    Content-Length: 0
    Content-MD5: RJBidEhsrgCKeDjvQjrF8A==
    x-bce-next-append-offset: 1134
    Connection: close
    Server: BceBos
    
  • 标准存储的请求示例二

    POST /my-object?append&offset=1134 HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 1900
    
    [1900 bytes of object data]
    
  • 低频/冷存储的请求示例二

    POST /my-object?append&offset=1134 HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Type: text/plain
    Content-Length: 1900
    x-bce-storage-class: STANDARD_IA 
    
    [1900 bytes of object data]
    
  • 响应示例二

    HTTP/1.1 200 OK
    x-bce-request-id: 28a99102-d0a5-4252-a4ed-fa6dc801806b
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    ETag: "11257f81dce31a95f67f6e75018b77e3"
    Content-Length: 0
    Content-MD5: fJNaOUfjpoQzNIC9a1i3wg==
    x-bce-next-append-offset: 3034
    Connection: close
    Server: BceBos
    

DeleteObject接口

接口描述

此命令用于删除指定Bucket的一个Object,要求请求者对此Object有写权限。

请求(Request)

  • 请求语法

    DELETE /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊Header参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

注意事项

示例

  • 请求示例

    DELETE /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 204 No Content
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 0
    Connection: close
    Server: BceBos
    

DeleteMultipleObjects接口

该命令可以实现通过一个HTTP请求删除同一个Bucket下的多个Object。

  • 支持一次请求内最多删除1000个Object。
  • 消息体(body)不超过2M。
  • 返回的消息体中只包含删除过程中出错的Object结果;如果所有Object都删除都成功的话,则没有消息体。

请求(Request)

  • 请求语法

    POST /?delete HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <date>
    Authorization: <Authorization_String>
    Content-Length: <ContentLength>
    Content-Type: text/plain
    
    {
        "objects": [
            {
                "key": <ObjectKey1>
            },
            {
                "key": <ObjectKey2>
            }
        ]
    }
    
  • 请求头域

    无特殊Header参数

  • 请求参数

    参数名称 描述 父节点
    objects 保存要删除的Object信息的容器,里面包含一个或多个Object元素。 -
    +key 要删除的Object名称。 objects

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

    参数名称 描述 父节点
    errors 删除过程中出错的Object信息的容器,里面包含一个或多个Object元素。 -
    +key 删除出错的Object名称。 errors
    +code 错误代码。 errors
    +message 错误信息。 errors

示例

  • 请求示例

    POST /?delete HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 11434
    Content-Type: text/plain
    
    {
        "objects": [
            {
            "key": "my-object1"
            },
            {
            "key": "my-object2"
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id : 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Connection: close
    Content-Length: 1324
    Server: BceBos
    
    {
           "errors": [
            {
                "key": "my-object1",
                "code": "NoSuchKey",
                "message": "The specified key does not exist."
            },
            {
                "key": "my-object2",
                "code": "InvalidArgument",
                "message": "Invalid Argument."
            }
        ]
    }
    

GetObjectAcl接口

此命令用来获取某个Object的访问权限。

请求(Request)

  • 请求语法

    GET /<ObjectKey>?acl HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

    名称 类型 描述
    accessControlList Objcet ACL访问控制列表
    +grantee Objcet 一个被授权人
    ++id String 被授权用户名id
    +permission String 授权权限支持:FULL_CONTROL,READ

示例

  • 请求示例

    GET /ObjectKey?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2017-05-01T12:23:49Z
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Wed, 01 Mar 2017 12:25:00 GMT
    Server: BceBos
    x-bce-request-id: 236A23124128905248E5A01
    
    {
        "accessControlList":[
            {
                "grantee":[{
                    "id":"6c47a952db4444c5a097b41be3f24c94"
                }],
                "permission":["FULL_CONTROL"]
            },
            {
                "grantee":[{
                    "id":"8c47a952db4444c5a097b41be3f24c94"
                }],
                "permission":["READ"]
            }
        ]
    }
    

PutObjectAcl接口

此命令用于设置Object的访问权限。目前BOS支持两种方式设置ACL。第一种是使用Canned Acl,在PutObjectAcl的时候,通过头域的"x-bce-acl"或者"x-bce-grant-permission'来设置object访问权限,当前可设置的权限包括private和public-read,两种类型的header不可以同时在一个请求中出现。第二种方式是上传一个ACL文件,文件格式参见ACL文件格式,目前ACL文件只支持accessControlList,grantee,id,permission字段。

目前不支持在同一请求中同时设置canned acl和上传ACL文件。

请求(Request)

  • ACL文件请求语法

    PUT /<ObjectKey>?acl HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: <Date>
    Authorization: <Authorization_String>
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    
  • Canned ACL文件请求语法(设置x-bce-acl)

    PUT /<ObjectKey>?acl HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: <Date>
    Authorization: <Authorization_String>
    x-bce-acl: <Object_Acl>
    Content-Length: <Content_Length>
    Content-Type: application/json; charset=utf-8
    
  • Canned ACL文件请求语法(设置x-bce-grant-permission)

    PUT /<ObjectKey>?acl HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: <Date>
    Authorization: <Authorization_String>
    x-bce-grant-read: <Object_Grant_Read>
    Content-Length: <Content_Length>
    Content-Type: application/json; charset=utf-8
    
  • 请求头域

    名称 类型 描述 是否必需
    x-bce-acl String Object设置的ACL权限,支持:private、public-read
    x-bce-grant-read String 授权读的Object id,支持多个id,以逗号分隔
    x-bce-grant-full-control String 授权控制权限的Object id,支持多个id,以逗号分隔

    注意事项

    • 只有Bucket的拥有者和被授予FULL_CONTROL权限的用户才能设置Object的ACL权限。
    • 在上传Object时,Object权限会默认为空,如果没有设置Object的权限,即当Object权限为空时,默认以Bucket权限为准。
    • 当Object权限和Bucket权限不一致时,以Object权限为准。
  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊参数返回

  • 响应元素

示例

  • ACL文件请求示例

    PUT /ObjectKey?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2017-05-01T12:23:49Z
    Authorization: Authorization_String
    Content-Type: application/json; charset=utf-8
    Content-Length: 315
    
    {
        "accessControlList":[
        {
            "grantee":[{
                "id":" 6c47a952db4444c5a097b41be3f24c94"
            }],
            "permission":["READ"]
        }
        ]
    }
    
  • Canned ACL文件请求示例(设置x-bce-acl)

    PUT /ObjectKey?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2017-05-01T12:23:49Z
    Authorization: AuthorizationString
    x-bce-acl: public-read
    Content-Length: 0
    Content-Type: application/json; charset=utf-8
    
  • Canned ACL文件请求示例(设置x-bce-grant-permission)

    PUT /ObjectKey?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2017-05-01T12:23:49Z
    Authorization: AuthorizationString
    x-bce-grant-read:id="6c47a952db4444c5a097b41be3f24c94",id="8c47a952db4444c5a097b41be3f24c94"
    Content-Length: 0
    Content-Type: application/json; charset=utf-8
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Wed, 01 Mar 2017 12:25:00 GMT
    Content-Length: 0
    Server: BceBos
    x-bce-request-id:413e34fd-118d-4049-b992-1b1f3a68b1f5
    

DeleteObjectAcl接口

此命令用来删除某个Object的访问权限。

请求(Request)

  • 请求语法

    DELETE /<ObjectKey>?acl HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊Header参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊参数返回

  • 响应元素

    无特殊参数返回

示例

  • 请求示例

    DELETE /ObjectKey?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2017-05-01T12:23:49Z
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Wed, 01 Mar 2017 12:25:00 GMT
    Content-Length: 0
    Server: BceBos
    x-bce-request-id:413e34fd-118d-4049-b992-1b1f3a68b1f5