Bucket相关接口

GetBucketLocation接口

接口描述

获取Bucket所在的区域。

请求(Request)

  • 请求语法

    GET /?location HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: 0
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数响应

  • 响应元素

名称 类型 描述
location String Bucket所在区域

示例

  • 请求示例

    GET /?location HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 35
    Connection: close
    Server: BceBos
    
    {
        "locationConstraint": "bj"
    }
    

ListBuckets接口

接口描述

列举请求者拥有的所有bucket。

请求(Request)

  • 请求语法

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

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数响应

  • 响应元素

名称 类型 描述
owner Object Bucket owner(拥有者)信息
+id String Bucket owner的用户id
+displayName String Bucket owner的名称
buckets Object 存放多个bucket信息的容器
bucket Object 存放一个bucket信息的容器
+name String Bucket名称
+location String Bucket所在区域
+creationDate Date Bucket创建时间

注意: 如果请求中没有用户验证信息(即匿名访问),返回403 Forbidden,错误信息:AccessDenied

示例

  • JSON请求示例

    说明:一次请求最多返回100个bucket的信息。

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

    {
        "owner":{
            "id":"10eb6f5ff6ff4605bf044313e8f3ffa5",
            "displayName":"BosUser"
        },
        "buckets":[
            {
                "name":"bucket1",
                "location":"bj",
                "creationDate":"2016-04-05T10:20:35Z"
            },
            {
                "name":"bucket2",
                "location":"bj",
                "creationDate":"2016-04-05T16:41:58Z"
            }
        ]
    }
    

说明:JSON请求响应项的命名规则是首字母小写的驼峰格式。

PutBucket接口

接口描述

此命令用于创建Bucket。每一个用户只允许创建100个Bucket。创建的Bucket其权限默认为private,即Bucket Owner获得FULL_CONTROL,其他人没有任何权限。

请求(Request)

  • 请求语法

    PUT / HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    Content-Type: text/plain
    
  • 请求头域

    无特殊Header参数

  • 请求参数

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

注意事项

  • 若一个用户创建的Bucket超过100个,服务将返回400 Bad Request,错误码TooManyBuckets。
  • 若请求的Bucket已存在,无论该Bucket是否是请求者创建,都会返回409 Conflict,错误信息:BucketAlreadyExists。

示例

  • 请求示例

    PUT / 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: 0
    
  • 响应示例

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

ListObjects接口

接口描述

此命令用于获得指定Bucket的Object信息列表。

请求(Request)

  • 请求语法

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

    无特殊Header参数

  • 请求参数

字段 类型 是否必需 描述
delimiter String 分隔符; 主要用此项实现list文件夹的逻辑。如果在请求的时候指定了delimiter,BOS把匹配到的Object名称按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回; delimiter长度限制为1
marker String 从marker之后按字母序排列的第一个开始返回
maxKeys Int 最大为1000,默认值是1000,如果指定的值大于1000,按1000操作
prefix String key前缀,限定返回的object key必须以此为前缀

响应(Response)

  • 响应头域

    无特殊Header参数响应

  • 响应元素

名称 类型 描述
listObjectResult Container 保存ListObjects请求的容器
commonPrefixes - 仅当指定delimiter,才会返回此项
+prefix String 匹配以prefix开始到第一次出现Delimiter字符之间的object作为一组元素返回
+contents Container 返回的一个object的容器
++key String Object名称
++lastModified Date 此Object最后一次被修改的时间
++eTag String Object的HTTP协议实体标签
++size Int Object的内容的大小(字节数)
++storageClass String Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,标准存储返回STANDARD
++owner Container Object上传者的用户信息
+++id String Object上传者的用户id
+++displayName String Object上传者的名称
+delimiter String 查询的结束符
+isTruncated Bool 指明是否所有查询都返回了;false-本次已经返回所有结果,true-本次还没有返回所有结果
+maxKeys Int 请求返回的最大数目
+marker String 本次查询的起点
+name String Bucket名称
+nextMarker String 当IsTruncated true时,才返回此项,作为下次查询marker的值
+prefix String 查询的前缀

注意事项

Delimiter可以用来实现文件夹逻辑:

  1. 如果把prefix设为某个文件夹名,就可以罗列以此prefix开头的文件,即该文件夹下递归的所有的文件和子文件夹内的文件。
  2. 如果再把delimiter设置为 / 时,返回值就只罗列该文件夹下的文件,该文件夹下的子文件夹名返回在CommonPrefixes部分,子文件夹下递归的文件不被显示。 如一个bucket下存在三个object:fun/test.jpg,fun/movie/001.avi,fun/movie/007.avi。 若设定prefix为“fun/”,则返回三个object;如果增加设定delimiter为“/”,则返回文件“fun/test.jpg”和前缀“fun/movie/”。

示例

  • 请求示例(JSON)1

    GET / HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例(JSON)1

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Server: BceBos
    
    {
        "name":"bucket",
        "prefix":"",
        "delimiter":"/",
        "marker":"",
        "maxKeys":1000,
        "isTruncated":false,
        "contents":[
            {
               "key":"my-image.jpg",
               "lastModified":"2009-10-12T17:50:30Z",
               "eTag":"fba9dede5f27731c9771645a39863328",
               "size":434234,
               "storageClass":"STANDARD",
               "owner":{
                   "id":"168bf6fd8fa74d9789f35a283a1f15e2",
                   "displayName":"mtd"
              }
            }
        ],
        "commonPrefixes":[
             {"prefix":"photos/"},
             {"prefix":"mtd/"}
        ]
    }
    
  • 请求示例(JSON)2

    GET /?delimiter=/  HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例(JSON)2

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Server: BceBos
    
    {
        "name":"bucket",
        "prefix":"" ,
        "delimiter":"/",
        "marker":"",
        "maxKeys":1000,
        "isTruncated":false,
        "contents":{
            "key":"my-image.jpg",
            "lastModified":"2009-10-12T17:50:30Z",
            "eTag":"fba9dede5f27731c9771645a39863328",
            "size":434234,
            "storageClass":"STANDARD",
            "owner":{
                "id":"168bf6fd8fa74d9789f35a283a1f15e2",
                "displayName":"mtd"
            }
        },
        "commonPrefixes":[
             {"prefix":"photos/"},
             {"prefix":"mtd/"}
       ]
    }
    

HeadBucket接口

接口描述

此命令用于查看Bucket是否存在和请求者是否有权限访问这个Bucket。当请求返还200 OK时,说明Bucket存在且请求者有权限访问。

请求(Request)

  • 请求语法

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

    无特殊Header参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

示例

  • 请求示例

    HEAD / 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
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Connection: close
    Server: BceBos
    

DeleteBucket接口

接口描述

此命令用于删除一个Bucket。在删除前需要保证此Bucket下的所有Object和未完成的三步上传Part已经已被删除,否则会删除失败。

说明:删除Bucket之前确认该Bucket没有开通跨区域复制,不是跨区域复制规则中的源Bucket或目标Bucket,否则不能删除。

请求(Request)

  • 请求语法

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

    无特殊Header参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

注意事项

  1. 只有Bucket的拥有者才能删除对应的Bucket,否则返回403 Forbidden,对应错误信息:AccessDenied。
  2. 为了确保用户数据安全,防止误删除,BOS不允许用户删除一个非空的Bucket。如果用户试图删除一个存在Object的Bucket,返回409 Conflict错误,错误码:BucketNotEmpty。

示例

  • 请求示例

    DELETE / 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
    Connection: close
    Server: BceBos
    

PutBucketAcl接口

接口描述

此命令用于设置Bucket的访问权限。目前BOS支持两种方式设置ACL。第一种是使用CannedAcl,在PutBucketAcl的时候,通过头域的“x-bce-acl"来设置,当前可设置的权限包括:private, public-read, public-read-write(大小写敏感)。第二种方式是上传一个ACL文件,文件格式参见ACL文件格式

注意事项BOS系统不支持在同一请求中,同时设置“x-bce-acl”和上传ACL文件。

请求(Request)

  • 请求语法

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

    无特殊参数

  • 请求头域

名称 类型 描述 是否必需
x-bce-acl String Bucket设置的ACL权限,支持:private、public-read、public-read-write

响应(Response)

  • 响应头域

    无特殊Header参数返回

  • 响应元素

注意事项

  1. 只有Bucket的拥有者和被授予FULL_CONTROL权限的用户才能设置Bucket的ACL权限。
  2. 在创建Bucket时,Bucket权限会默认设置为private。

