所有文档

          对象存储 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