对象存储BOS

    Bucket相关接口

    GetBucketLocation接口

    接口描述

    获取Bucket所在的区域。

    请求(Request)

    • 请求语法

      GET /?location HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <AuthorizationString>
      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: bj.bcebos.com
      Date: <Date>
      Authorization: <AuthorizationString>
    • 请求头域

      无特殊参数

    • 请求参数 无特殊参数

    响应(Response)

    • 响应头域

      无特殊Header参数响应

    • 响应元素

      名称 类型 描述
      owner Object Bucket owner(拥有者)信息
      +id String Bucket owner的用户id
      +displayName String Bucket owner的名称
      buckets Array 存放多个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: <AuthorizationString>
      Content-Length: <ContentLength>
      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: <AuthorizationString>
    • 请求头域

      无特殊Header参数

    • 请求参数

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

    响应(Response)

    • 响应头域

      无特殊Header参数响应

    • 响应元素

      名称 类型 描述
      commonPrefixes Array 仅当指定delimiter,才会返回此项
      +prefix String 匹配以prefix开始到第一次出现Delimiter字符之间的object作为一组元素返回
      contents Array 返回的一个object的列表
      +key String Object名称
      +lastModified Date 此Object最后一次被修改的时间
      +eTag String Object的HTTP协议实体标签
      +size Int Object的内容的大小(字节数)
      +storageClass String Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,归档存储返回ARCHIVE,标准存储返回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,递归列举所有object

      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"
                 }
               },
               {
                  "key":"my-image1.jpg",
                  "lastModified":"2009-10-12T17:51:30Z",
                  "eTag":"0cce7caecc8309864f663d78d1293f98",
                  "size":124231,
                  "storageClass":"COLD",
                  "owner":{
                      "id":"168bf6fd8fa74d9789f35a283a1f15e2",
                      "displayName":"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: <AuthorizationString>
    • 请求头域

      无特殊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: <AuthorizationString>
    • 请求头域

      无特殊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: <ContentLength>
      Content-Type:application/json; charset=utf-8
      Authorization: <AuthorizationString>
      x-bce-acl: <ACLString>
    • 请求参数

      无特殊参数

    • 请求头域

      名称 类型 描述 是否必需
      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: <AuthorizationString>
    • 请求头域

      无特殊参数

    • 请求参数

      无特殊参数

    响应(Response)

    • 响应元素(以JSON请求为例)

      名称 类型 描述
      accessControlList Objcet 保存acl的容器
      +grantee Objcet 一个被授权人
      ++id String 被授权用户id
      +permission String 授权权限支持:FULL_CONTROL,READ,WRITE、LIST、MODIFY、GetObject、PutObject、DeleteObject、RestoreObject等
      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,也可以是不同Region下的Bucket。
    • 目标Bucket和源Bucket都必须没有开通过replication,且没有成为别的数据同步规则中的目的Bucket。
    • 整个配置的大小不能超过128k。
    • 数据同步暂时不支持归档类型文件的同步,进行数据同步时会忽略归档类型文件。

    请求(Request)

    • 请求语法

      PUT /?replication 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>
      
      {
          "status":"enabled",
          "resource":[
              "src-bucket-name/abc"
              "src-bucket-name/cd*",
              ...
          ],
          "destination":
          {
                  "bucket":"dst-bucket-name",
                  "storageClass":"COLD"
          },
          "replicateHistory":
          {
                  "bucket":"dst-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的存储类型一致,则该参数不需要配置;如果需要单独指定存储类型可以为STANDARDSTANDARD_IACOLDARCHIVE
      replicateHistory 历史文件复制,有该项则认为是开启。replicateHistory中的Bucket name需要和上面destination中的Bucket name保持一致。开启历史文件复制后,存量的全部Object都同步复制到目的Bucket,历史文件复制范围不参考resource。
      +bucket 目的Bucket name
      +storageClass 目的Object的存储类型。如果保持和源Bucket的存储类型一致,则该参数不需要配置;如果需要单独指定存储类型可以为STANDARDSTANDARD_IACOLDARCHIVE
      replicateDeletes 是否开启删除同步,可以为enabled,disabled

    响应(Response)

    • 响应元素

      无特殊参数

    • 响应头域

      无特殊参数

    示例

    • 请求示例

      PUT /?replication HTTP/1.1
      Host: BucketName.bj.bcebos.com
      x-bce-date: date
      Content-Length: xxx
      Content-Type: application/json; charset=utf-8
      Authorization: AuthorizationString
      
      {
          "status":"enabled",
          "resource":[
                      "src-bucket-name/abc",
                      "bucket/cd*",
                      ...
          ],
          "destination":
          {
                  "bucket":"dst-bucket-name",
                  "storageClass":"COLD"
          },
          "replicateHistory":
          {
                  "bucket":"dst-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表示冷存储类型,ARCHIVE表示归档存储类型。
      replicateHistory 历史文件复制,有该项则认为是开启
      +bucket 目的Bucket name
      +storageClass 目的Object的存储类型,默认为REMAIN,可以为STANDARD,STANDARD_IA,COLD,ARCHIVE
      replicateDeletes 是否开启删除同步,可以为enabled,disabled
    • 响应头域

      无特殊参数

    示例

    • 请求示例

      GET /?replication HTTP/1.1
      Host: BucketName.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":[
                      "src-bucket-name/abc",
                      "src-bucket-name/cd*",
                      ...
          ],
          "destination":
          {
                  "bucket":"dst-bucket-name",
                  "storageClass":"COLD"
          },
          "replicateHistory":
          {
                  "bucket":"dst-bucket-name",
                  "storageClass":"COLD"
          },
          "replicateDeletes":"enabled",
          "id":"sample-bucket-replication-config",
      }

    DeleteBucketReplication接口

    接口描述

    此命令用来删除数据同步复制配置。

    请求(Request)

    • 请求语法

      DELETE /?replication HTTP/1.1
      Host: <BucketName>.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接口

    接口描述

    此命令用来获取数据同步复制的进程状态。

    请求(Request)

    • 请求语法

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

      无特殊参数

    • 请求参数

      无特殊参数

    响应(Response)

    • 响应元素

      参数 描述
      status 是否开启了数据同步功能,可选值为enableddisabled
      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: <AuthorizationString>
      Content-Length: <ContentLength>
      
      {
      	"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: <AuthorizationString>
      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: &lt;AuthorizationString>
    • 请求头域

      无特殊参数

    • 请求参数

      无特殊参数

    响应(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: <BucketName>.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_IACOLDARCHIVE,表示从原存储类型转为低频存储或冷存储或归档存储。

    响应(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: <BucketName>.bj.bcebos.com
      Date: GMT Date
      Authorization: AuthorizationString
    • 请求头域

      无特殊参数

    • 请求参数

      无特殊参数

    响应(Response)

    • 响应元素

      无特殊元素

    • 响应头域

      无特殊头域

    示例

    • 请求示例

      DELETE /?lifecycle HTTP/1.1
      Host: <BcuketName>.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: <BcuketName>.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代表冷存储,ARCHIVE代表归档类型。

    响应(Response)

    • 响应元素

      无特殊元素

    • 响应头域

      无特殊头域

    示例

    • 请求示例

      PUT /?storageClass HTTP/1.1
      Host: <BcuketName>.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: <BcuketName>.bj.bcebos.com
      x-bce-date: date
      Content-Type: application/json; charset=utf-8
      Authorization: AuthorizationString
    • 请求头域

      无特殊参数

    • 请求参数

      无特殊参数

    响应(Response)

    • 响应头域

      无特殊头域

    • 响应元素

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

    示例

    • 请求示例

      GET /?storageClass HTTP/1.1
      Host: <BcuketName>.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: <AuthorizationString>
      Content-Length: <ContentLength>
      
      {
      	"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: <AuthorizationString>
      Content-Length: 0
    • 请求参数

    • 请求头域

    响应(Response)

    • 响应元素

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

    示例

    • 请求示例

      Get /?encryption HTTP/1.1
      Host: <BcuketName>.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: <AuthorizationString>
    • 请求参数

    • 请求头域

    响应(Response)

    • 响应元素

    • 响应头域

    示例

    • 请求示例

      DELETE /?encryption HTTP/1.1
      Host: <BcuketName>.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 权限。不建议设置归档文件,归档文件没有取回时不可读,StaticWebsite此时不会生效。

    请求(Request)

    • 请求头域

      无特殊参数

    • 请求参数

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

    响应(Response)

    • 响应元素

    • 响应头域

    示例

    • 请求示例

      PUT /?website HTTP/1.1
      Host: <BcuketName>.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的静态网站托管信息

    请求(Request)

    • 请求头域

      无特殊参数

    • 请求语法

        ```
        Get /?website HTTP/1.1
        Host: <BucketName>.bj.bcebos.com
        Date: <Date>
        Authorization: <AuthorizationString>
        Content-Length: 0
        ```

      响应(Response)

    • 响应元素

      名称 描述
      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设置的静态网站托管信息,并关闭此bucket的静态网站托管。
    
    用户必须对bucket具有 FULL_CONTROL 权限。

    请求(Request)

    • 请求头域

      无特殊参数

    • 请求语法

        ```
        DELETE /?website HTTP/1.1
        Host: <BucketName>.bj.bcebos.com
        Date: <Date>
        Authorization: <AuthorizationString>
        ```

      响应(Response)

    • 响应元素

      无特殊元素

    • 响应头域

      无特殊头域

    示例

    • 响应示例

      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: <AuthorizationString>
      Content-Type: application/json
      Content-Length: <ContentLength>
    • 请求头域

      无特殊Header参数

    • 请求元素

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

      说明

      1.若已开通trash功能,会覆盖原目录名。

      2."trashDir"只能包含字母,数字,中文,下划线(_)和短横线(-),小数点(.)。包含'/'会报错。

      3.开通了trash功能的bucket, 删除object会到回收站中(回收站中的object的全称是:trashDir + '/' + old object name)。未开通此功能的bucket,或者开通此功能的bucket且删除回收站内的object时,会彻底删除。

      4.归档类型文件不支持Bucket Trash,删除归档类型文件时会直接删除。

    响应

    • 响应头域

    • 响应元素

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

    示例

    • 请求示例

      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: <AuthorizationString>
    • 请求头域

      无特殊Header参数

    • 请求元素

    响应

    • 响应头域

    • 响应元素

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

      返回结果解释如下:

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

    示例

    • 请求示例

      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: <AuthorizationString>   
    • 请求头域

      无特殊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 204 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: <AuthorizationString>
      
      {
          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: <AuthorizationString>
    • 请求参数

    • 请求头域

      无特殊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: <AuthorizationString>
    • 请求参数

    • 请求头域

      无特殊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字段,表示生效的资源范围。 对于开通原图保护的文件,不允许匿名下载访问该文件,或带自定义图片处理参数访问,只允许使用style样式访问或携带合法签名访问。

    请求语法

    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: <AuthorizationString>

    请求示例

    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: <AuthorizationString>
      Content-Type: application/json; charset=utf-8
      Content-Length: <ContentLength>
    • 请求参数
    字段 类型 必要性 说明
    id String 必选 规则id
    name String 可选 规则名称
    appId String 必选 注册本条规则的产品id
    status String 必选 可选值:{"disabled", "enabled"}
    encryption Object 可选 加密方式
    +key String 可选 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey
    resources[] Array 必选 订阅的资源
    +resource String 必选 订阅的资源,${bucket_name}/path1/*.jpg或者/path1/*.jpg,最多只能有1个*
    events[] Array 必选 订阅的事件
    +eventType String 必选 事件类型,当前支持:
    - PutObject:普通上传Object
    - PostObject:表单上传Object
    - AppendObject:追加上传Object
    - CopyObject:拷贝Object
    - CompleteMultipartUpload:完成Object分片上传
    - FetchObject:抓取Object,包含镜像回源等产生的抓取
    - DeleteObject:删除Object
    - DeleteMultipleObjects:删除多个Object
    apps[] Array 必选 订阅消息的产品
    +id String 必选 被通知的产品id
    +eventUrl String 必选 处理事件通知的url,可选值:{"http", "https", "brn", "app"},http/https为自定义应用,brn为cfc的通知,app为官方应用
    +xVars String 可选 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果

    如果仅用于配置通知或者回调的密钥,可以简化为如下参数:

    字段 类型 必要性 说明
    id String 必选 规则id
    name String 可选 规则名称
    appId String 必选 注册本条规则的产品id
    status String 必选 可选值:{"disabled", "enabled"}
    encryption Object 可选 加密方式
    +key String 可选 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey
    • 请求头域

    响应

    • 响应头域

    • 响应元素

    示例

    • 请求示例

      PUT /?notification HTTP/1.1
      Host:  <BucketName>.bj.bcebos.com
      Date: Wed, 12 Sep 2018 06:34:40 GMT
      Authorization: <AthorizationString>
      Content-Type: application/json; charset=utf-8
      Content-Length: 0
      
      {
          "notifications": [
              {
                  "id": "notify-id-1",
                  "name": "rule-name",
                  "appId": "app-id-1",
                  "status": "enabled",
                  "encryption": {
                      "key": "06a62b70f47dc4a0a7da349609f1a1ac",
                  },
                  "resources": [
                      "bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
                  ],
                  "events": [
                      "PutObject"
                  ],
                  "apps": [
                      {
                          "id": "app-id-1",
                          "eventUrl": "http://xxx.com/event",
                          "xVars": ""
                      },
                      {
                          "id": "app-id-2",
                          "eventUrl": "brn:bce:cfc:bj:1f1c3e38xxxxxxxx4c44523f0d5b22:function:hello_bos:$LATEST"
                      },
                      {
                          "id": "app-id-3",
                          "eventUrl": "app:ImageOcr",
                          "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

    GetNotification接口

    接口描述

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

    请求

    • 请求语法

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

    • 请求参数

    响应

    • 响应头域

    • 响应元素
    字段 类型 必要性 说明
    id String 必选 规则id
    name String 可选 规则名称
    appId String 必选 注册本条规则的产品id
    status String 必选 可选值:{"disabled", "enabled"}
    encryption Object 可选 加密方式
    +key String 可选 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey
    resources[] Array 必选 订阅的资源
    +resource String 必选 订阅的资源,${bucket_name}/path1/*.jpg或者/path1/*.jpg,最多只能有1个*
    events[] Array 必选 订阅的事件
    +eventType String 必选 事件类型,当前支持:
    - PutObject:普通上传Object
    - PostObject:表单上传Object
    - AppendObject:追加上传Object
    - CopyObject:拷贝Object
    - CompleteMultipartUpload:完成Object分片上传
    - FetchObject:抓取Object,包含镜像回源等产生的抓取
    - DeleteObject:删除Object
    - DeleteMultipleObjects:删除多个Object
    apps[] Array 必选 订阅消息的产品
    +id String 必选 被通知的产品id
    +eventUrl String 必选 处理事件通知的url,可选值:{"http", "https", "brn", "app"},http/https为自定义应用,brn为cfc的通知,app为官方应用
    +xVars String 可选 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果

    示例

    • 请求示例

      GET /?notification HTTP/1.1
      Host: <BucketName>.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",
                          "xVars": ""
                      },
                      {
                          "id": "app-id-2",
                          "eventUrl": "brn:bce:cfc:bj:1f1c3e383c31e6467c4c44523f0d5b22:function:hello_bos:$LATEST"
                      },
                      {
                          "id": "app-id-3",
                          "eventUrl": "app:ImageOcr",
                          "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
                      }
                  ]
              }
          ]
      }

    DeleteNotification

    接口描述

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

    请求

    • 请求语法

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

    • 请求参数

    响应

    • 响应头域

    • 响应元素

    示例

    • 请求示例

      DELETE /?notification HTTP/1.1
      Host: <BucketName>.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接口

    接口描述

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

    如果规则中配置了encryption字段,那么请求中会包含Authorization的签名,保证消息不会被伪造或篡改。

    注意:

    • 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>
      Authorization: <AuthorizationString>
    • 请求头域

    • 请求参数
    字段 类型 说明
    version String 事件版本,当前为1.0
    eventId String 事件唯一标识
    eventOrigin String 事件触发源,当前支持增量(bos:realtime)
    eventType String 事件类型
    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/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处理的结果。

    如果规则中配置了encryption字段,那么请求中会包含Authorization的签名,保证消息不会被伪造或篡改。

    注意:

    • 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>
      Authorization: <AuthorizationString>
    • 请求参数
    字段 类型 说明
    version String 事件版本,当前为1.0
    eventType String 事件类型
    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/test.jpg",
                      "etag": "977b9623a15e520c663ac5ff6647e881",
                  },
                  "imageOcr": {
                      "log_id": 153673668620866,
                      "result": {
                          "ocr": {
                              "log_id": 1078286758436670376,
                              "words_result": [
                                  {
                                      "words": "MAKE"
                                  }
                              ],
                              "words_result_num": 1,
                              "direction": 0
                          }
                      }
                  },
                  "imageClassify": {
                      "log_id": 6353842115261500790,
                      "result_num": 1,
                      "result": [
                          {
                              "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
    上一篇
    访问控制
    下一篇
    Object相关接口