示例

  • 使用CannedAcl的请求示例

    PUT /?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2016-04-06T08:23:49Z 
    Authorization: AuthorizationString
    x-bce-acl: public-read
    Content-Type: application/json; charset=utf-8
    Content-length: 0
    
  • 上传ACL文件的示例

    PUT /?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2016-04-06T08:23:49Z 
    Content-Length :1324
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "accessControlList":[
             { 
                   "grantee":[{
                      "id":"168bf6fd8fa74d9789f35a283a1f15e2"
                    }],
                    "permission":["READ"]
              }
         ]
    }
    
  • 响应示例

    HTTPS/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Content-Length: 0
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Server: BceBos
    

GetBucketAcl接口

接口描述

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

请求(Request)

  • 请求语法

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

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素(以JSON请求为例)
名称 类型 描述
accessControlList Objcet 保存acl的容器
+grantee Objcet 一个被授权人
++id String 被授权用户名id
+permission String 授权权限支持:FULL_CONTROL,READ,WRITE、LIST、GetObject
owner Objcet Bucket拥有者信息
+id String Owner用户id
  • 响应头域

注意事项

示例

  • 请求示例

    GET /?acl HTTP/1.1
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2016-04-06T08:23:49Z 
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-acl: public-read
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Server: BceBos
    
    {
        "accessControlList":[
             {
                 "grantee":[{
                     "id":"168bf6fd8fa74d9789f35a283a1f15e2"
                  }],
                  "permission":["FULL_CONTROL"]
             },
             { 
                   "grantee":[{
                      "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                    }],
                    "permission":["READ"]
              }
         ],
        "owner":{
             "id":"16df583fe6824d73a5f858f06de0af03"
        }
    }
    

PutBucketReplication接口

接口描述

此命令用来创建跨区域同步。该接口在status为disable时,可以重复调用;但如果成功创建一个跨区域同步即put一个status为enable的Replication后,如果需要修改,则只能先调用DeleteBucketReplication接口后再调用该接口进行put。

说明:

  • 用户必须是源Bucket的owner且拥有FULL_CONTROL权限,且是目标Bucket的owner。
  • 目的Bucket和源Bucket必须存在。
  • 目的Bucket和源Bucket必须为不同region下的Bucket。
  • 目的Bucket和源Bucket都必须没有开通过replication,且没有成为别的跨区域复制规则中的目的Bucket。
  • 整个配置的大小不能超过128k。

请求(Request)

  • 请求语法

    PUT /?replication HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: request-body length
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "status":"enabled",
        "resource":[
            "bucket/abc"
            "bucket/cd*",
            ...
            ],
        "destination":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateHistory":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateDeletes":"enabled",
        "id":"sample-bucket-replication-config"
    }
    
  • 请求头域

    无特殊参数

  • 请求参数

    参数 是否必须 描述
    id replication规则名
    status 是否生效
    resource replication生效前缀,resource的配置形式为{$bucket_name/<生效的对象前缀>},必须要以“$bucket_name”+"/"开头
    destination 复制的目的端配置
    +bucket 目的Bucket name
    +storageClass 目的Object的存储类型。如果保持和源Bucket的存储类型一致,则该参数不需要配置;如果需要单独指定存储类型可以为"STANDARD","STANDARD_IA","COLD"
    replicateHistory 历史文件复制,有该项则认为是开启。replicationHistory中的Bucket name需要和上面destination中的Bucket name保持一致
    +bucket 目的Bucket name
    +storageClass 目的Object的存储类型。如果保持和源Bucket的存储类型一致,则该参数不需要配置;如果需要单独指定存储类型可以为"STANDARD","STANDARD_IA","COLD"
    replicateDeletes 是否开启删除同步,可以为"enabled","disabled"

响应(Response)

  • 响应元素

    无特殊参数

  • 响应头域

    无特殊参数

示例

  • 请求示例

    PUT /?replication HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: xxx
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "status":"enabled",
        "resource":[
                    "bucket/abc",
                    "bucket/cd*",
                    ...
                   ],
        "destination":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateHistory":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateDeletes":"enabled",
        "id":"sample-bucket-replication-config"
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: xxxx-xxxx-xxxx
    Date: Wed, 12 May 2017 17:50:00 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: BceBos
    

GetBucketReplication接口

接口描述

此命令用来获取跨区域复制的Bucket信息,包括源Bucket名称、目的Bucket名称、存储类型、是否进行历史复制,数据同步策略等。

请求(Request)

  • 请求语法

    GET /?replication HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <GMT Date>
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    参数 描述
    id replication规则名
    status 是否生效
    resource replication生效前缀
    destination 复制的目的端配置
    +bucket 目的Bucket name
    +storageClass 目的Object的存储类型。如果保持和源Bucket的存储类型一致,则该参数为空;"STANDARD"表示标准存储类型,"STANDARD_IA"表示低频存储类型,"COLD"表示冷存储类型。
    replicateHistory 历史文件复制,有该项则认为是开启
    +bucket 目的Bucket name
    +storageClass 目的Object的存储类型,默认为"REMAIN",可以为"STANDARD","STANDARD_IA","COLD"
    replicateDeletes 是否开启删除同步,可以为"enabled","disabled"
  • 响应头域

    无特殊参数

示例

  • 请求示例

    GET /?replication HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Thu, 15 May 2017 00:17:23 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2017 00:17:23 GMT
    Server: BceBos
    x-bce-request-id: xxxx-xxxxx-xxxx
    Connection: keep-alive
    Content-Length: xxx
    
    {
        "status":"enabled",
        "resource":[
                    "bucket/abc",
                    "bucket/cd*",
                    ...
                   ],
        "destination":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateHistory":
            {
                "bucket":"bucket-name",
                "storageClass":"COLD"
            },
        "replicateDeletes":"enabled",
        "id":"sample-bucket-replication-config",
    }
    

DeleteBucketReplication接口

接口描述

此命令用来删除跨区域同步复制配置。

请求(Request)

  • 请求语法

    DELETE /?replication HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: GMT Date
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    无特殊参数

  • 响应头域

    无特殊参数

示例

  • 请求示例

    DELETE /?replication HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Thu, 15 May 2017 00:17:23 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 204 No Content
    Date: Thu, 15 May 2017 00:17:23 GMT
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Connection: keep-alive
    Server: BceBos
    

GetBucketReplicationProgress接口

接口描述

此命令用来获取Bucket跨区域复制的进程状态。

请求(Request)

  • 请求语法

    Get /?replicationProgress HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: GMT Date
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    参数 描述
    status 是否开启了跨区域同步功能,可选值为enabled和disabled
    historyReplicationPercent 历史文件跨区域同步已完成百分比
    latestReplicationTime UNIX 时间戳,最新的跨区域复制的时间
  • 响应头域

    无特殊参数

示例

  • 请求示例

    Get /?replicationProgress HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Thu, 15 May 2017 00:17:23 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2017 00:17:23 GMT
    Server: BceBos
    x-bce-request-id: xxxx-xxxxx-xxxx
    Connection: keep-alive
    Content-Length: xxx
    
    {
        "status":"enabled",
        "historyReplicationPercent":5,
        "latestReplicationTime":1504448315
    }
    

PutBucketLogging接口

接口描述

此命令用来开启Bucket的访问日志并指定存放日志的Bucket和访问日志的文件前缀。访问日志的规则请参见日志命名规则日志格式

请求(Request)

  • 请求语法

    PUT /?logging HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    
    {
        "targetBucket": "TargetBucketName",
        "targetPrefix": "TargetPrefixName"
    }
    
  • 请求头域

    无特殊参数

  • 请求参数

    名称 描述 类型 是否必须
    targetBucket 指定存放访问日志的Bucket 字符串
    targetPrefix 指定最终被保存的访问日志文件前缀 字符串 否(建议填写,用以区分访问日志)

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

注意事项

  • 用户必须是源Bucket的owner且拥有FULL_CONTROL权限,且是目标Bucket的owner。
  • 源Bucket和目标Bucket必须同时存在。
  • 源Bucket和目标Bucket必须属于同一个Region。
  • 如果HTTP Body中Json不合法,BOS会返回CODE_MALFORMED_JSON错误。
  • 如果HTTP Body中Json有无效字段,BOS会返回CODE_INAPPROPRIATE_JSON错误。
  • 用户可将不同的源Bucket的Logging都保存在同一个目标Bucket内,建议指定不同的 “targetPrefix”便于区分。
  • 如果源Bucket开通了Logging功能,源Bucket被删除的同时,相应的Logging信息也将被删除。
  • 如果Logging的目标Bucket被删除,则源Bucket的Logging功能会被自动关闭。
  • 如果需要修改目标Bucket等信息,可再发送一个PutBucketLogging请求,请求中包含需要修改的信息。
  • “targetPrefix”表示存储访问日志记录的Object名字前缀,可以为空。如果不为空时,“targetPrefix”可以包含字母、数字、中划线、下划线、斜杠,且必须以字母开头,长度不大于32位。
  • 重复请求返回结果相同。

示例

  • 请求示例

    PUT /?logging HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Tue, 17 May 2016 08:36:52 GMT
    Authorization: AuthorizationString
    Content-Length: 55
    
    {
        "targetBucket": "dscbucket",
        "targetPrefix": "mylog/"
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Content-Length: 0
    Server: BceBos
    

GetBucketLogging接口

接口描述

此命令用来获取某个Bucket的访问日志配置情况。

请求(Request)

  • 请求语法

    Get /?logging HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: 0
    
  • 请求头域

    无特殊参数

    • 请求参数

      无特殊参数

响应(Response)

  • 响应元素
名称 描述
status Bucket的访问日志功能的开启状态,取值为enableddisabledenabled代表已开启,disabled代表未开启。
targetBucket 指定存放访问日志的Bucket,如果未开启Logging功能,响应中无该字段。
targetPrefix 指定最终被保存的访问日志文件前缀,如果未开启Logging功能,响应中无该字段。
  • 响应头域

    无特殊头域

注意事项

  • 如果请求的源Bucket不存在,返回404错误,错误码为NoSuchBucket。
  • 请求者只有是源Bucket的owner且拥有FULL_CONTROL权限才允许查看,否则返回403错误,错误码为AccessDenied。

示例

  • 请求示例

    Get /?logging HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Tue, 17 May 2016 08:36:52 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    
  • 响应示例(已设置Log规则)

    HTTP/1.1 200 OK
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Content-Length: 71
    Server: BceBos
    
    {
        "status": "enabled",
        "targetBucket": "dscbucket",
        "targetPrefix": "mylog-"
    }
    
  • 响应示例(未设置Log规则)

    HTTP/1.1 200 OK
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Content-Length: 21
    Server: BceBos
    
    {
        "status": "disabled"
    }
    

DeleteBucketLogging接口

接口描述

此命令用来关闭Bucket访问日志记录功能。

请求(Request)

  • 请求语法

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

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

注意事项

  • 如果请求的源Bucket不存在,返回404错误,错误码为NoSuchBucket。
  • 请求者只有是源Bucket的owner且拥有FULL_CONTROL权限,才能关闭Bucket访问日志记录功能。否则,BOS返回403错误,错误码为AccessDenied。
  • 如果请求的源Bucket没有开通Logging功能,依然返回HTTP状态码204。

示例

  • 请求示例

    DELETE /?logging HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Tue, 17 May 2016 08:36:52 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 204 No Content
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Connection: close
    Server: BceBos
    

PutBucketLifecycle接口

接口描述

此接口用来创建生命周期管理规则。

说明:只有bucket的owner且拥有FULL_CONTROL权限才能够进行此请求。

请求(Request)

  • 请求语法

    PUT /?lifecycle HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: request-body length
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "rule": [
            {
                "id": "rule-id", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "2016-09-07T00:00:00Z"
                    }
                }, 
                "action": {
                    "name": "DeleteObject"
                }
            },
    }
    
  • 请求头域

    无特殊参数

  • 请求参数

    规则项 描述 是否必填 备注
    id 规则的标识符。 必填 同一个bucket内规则id必须唯一,不能重复。如果用户不填系统会自动帮用户生成一个。
    status 规则的状态。 必填 取值为enableddisabled,当规则处于disabled时规则不生效。
    resource 规则对哪些资源生效。 必填 举例:对samplebucket里以prefix/为前缀的Object生效:samplebucket/prefix/*;对samplebucket里所有Object生效:samplebucket/*
    condition 规则依赖的条件。 必填 目前只支持time形式。
    +time 时间限制条件。 必填 通过定义的dateGreaterThan实现。
    ++dateGreaterThan 描述时间关系。 必填 支持绝对时间date和相对时间days。绝对时间date格式为yyyy-mm-ddThh:mm:ssZ,eg. 2016-09-07T00:00:00Z。绝对时间为UTC时间, 必须以00:00:00(UTC 0点)结尾;相对时间days的描述遵循ISO8601, 支持的最小时间粒度为天,如: $(lastModified)+P7D表示的时间为object的last-modified之后7天。
    action 对resource执行的操作动作。 必填 -
    +name 执行的操作名称。 必填 取值为TransitionDeleteObjectAbortMultipartUpload
    +storageClass Object的存储类型 可选 action为Transition时可以设定,取值为STANDARD_IACOLD,表示从原存储类型转为低频存储或冷存储。

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

示例

  • 请求示例

    PUT /?lifecycle HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: 2016-08-16T08:23:49Z
    Content-Length :1324
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "rule": [
            {
                "id": "sample-rule-delete-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "2016-09-07T00:00:00Z"
                    }
                }, 
                "action": {
                    "name": "DeleteObject"
                }
            },
            {
                "id": "sample-rule-transition-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "$(lastModified)+P7D"
                    }
                }, 
                "action": {
                    "name": "Transition",
                    "storageClass": "STANDARD_IA"
                }
            },
            {
                "id": "sample-rule-abort-multiupload-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "$(lastModified)+P7D"
                    }
                }, 
                "action": {
                    "name": "AbortMultipartUpload"
                }
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 0A49CE4060975EAC
    Date: Wed, 12 Oct 2016 17:50:00 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: BceBos
    

GetBucketLifecycle接口

接口描述

此接口用于获取定义的生命周期管理规则详细信息。

请求(Request)

  • 请求语法

    GET /?lifecycle HTTP/1.1
    Host: bucketname.bj.bcebos.com
    Date: date
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

注意事项

  • 如果请求的源Bucket不存在,返回404错误,错误码为NoSuchBucket。
  • 如果请求的源Bucket没有配置lifecycle,返回404错误,错误码为NoLifecycleConfiguration。

示例

  • 请求示例

    GET /?lifecycle HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Thu, 15 Sep 2016 00:16:26 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Thu, 15 Sep 2016 00:17:23 GMT
    Server: BceBos
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Connection: keep-alive
    Content-Length: 358
    
    {
        "rule": [
            {
                "id": "sample-rule-delete-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "2016-09-07T00:00:00Z"
                    }
                }, 
                "action": {
                    "name": "DeleteObject"
                }
            },
            {
                "id": "sample-rule-transition-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "$(lastModified)+P7D"
                    }
                }, 
                "action": {
                    "name": "Transition"
                    "storageClass": "STANDARD_IA"
                }
            },
            {
                "id": "sample-rule-abort-multiupload-prefix", 
                "status": "enabled", 
                "resource": [
                    "bucket/prefix/*"
                ], 
                "condition": {
                    "time": {
                        "dateGreaterThan": "$(lastModified)+P7D"
                    }
                }, 
                "action": {
                    "name": "AbortMultipartUpload"
                }
            }
        ]
    }
    

DeleteBucketLifecycle接口

接口描述

此命令用来删除定义的生命周期管理规则。

请求(Request)

  • 请求语法

    DELETE /?lifecycle HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: GMT Date
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

示例

  • 请求示例

    DELETE /?lifecycle HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Tue, 17 Sep 2016 08:36:52 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 204 No Content
    Date: Wed, 14 Sep 2016 05:37:16 GMT
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Connection: keep-alive
    Server: BceBos
    

PutBucketStorageclass接口

接口描述

此命令用来设置Bucket的默认存储类型。

如果用户使用API、CLI或者SDK上传的Object未指定存储类型,则继承Bucket的默认存储类型。如果上传Object指定的存储类型和Bucket默认存储类型不一致时,以Object的存储类型为准。存储类型包含标准存储、低频存储和冷存储三种,具体使用场景和性能请参见分级存储

请求(Request)

  • 请求语法

    PUT /?storageClass HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: request-body-length
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

名称 类型 描述 是否必须
storageClass String 指定Bucket的默认存储类型,STANDRAD代表标准存储,STANDARD_IA代表低频存储,COLD代表冷存储。

响应(Response)

  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

示例

  • 请求示例

    PUT /?storageClass HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: 38
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "storageClass": "STANDARD_IA"
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db4b34d-653d-4d9a-b49b-3049ca786409
    Date: Wed, 31 May 2017 08:34:40 GMT
    Connection: keep-alive
    Server: BceBos
    

GetBucketStorageClass接口

接口描述

此命令用来获取Bucket的默认存储类型。

请求(Request)

  • 请求语法

    GET /?storageClass HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
  • 请求头域

    无特殊参数

  • 请求参数

    无特殊参数

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

名称 类型 描述
storageClass String 存储类型。标准存储返回STANDARD,低频存储返回STANDARD_IA,冷存储返回COLD。

示例

  • 请求示例

    GET /?storageClass HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: Wed, 31 May 2017 09:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 2eb2b34d-654d-fd8a-b49b-3049ca786409
    Date: Wed, 31 May 2017 09:34:40 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 31
    Connection: keep-alive
    Server: BceBos
    
    {
        "storageClass": "COLD"
    }
    

PutBucketEncryption接口

接口描述

开启指定Bucket的加密开关。

请求(Request)

  • 请求语法

    PUT /?encryption HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    
    {
        "encryptionAlgorithm":"AES256"
    }
    
  • 请求参数

  • 请求头域

    名称 类型 描述 是否必须
    encryptionAlgorithm String 指定Bucket的服务器端加密类型,当前只支持AES256加密。

响应(Response)

  • 响应元素

  • 响应头域

示例

  • 请求示例

    PUT /?encryption HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 11434
    
    {
        "encryptionAlgorithm":"AES256"
    }
    
  • 返回示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 11434
    Server: BceBos
    

GetBucketEncryption接口

接口描述

获取Bucket服务端加密是否打开。

请求(Request)

  • 请求语法

    Get /?encryption HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: 0
    
  • 请求参数

  • 请求头域

响应(Response)

  • 响应元素

    名称 类型 描述
    encryptionAlgorithm String Bucket的服务器端加密类型,当前只支持AES256加密。
  • 响应头域

示例

  • 请求示例

    Get /?encryption HTTP/1.1
    Host: bucket.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: Authorizationstring
    Content-Length: 0
    
  • 返回示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 11434
    Server: BceBos
    x-bce-server-side-encryption: AES256
    
    {
        "encryptionAlgorithm":"AES256"
    }
    

DeleteBucketEncryption接口

接口描述

关闭服务端加密功能。

请求(Request)

  • 请求语法

    DELETE /?encryption HTTP/1.1
    Host: <BucketName>.bj.bcebos.com                            
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求参数

  • 请求头域

响应(Response)

  • 响应元素

  • 响应头域

示例

  • 请求示例

    DELETE /?encryption HTTP/1.1
    Host: bucket.bj.bcebos.com                            
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: Authorizationstring
    
  • 返回示例

    HTTP/1.1 204 No Content
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Connection: close
    Server: BceBos
    

PutBucketStaticWebsite

用户必须对bucket 具有 full control 权限。

  • 接口描述

    用于设置静态网站托管。

  • 请求头域

    无特殊参数

  • 请求参数

    名称 描述 类型 是否必须
    index Index文件名称 string
    notFound 404文件名称 string
  • PutBucketStaticWebsite 示例

    PUT /?website HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Tue, 17 May 2016 08:36:52 GMT
    Authorization: AuthorizationString
    Content-Length: 65
    
    {
        "index": "index.html",
        "notFound": "404.html"
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Date: Tue, 17 May 2016 08:36:52 GMT
    Content-Length: 0
    Server: BceBos
    
  • 返回代码

    结果 http status error code 说明
    成功 200 - -
    Json格式错误 400 MalformedJSON -
    Json内容不正确 400 InappropriateJSON 比如index和404文件都为空
    Index或者404文件名过长 400 EntityTooLarge index或者404文件名都不能超过1024个字节
    不允许的index或者404文件名 400 InvalidStaticWebSiteFormat 比如文件格式不允许,或者index与404文件同名。
    静态网站托管功能被禁止 501 StaticWebSiteIsDisable 即BOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线
    其他错误, 遵循bos之前的错误代码 - - -

GetBucketStaticWebsite

  • 接口描述

    获取bucket的静态网站托管信息

  • 请求头域

    无特殊参数

  • 请求语法

    Get /?website HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: 0
    
  • 响应元素

    名称 描述
    index Index文件名称
    notFound 404文件名称
  • 响应示例

  1. 当配置存在:

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2017 00:17:23 GMT
    Server: BceBos
    x-bce-request-id: xxxx-xxxxx-xxxx
    Connection: keep-alive
    Content-Length: xxx
    
    {
        "index": "index.html",
        "notFound": "404.html"
    }
    
  2. 当未开启静态网站托管

    返回http status 为 404, 错误Code为 NoSuchBucketStaticWebSiteConfig

  • 返回代码

    结果 http status error code 说明
    成功 200 - -
    没有开启静态托管 404 NoSuchBucketStaticWebSiteConfig -
    静态网站托管功能被禁止 501 StaticWebSiteIsDisable 即BOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线
    其他错误, 遵循bos之前的错误代码 - - -

DeleteBucketStaticWebsite

用户必须对bucket 具有 full control 权限。

  • 接口描述

    删除bucket设置的静态网站托管信息,并关闭此bucket的静态网站托管。

  • 请求头域

    无特殊参数

  • 请求语法

    DELETE /?website HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 响应元素

    无特殊元素

  • 响应头域

    无特殊头域

  • 响应示例

    HTTP/1.1 204 No Content
    Date: Wed, 14 Sep 2016 05:37:16 GMT
    x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
    Connection: keep-alive
    Server: BceBos
    
  • 返回代码

    结果 http status error code 说明
    成功 204 - -
    静态网站托管功能被禁止 501 StaticWebSiteIsDisable 即BOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线
    其他错误, 遵循bos之前的错误代码 - - -

PutBucketTrash接口

接口描述

开通Bucket Trash功能,用户必须是源Bucket的owner且拥有FULL_CONTROL权限,且是目标Bucket的owner。

请求

  • 请求语法

    PUT /?trash HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: application/json
    Content-Length: <Content_Length>
    
  • 请求头域

    无特殊Header参数

  • 请求元素

    名称 描述
    trashDir 回收站的路径名称,有长度限制。可选,不填默认名为.trash

    说明:若已开通trash功能,会覆盖trash目录名。

响应

  • 响应头域

  • 响应元素

    结果 http status error code 说明
    Json格式错误 400 MalformedJSON -
    trash目录名过长 400 EntityTooLarge 不超过1024字节
    trash目录包含非法字符 400 InvalidTrashDirectoryName 只能包含字母,数字,中文,下划 )和短横线(-),小数点(.)
    bucket不存在 404 NoSuchBucket -
    没有权限 403 AccessDenied 只有bucket owner可以操作

示例

  • 请求示例

    PUT /?trash HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Content-Length: request-body-length
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    {
    "trashDir": "trashDirName"
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db4b34d-653d-4d9a-b49b-3049ca786409
    Date: Wed, 31 May 2017 08:34:40 GMT
    Server: BceBos
    

GetBucketTrash接口

接口描述

获取Bucket Trash开通状态,返回当前trash目录名,默认为.trash。用户必须是源Bucket的owner且拥有FULL_CONTROL权限,且是目标Bucket的owner。

请求

  • 请求语法

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

    无特殊Header参数

  • 请求元素

响应

  • 响应头域

  • 响应元素

    名称 描述
    trashDir 回收站的路径名称,有长度限制。可选,不填默认名为.trash

    返回结果解释如下:

    结果 http status error code 说明
    成功 200 - -
    bucket不存在 404 NoSuchBucket -
    trash功能未开通 404 NoSuchTrashDirectory -
    没有权限 403 AccessDenied 只有bucket owner可以操作

示例

  • 请求示例

    GET /?trash HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db4b34d-653d-4d9a-b49b-3049ca786409
    Date: Wed, 31 May 2017 08:34:40 GMT
    Content-Length: request-body-length
    Content-Type: application/json; charset=utf-8
    Server: BceBos
    Connection: keep-alive
    {
    "trashDir": ".trash/"
    }
    

DeleteBucketTrash接口

接口描述

关闭trash功能,用户必须是源Bucket的owner且拥有FULL_CONTROL权限,且是目标Bucket的owner。

请求

  • 请求语法

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

    无特殊Header参数

  • 请求元素

响应

  • 响应头域

  • 响应元素

    名称 描述
    trashDir 回收站的路径名称,有长度限制。可选,不填默认名为.trash

    返回结果解释如下:

    结果 http status error code 说明
    成功 204 - -
    bucket不存在 404 NoSuchBucket -
    没有权限 403 AccessDenied 只有bucket owner可以操作

    说明:即使未开通trash功能也返回204,满足delete幂等

示例

  • 请求示例

    DELETE /?trash HTTP/1.1
    Host: bucket.bj.bcebos.com
    x-bce-date: date
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db4b34d-653d-4d9a-b49b-3049ca786409
    Date: Wed, 31 May 2017 08:34:40 GMT
    Server: BceBos
    Connection: keep-alive
    

PutBucketCors接口

接口描述

PutBucketCors操作用来在指定的Bucket上设定一个跨域资源共享(CORS)的规则,如果原规则存在则覆盖原规则。

权限说明

只有Bucket的所有者和被授予FULL_CONTROL权限的用户才能设置Bucket的CORS。没有权限时,返回403 Forbidden错误,错误码:AccessDenied。

请求

  • 请求语法

    PUT /?cors HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    x-bce-date: date
    Content-Length: content_length
    Content-Type: application/json; charset=utf-8
    Authorization: <Authorization_String>
    
    {
        Cors json file …
    }
    
  • 请求参数

  • 请求头域

    无特殊Header参数

  • 请求元素

    Cors json文件包含如下字段:

    名称 描述 是否必需 父节点
    corsConfiguration Bucket的CORS规则容器。每个Bucket
    最多允许有100条规则。
    如果有多条配置,执行顺序为从上到下。
    allowedOrigins 存储允许的跨域请求的来源的容器。 corsConfiguration
    allowedOrigin 指定允许的跨域请求的来源,允许使用
    最多一个*通配符。
    如果指定为*则表示允许所有的来源的
    跨域请求。特别的还支持*作为后缀来
    表示某一类网站比如abc*,则表示支持
    abc开头的网站。
    注意:allowedOrigin匹配时大小写敏感。
    类型:字符串
    allowedOrigins
    allowedMethods 存储允许的跨域请求方法的容器。 corsConfiguration
    allowedMethod 指定允许的跨域请求的方法,不支持通配
    *,大小写敏感。
    类型:枚举,取值有“GET,PUT,DELETE,
    POST,HEAD”。
    allowedMethods
    allowedHeaders 存储允许的allowedHeaders容器。控制
    在OPTIONS预取指令中Access-Control-
    Request-Headers头中指定的header是
    否允许。
    corsConfiguration
    allowedHeader 控制在OPTIONS预取指令中Access-Control
    -Request-Headers头中指定的header是否允许。
    在Access-Control-Request-Headers中指定的每
    个header都必须在allowedHeader中有一条对应
    的项。每一个header允许使用最多一个*通配符,
    不区分大小写。
    类型:字符串。
    allowedHeaders
    allowedExposeHeaders 存储允许用户从应用程序中访问的响应头的容器。 corsConfiguration
    allowedExposeHeader 指定允许用户从应用程序中访问的响应头(例如一个
    Javascript的XMLHttpRequest对象)。不允许使用
    *通配符。
    OPTIONS请求中将根据此定义设置Access-Control
    -Expose-Headers。
    类型:字符串。
    allowedExposeHeaders
    maxAgeSeconds 指定浏览器对特定资源的预取(OPTIONS)请求返
    回结果的缓存时间,在缓存时间内请求方不必发送重
    复的preflight
    请求,单位为秒。
    类型:Int64。
    corsConfiguration

响应

  • 响应头域

  • 响应元素

    注意事项

    • 通过此接口设置CORS规则之前,Bucket的CORS权限设置为不允许跨域。
    • 每个Bucket最多只允许有一个规则文件,因此新上传的规则文件会覆盖原有的。
    • CORS规则文件大小限制为20KB,因此请求时大于20KB会返回超出大小错误(400 Bad Request: EntityTooLarge)。

示例

  • 请求示例

    PUT /?cors HTTP/1.1 
    Host: BucketName.bj.bcebos.com
    x-bce-date: 2016-04-06T08:23:49Z 
    Content-Length: 1024
    Content-Type: application/json; charset=utf-8
    Authorization: AuthorizationString
    
    {
        "corsConfiguration": [
                {
                "allowedOrigins": [
                    "http://www.example.com",
                    "www.example2.com"
                ],
                "allowedMethods": [
                        "GET",
                        "HEAD",
                        "DELETE"
                    ],
                 "allowedHeaders": [
                        "Authorization",
                        "x-bce-test",
                        "x-bce-test2"
                    ],
                "allowedExposeHeaders": [
                     "user-custom-expose-header"
                ],
                "maxAgeSeconds": 3600
            },
            {    
                "allowedOrigins": [
                    "http://www.baidu.com"
                ],
                "allowedMethods": [
                        "GET",
                        "HEAD",
                        "DELETE"
                    ],
                "allowedHeaders": [
                        "*",
                ],
                "allowedExposeHeaders": [
                     "user-custom-expose-header"
                ],
                "maxAgeSeconds": 1800
            }
        ]
    }
    
  • 响应示例

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

GetBucketCors接口

接口描述

GetBucketCors操作用于获取指定的Bucket当前的CORS规则。

权限说明

只有Bucket的所有者和被授予FULL_CONTROL权限的用户才能设置Bucket的CORS。没有权限时,返回403 Forbidden错误,错误码: AccessDenied。

请求

  • 请求语法

    GET /?cors HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: date
    Authorization: <Authorization_String>
    
  • 请求参数

  • 请求头域

    无特殊Header参数

  • 请求元素

响应

  • 响应头域

  • 响应元素

    名称 描述 是否必需 父节点
    corsConfiguration Bucket的CORS规则容器。每个Bucket最多允许有100条规则。如果有多条配置,执行顺序为从上到下。
    allowedOrigins 存储允许的跨域请求的来源的容器。 corsConfiguration
    allowedOrigin 指定允许的跨域请求的来源,允许使用最多一个*通配符。 如果指定为*则表示允许所有的来源的跨域请求。特别的还支持*作为后缀来表示某一类网站比如abc*,则表示支持abc开头的网站。注意:allowedOrigin匹配时大小写敏感。类型:字符串 allowedOrigins
    allowedMethods 存储允许的跨域请求方法的容器。 corsConfiguration
    allowedMethod 指定允许的跨域请求的方法,不支持通配符*,大小写敏感。类型:枚举,取值有“GET,PUT,DELETE,POST,HEAD”。 allowedMethods
    allowedHeaders 存储允许的allowedHeaders容器。控制在OPTIONS预取指令中Access-Control-Request-Headers头中指定的header是否允许。 corsConfiguration
    allowedHeader 控制在OPTIONS预取指令中Access-Control-Request-Headers头中指定的header是否允许。在Access-Control-Request-Headers中指定的每个header都必须在allowedHeader中有一条对应的项。每一个header允许使用最多一个*通配符,不区分大小写。类型:字符串。 allowedHeaders
    allowedExposeHeaders 存储允许用户从应用程序中访问的响应头的容器。 corsConfiguration
    allowedExposeHeader 指定允许用户从应用程序中访问的响应头(例如一个Javascript的XMLHttpRequest对象)。不允许使用*通配符。OPTIONS请求中将根据此定义设置Access-Control-Expose-Headers。类型:字符串。 allowedExposeHeaders
    maxAgeSeconds 指定浏览器对特定资源的预取(OPTIONS)请求返回结果的缓存时间,在缓存时间内请求方不必发送重复的preflight请求,单位为秒。类型:Int64。 corsConfiguration

注意事项

  • 当Bucket不存在时,会返回404 Not Found错误,错误码:NoSuchBucket。
  • 如果CORS规则并不存在,会返回404 Not Found错误,错误码:NoSuchCORSConfiguration。

示例

  • 请求示例

    GET /?cors 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
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 1324
    Content-Type: application/json; charset=utf-8
    Server: BceBos
    
    {
        "corsConfiguration": [
                {
                "allowedOrigins": [
                    "http://www.example.com",
                    "www.example2.com"
                ],
                "allowedMethods": [
                        "GET",
                        "HEAD",
                        "DELETE"
                    ],
                 "allowedHeaders": [
                        "Authorization",
                        "x-bce-test",
                        "x-bce-test2"
                    ],
                "allowedExposeHeaders": [
                     "user-custom-expose-header"
                ],
                "maxAgeSeconds": 3600
            },
            {
                "allowedOrigins": [
                    "http://www.baidu.com"
                ],
                "allowedMethods": [
                        "GET",
                        "HEAD",
                        "DELETE"
                    ],
                "allowedHeaders": [
                        "*"
                ],
    
                "allowedExposeHeaders": [
                     "user-custom-expose-header"
                ],
                "maxAgeSeconds": 1800
            }
        ]
    }
    

    DeleteBucketCors接口

接口描述

DeleteBucketCors用于关闭指定Bucket的CORS功能并清空所有规则。

权限说明

只有Bucket的所有者和被授予FULL_CONTROL权限的用户才有权限删除CORS规则。

请求

  • 请求语法

    DELETE /?cors HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: <Authorization_String>
    
  • 请求参数

  • 请求头域

    无特殊Header参数

  • 请求元素

响应

  • 响应头域

  • 响应元素

注意事项

  • 当所对应的Bucket不存在时,会返回错误404 Not Found错误,错误码:NoSuchBucket。
  • 当没有权限Delete Cors时,会返回错误403 Forbidden,错误码:AccessDenied。
  • 当所对应的Bucket原本并不存在CORS规则时,会返回204 No Content。

示例

  • 请求示例

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

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

OPTIONS Object接口

接口描述

浏览器在发送跨域请求之前会发送一个preflight请求(OPTIONS)并带上特定的来源域,HTTP方法和Header信息等给BOS以决定是否发送真正的请求,此接口即响应这种请求。

权限说明

OPTIONS Object操作不需要进行鉴权。

请求

  • 请求语法

    OPTIONS /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Origin: Origin
    Access-Control-Request-Method: HTTPMethod
    Access-Control-Request-Headers: RequestHeader
    
  • 请求参数

  • 请求头域

    名称 描述 是否必需
    Origin 请求来源域,用来标识跨域请求,只允许一个方法。类型:字符串。默认值:无。
    Access-Control-Request-Method 在实际请求中将会用到的方法,只允许一个方法。类型:字符串。取值为“PUT/GET/DELETE/POST/HEAD”,无默认值。
    Access-Control-Request-Headers 在实际请求中会用到的除了简单头部之外的Headers,多个headers用逗号分割。类型:字符串。默认值:无。
  • 请求元素

响应

  • 响应头域

    名称 描述
    Access-Control-Allow-Credentials BOS的Server端是否允许客户端在请求中带cookie。需要客户端和Server端同时允许才能生效。BOS在请求通过时会返回允许,即值为true,大小写敏感。
    Access-Control-Allow-Headers 允许请求携带的Header的列表,如果请求中有不被允许的Header,则CORS规则匹配失败,返回不包含任何Access-Control-开头的头部。多个Headers也用逗号分隔。注意:返回仅仅包括此次请求的Headers列表,而不管配置文件中是否配置了更多被允许的Headers。
    Access-Control-Allow-Methods 允许请求的HTTP方法,如果不允许该请求,则不包含该头部以及所有的Access-Control-*相关的头部。类型:字符串。注意:返回的是所有允许的allowedMethods列表,而不仅仅包括此次请求的method。
    Access-Control-Allow-Origin 请求中包含的Origin,如果不允许的话将不包含该头部以及所有的Access-Control-*相关的头部。类型:字符串。
    Access-Control-Expose-Headers 允许在请求端的JavaScript程序中访问的Headers的列表。与配置文件中的exposeHeaders对应。类型:字符串。
    Access-Control-Max-Age 允许浏览器缓存preflight结果的时间,单位为秒。类型:整形。
  • 响应元素

注意事项

  • 当CORS收到OPTIONS请求后,会读取Bucket对应的CORS规则,然后进行相应的权限检查。整个检查会依次检查每一条规则,使用第一条匹配的规则来允许请求并返回对应的Header。如果所有规则都匹配失败则不附加任何CORS相关的Header。
  • CORS规则匹配成功必须满足三个条件:
    • 请求的Origin必须匹配一项allowedOrigins中一项。
    • OPTIONS请求的Access-Control-Request-Method头对应的方法必须匹配一项 allowedMethods中一项。
    • OPTIONS请求的Access-Control-Request-Headers头包含的每个Header都必须匹配一项 allowedHeader项(只要有一个不符合则整体失败)。

示例

  • 请求示例

    OPTIONS /object HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Origin: http://www.example.com
    Access-Control-Request-Method: GET
    Access-Control-Request-Headers: x-bce-test
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Access-Control-Allow-Origin: http://www.example.com 
    Access-Control-Allow-Methods: GET, HEAD, DELETE 
    Access-Control-Allow-Headers: x-bce-test
    Access-Control-Expose-Headers: user-custom-expose-header
    Access-Control-Max-Age: 3600
    Access-Control-Allow-Credentials: true
    Content-Length: 0
    Server: BceBos
    

PutBucketCopyrightProtection接口

接口描述

此命令用来开启Bucket的原图保护功能,并指定resource字段,表示生效的资源范围。

请求语法

PUT /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: date
Content-Length: request-body length
Content-Type: application/json; charset=utf-8
Authorization: AuthorizationString

(request body: json string)

请求示例

PUT /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: 2016-04-06T06:34:40Z 
Content-Length: request-body length
Content-Type: application/json; charset=utf-8
Authorization: AuthorizationString

{    
    "resource":[
                    "bucket/prefix/*",
                    "bucket/*/suffix"
                ]
}

