对象存储BOS

    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/"}
          ]
      }
    上一篇
    ListBuckets
    下一篇
    GetBucketLocation