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文件名称</