响应示例

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

说明:用户必须拥有FULL_CONTROL权限。

GetCopyrightProtection接口

接口描述

此命令用来获取某个Bucket的原图保护配置情况。

请求语法

GET /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: date
Authorization: <Authorization_String>

请求示例

GET /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: 2016-04-06T06:34:40Z 
Authorization: AuthorizationString

响应示例

HTTP/1.1 200 OK
Content-Length: 124
Date: Wed, 06 Apr 2016 06:34:40 GMT
Server: BceBos
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786410

{    
    "resource": [
        "bucket/prefix/*",
        "bucket/*/suffix"
    ]
}

响应示例

HTTP/1.1 404
Date: Wed, 06 Apr 2016 06:34:40 GMT
Server: BceBos
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786410

说明: 请求者拥有FULL_CONTROL权限才允许查看,否则返回403错误,错误码为AccessDenied。

DeleteCopyrightProtection接口

接口描述

此命令用来关闭Bucket原图保护功能。

请求语法

DELETE /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: date
Authorization: AuthorizationString

请求示例

DELETE /?copyrightProtection HTTP/1.1
Host: <BucketName>.bj.bcebos.com
x-bce-date: 2016-04-06T06:34:40Z
Authorization: AuthorizationString

响应示例

HTTP/1.1 204 No Content
Date: Wed, 14 Sep 2016 05:37:16 GMT
x-bce-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
Server: BceBos

说明

  • 请求者只有拥有FULL_CONTROL权限才允许关闭原图保护功能,否则返回403错误,错误码为AccessDenied。
  • 如果请求的Bucket没有开通原图保护功能,依然返回HTTP状态码204。

事件通知接口

PutNotification接口

接口描述

指定bucket上增加通知规则。

注意:

  • 只有bucket owner或者full control权限才能获取这个bucket的配置。
  • 如果不是bucket owner则返回403,如果对应的文件不存在则返回404。

请求

  • 请求语法

    PUT /?notification HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    
    {
        "notifications": [
            {
                "id": "notify-id-1",
                "name": "rule-name",
                "appId": "app-id-1",
                "status": "enabled",
                "resources": [
                    "bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
                ],
                "events": [
                    "PutObject"
                ],
                "apps": [
                    {
                        "id": "app-id-1",
                        "eventUrl": "http://xxx.com/event",
                        "aipAppId": "appid:1482507431",
                        "xVars": ""
                    },
                    {
                        "id": "app-id-2",
                        "eventUrl": "brn:bce:cfc:bj:1f1c3e38xxxxxxxx4c44523f0d5b22:function:hello_bos:$LATEST"
                    },
                    {
                        "id": "app-id-3",
                        "eventUrl": "app:ImageOcr",
                        "aipAppId": "appid:1482507431",
                        "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                    }
                ],
                "quota": {
                    "quotaDay": 1000,
                    "quotaSec": 0.5
                }
            }
        ]
    }
    
  • 请求参数

    字段 类型 必要性 说明
    id String 必选 规则id
    name String 可选 规则名称
    appId String 必选 注册本条规则的产品id
    status String 必选 可选值:{"disabled", "enabled"}
    resources[] Array 必选 订阅的资源
    +resource String 必选 订阅的资源,${bucket_name}/path1/*.jpg或者/path1/*.jpg,最多只能有1个*
    events[] Array 必选 订阅的事件
    +eventType String 必选 事件类型,具体见事件类型(EventType)部分的值
    apps[] Array 必选 订阅消息的产品
    +id String 必选 被通知的产品id
    +eventUrl String 必选 处理事件通知的url,可选值:{"http", "https", "brn", "app"},http/https为自定义应用,brn为cfc的通知,app为官方应用
    +aipAppId String 可选 aip的appid
    +xVars String 可选 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果
    +quota Object 可选 配额,以下单位独立生效,例如,每秒5次并且每天1000次
    ++quotaDay Number 可选 每天配额
    ++quotaSec Number 可选 每秒配额,也就是QPS限制
  • 请求头域

响应

  • 响应头域

  • 响应元素

示例

  • 请求示例

    PUT /?notification HTTP/1.1
    Host: test.bj.bcebos.com
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Authorization: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 0
    
    {
        "notifications": [
            {
                "id": "notify-id-1",
                "name": "rule-name",
                "appId": "app-id-1",
                "status": "enabled",
                "resources": [
                    "bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
                ],
                "events": [
                    "PutObject"
                ],
                "apps": [
                    {
                        "id": "app-id-1",
                        "eventUrl": "http://xxx.com/event",
                        "aipAppId": "appid:1482507431",
                        "xVars": ""
                    },
                    {
                        "id": "app-id-2",
                        "eventUrl": "brn:bce:cfc:bj:1f1c3e38xxxxxxxx4c44523f0d5b22:function:hello_bos:$LATEST"
                    },
                    {
                        "id": "app-id-3",
                        "eventUrl": "app:ImageOcr",
                        "aipAppId": "appid:1482507431",
                        "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                    }
                ],
                "quota": {
                    "quotaDay": 1000,
                    "quotaSec": 0.5
                }
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Length: 0
    Connection: close
    Server: BceBos
    

GetNotification接口

接口描述

获取指定bucket上的通知规则。

请求

  • 请求语法

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

  • 请求参数

响应

  • 响应头域

  • 响应元素

    字段 说明
    id 规则id
    name 规则名称
    appId 注册本条规则的产品id
    status 可选值:{"disabled", "enabled"}
    resources[] 订阅的资源
    +resource 订阅的资源,${bucket_name}/path1/*.jpg或者/path1/*.jpg,最多只能有1个*
    events[] 订阅的事件
    +eventType 事件类型,当前支持
    - PutObject:简单上传
    - PostObject:表单上传
    - AppendObject:追加上传
    - CopyObject:拷贝文件
    - CompleteMultipartUpload:完成分片上传
    apps[] 订阅消息的产品
    +id 被通知的产品id
    +eventUrl 处理事件通知的url,可选值:{"http", "https", "brn", "app"}http/https为自定义应用,brn为cfc的通知,app为官方应用
    +aipAppId aip的appid
    +xVars 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果
    +quota 配额,以下单位独立生效,例如,每秒5次并且每天1000次
    ++quotaDay 每天配额
    ++quotaSec 每秒配额,也就是QPS限制

示例

  • 请求示例

    GET /?notification HTTP/1.1
    Host: test.bj.bcebos.com
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Length: 0
    Connection: close
    Server: BceBos

    {
        "notifications": [
            {
                "id": "notify-id-1",
                "name": "rule-name",
                "appId": "app-id-1",
                "status": "enabled",
                "resources": [
                    "bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
                ],
                "events": [
                    "PutObject"
                ],
                "apps": [
                    {
                        "id": "app-id-1",
                        "eventUrl": "http://xxx.com/event",
                        "aipAppId": "appid:1482507431",
                        "xVars": ""
                    },
                    {
                        "id": "app-id-2",
                        "eventUrl": "brn:bce:cfc:bj:1f1c3e383c31e6467c4c44523f0d5b22:function:hello_bos:$LATEST"
                    },
                    {
                        "id": "app-id-3",
                        "eventUrl": "app:ImageOcr",
                        "aipAppId": "appid:1482507431",
                        "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                    }
                ],
                "quota": {
                    "quotaDay": 1000,
                    "quotaSec": 0.5
                }
            }
        ]
    }

DeleteNotification

接口描述

删除指定bucket上的通知规则。

请求

  • 请求语法

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

  • 请求参数

响应

  • 响应头域

  • 响应元素

示例

  • 请求示例

    DELETE /?notification HTTP/1.1
    Host: test.bj.bcebos.com
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

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

PostEvent接口

接口描述

将事件消息推送到app设置的url上。

注意:

  • Status Code: 200 OK才会认为消息推送成功,否则将会重试;
  • 对于过载保护的情况,支持Status Code: 429 Too Many Requests返回值,会间隔一段时间再重试;

请求

  • 请求语法

    POST /?event HTTP/1.1
    Host: <User_Host>
    Date: <Date>
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    
    {
        "events": [
            {
                "version": "1.0",
                "eventId": "2a513199-bbb9-4ac7-b12a-60213c26810d",
                "eventOrigin": "bos:realtime",
                "eventTime": "2018-09-05T02:28:49Z",
                "eventType": "PutObject",
                "content": {
                    "userId": "c7ac82ae14ef42d1a4ffa3b2ececa17f",
                    "domain": "bj.bcebos.com",
                    "bucket": "bucket-test",
                    "object": "images/bos_test.jpg",
                    "etag": "977b9623a15e520c663ac5ff6647e881",
                    "contentType": "application/octet-stream",
                    "filesize": 24414,
                    "lastModified": "2018-09-05T02:28:49Z",
                    "credentials": {
                        "accessKeyId": "f3ade7c6b1a911e8bb6821a724cc157d",
                        "secretAccessKey": "07381a56d35e4b1193a418362221de81",
                        "sessionToken": "ZGZiM2M3MmU4Mjk4NGQ2MGEzYTNhYTAyMDE3NTZmZmV8AAAAAIcCAADaE18IR6jSaVWlMHxZG5wzb/7AQas3Y6V",
                        "expiration": "2018-02-22T11:22:33Z"
                    },
                    "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                }
            }
        ]
    }
    
  • 请求头域

  • 请求参数

    字段 类型 说明
    version String 事件版本,当前为1.0
    eventId String 事件唯一标识
    eventOrigin String 事件触发源,当前支持增量(bos:realtime)
    eventType String 事件类型,当前支持
    - PutObject:简单上传
    - PostObject:表单上传
    - AppendObject:追加上传
    - CopyObject:拷贝文件
    - CompleteMultipartUpload:完成分片上传
    eventTime String 事件发生时间(GMT格式)
    content Object 事件具体信息
    +domain String 所属的domain
    +bucket String 所属的bucket
    +object String object名字
    +etag String object的etag,如果object可能被覆盖,则需要用etag判断是哪个版本的object触发的事件
    +contentType String object的Content-Type
    +filesize Number 文件大小
    +lastModified String 文件更新时间
    +credentials Object 相关资源的临时授权,具体使用参考临时授权访问
    ++accessKeyId String 临时授权的Access Key ID
    ++secretAccessKey String 临时授权的Secret Access Key
    ++sessionToken String 临时授权的Session Token
    ++expiration String 临时授权的的有效时间
    ++xVars String 用户设置通知中的xVars原文

响应

  • 响应头域

  • 响应元素

示例

  • 请求示例

    POST /?event HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 0
    
    {
        "events": [
            {
                "version": "1.0",
                "eventId": "2a513199-bbb9-4ac7-b12a-60213c26810d",
                "eventOrigin": "bos:realtime",
                "eventTime": "2018-09-05T02:28:49Z",
                "eventType": "PutObject",
                "content": {
                    "userId": "c7ac82ae14ef42d1a4ffa3b2ececa17f",
                    "domain": "bj.bcebos.com",
                    "bucket": "bucket-test",
                    "object": "images/bos_test.jpg",
                    "etag": "977b9623a15e520c663ac5ff6647e881",
                    "contentType": "application/octet-stream",
                    "filesize": 24414,
                    "lastModified": "2018-09-05T02:28:49Z",
                    "credentials": {
                        "accessKeyId": "f3ade7c6b1a911e8bb6821a724cc157d",
                        "secretAccessKey": "07381a56d35e4b1193a418362221de81",
                        "sessionToken": "ZGZiM2M3MmU4Mjk4NGQ2MGEzYTNhYTAyMDE3NTZmZmV8AAAAAIcCAADaE18IR6jSaVWlMHxZG5wzb/7AQas3Y6V",
                        "expiration": "2018-02-22T11:22:33Z"
                    },
                    "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                }
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Length: 0
    Connection: close
    Server: BceBos
    

PostResult

接口描述

ImageOcrImageClassify两种产品处理后的事件消息推送到app设置的url上,内容包含BOS的事件信息和AI处理的结果。

注意:

  • Status Code: 200 OK才会认为消息推送成功,否则将会重试;
  • 对于过载保护的情况,支持Status Code: 429 Too Many Requests返回值,会间隔一段时间再重试;

请求

  • 请求语法

    POST /?result HTTP/1.1
    Host: <User_Host>
    Date: <Date>
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    
    {
        "events": [
            {
                "version": "1.0",
                "eventType": "PutObject",
                "eventTime": "2009-10-28T22:32:00Z",
                "content": {
                    "domain": "bj.bcebos.com",
                    "bucket": "bucket-test",
                    "object": "images/bos_test.jpg",
                    "etag": "977b9623a15e520c663ac5ff6647e881",
                },
                "imageOcr": {
                    "log_id": 153673668620866,
                    "result": {
                        "ocr": {
                            "log_id": 1078286758436670376,
                            "words_result": [
                                {
                                    "words": "MAKE"
                                },
                                {
                                    "words": "AMERICA"
                                },
                                {
                                    "words": "GREAT AGAIN"
                                }
                            ],
                            "words_result_num": 5,
                            "direction": 0
                        }
                    }
                },
                "imageClassify": {
                    "log_id": 6353842115261500790,
                    "result_num": 2,
                    "result": [
                        {
                            "score": 0.893464,
                            "root": "公众人物",
                            "keyword": "约翰逊"
                        },
                        {
                            "score": 0.566877,
                            "root": "人物-人物特写",
                            "keyword": "马尾辫"
                        }
                    ]
                }
            }
        ]
    }
    
  • 请求参数

    字段 类型 说明
    version String 事件版本,当前为1.0
    eventType String 事件类型,当前支持
    - PutObject:简单上传
    - PostObject:表单上传
    - AppendObject:追加上传
    - CopyObject:拷贝文件
    - CompleteMultipartUpload:完成分片上传
    eventTime String 事件发生时间(GMT格式)
    content Object 事件具体信息
    +domain String 所属的domain
    +bucket String 所属的bucket
    +object String object名字
    +etag String object的etag,如果object可能被覆盖,则需要用etag判断是哪个版本的object触发的事件
    result String 根据实际的事件为imageOcrimageClassify,具体内容参见AI通用文字识别AI通用图像分析
  • 请求头域

响应

  • 响应头域

  • 响应元素

示例

  • 请求示例

    POST /?result HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 0
    
    {
        "events": [
            {
                "version": "1.0",
                "eventType": "PutObject",
                "eventTime": "2009-10-28T22:32:00Z",
                "content": {
                    "domain": "bj.bcebos.com",
                    "bucket": "bucket-test",
                    "object": "images/bos_test.jpg",
                    "etag": "977b9623a15e520c663ac5ff6647e881",
                },
                "imageOcr": {
                    "log_id": 153673668620866,
                    "result": {
                        "ocr": {
                            "log_id": 1078286758436670376,
                            "words_result": [
                                {
                                    "words": "MAKE"
                                },
                                {
                                    "words": "AMERICA"
                                },
                                {
                                    "words": "GREAT AGAIN"
                                }
                            ],
                            "words_result_num": 5,
                            "direction": 0
                        }
                    }
                },
                "imageClassify": {
                    "log_id": 6353842115261500790,
                    "result_num": 2,
                    "result": [
                        {
                            "score": 0.893464,
                            "root": "公众人物",
                            "keyword": "约翰逊"
                        },
                        {
                            "score": 0.566877,
                            "root": "人物-人物特写",
                            "keyword": "马尾辫"
                        }
                    ]
                }
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
    Date: Wed, 12 Sep 2018 06:34:40 GMT
    Content-Length: 0
    Connection: close
    Server: BceBos
    

Android批量打包接口

接口描述

该接口用于请求Android的批量打包功能。BOS的Android批量打包功能在后台调度计算资源按照配置文件进行批量打包。

说明:使用本接口需要先在控制台开通Android批量打包功能,详情请参见开通Android批量打包服务

请求

  • 请求语法

    • 配置批量打包并接收通知

      POST <ObjectKey>?process HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <Authorization_String>
      Content-Type: application/json; charset=utf-8
      Content-Length: <Content_Length>
      
      {
          "action" : {
              "async" : [{
                      "url" : "$(apk-pack)",
                      "parameters" : "<base64_encode(param)>"
                  }, {
                      "url" : "<result-notify-url>"
                  }
              ],
          }
      }
      
    • 配置批量打包但不接收通知

      POST <ObjectKey>?process HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <Authorization_String>
      Content-Type: application/json; charset=utf-8
      Content-Length: <Content_Length>
      
      {
          "action" : {
              "async" : [{
                      "url" : "$(apk-pack)",
                      "parameters" : "<base64_encode(param)>"
                  }, 
              ],
          }
      }
      
  • 请求参数

    参数名称 说明
    第一个url 固定取值为$(apk-pack),不需要修改。
    parameters 第一个服务的参数。此项值是对打包功能参数进行base64编码而成。打包功能参数依然是个json字符串。
    第二个url 该URL为批量打包完成后,接收通知的URL。如果用户希望接收通知,则这个参数填写接收通知的URL。如果无需接收通知,则可以删除该行配置,不影响打包功能。

    打包功能参基本结构:

    {
          "algorithm" : "v1",
          "channelFile" : "<channelFile-name>",
          "targetPrefix" : "<target-prefix>"
        }
    
    • algorithm:打包算法,目前只有v1。
    • channelFile:打包的渠道文件,此渠道文件必须上传到bos上,可以为prefix或直接文件名,渠道文件必须是一个TSV文件(tab seperated values),第一行必须为insertedFileName和distributedPackageName,其两列分别为空文件名、渠道包名,且两个字段之间必须以tab分隔,不可以用空格。示例如下:
      insertedFileName    distributionPackageName
        file_123    my_123.apk
        file_222    bbb_222.apk
      
    • targetPrefix:打包输出APK所存放的prefix
  • 请求头域

响应

  • 响应头域

  • 响应元素

示例

  • 请求示例

    上传渠道文件channelFile.tsv到bucket上名"pre2/"的prefix下,内容为:

    insertedFileName    distributionPackageName
    file_123    my_123.apk
    file_222    bbb_222.apk
    

    将打包功能参数

    {
              "algorithm" : "v1",
              "channelFile" : "pre2/channelFile.tsv",
              "targetPrefix" : "p1/p2/"
      }
    

    base64编码后
    ICB7CiAgCQkiYWxnb3JpdGhtIiA6ICJ2MSIsCiAgCQkiY2hhbm5lbEZpbGUiIDogInByZTIvY2hhbm5lbEZpbGUudHN2IiwKICAJCSJ0YXJnZXRQcmVmaXgiIDogInAxL3AyLyIKICB9

    填充到parameters中,发送的请求如下:

    POST <ObjectKey>?process HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    
    {
        "action" : {
            "async" : [{
                    "url" : "$(apk-pack)",
                    "parameters" : "ICB7CiAgCQkiYWxnb3JpdGhtIiA6ICJ2MSIsCiAgCQkiY2hhbm5lbEZpbGUiIDogInByZTIvY2hhbm5lbEZpbGUudHN2IiwKICAJCSJ0YXJnZXRQcmVmaXgiIDogInAxL3AyLyIKICB9"
                }, {
                    "url" : "http://myserver.com"
                }
            ]
        }
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Thu, 22 Jun 2017 07:30:56 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: <Content_Length>
    Connection: keep-alive
    Server: BceBos
    x-bce-debug-id: MTAuNzUuNzguNDA6VGh1LCAyMiBKdW4gMjAxNyAxNTozMDo1NiBDU1Q6MTg1MDY5NDg3OQ==
    x-bce-request-id: 598f7e18-77fb-424a-bc68-95acb0644076
    
    {
        "code" : 66,
        "requestId" : "aa974b72-3587-4854-a46f-b0e7993b5778",
        "jobIds" : ["360-172707368", "359-172707368"]
    }