接口描述

本接口用于获得指定Bucket的Object信息列表。

请求（Request）

• 请求语法

  Plain Text 复制

  1   GET / HTTP/1.1
  2   Host: <BucketName>.bj.bcebos.com
  3   Date: <Date> 
  4   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

  JSON 复制

  1GET / HTTP/1.1
  2Host: <BucketName>.bj.bcebos.com
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Authorization: <AuthorizationString>

• 响应示例（JSON）1，递归列举所有object

  JSON 复制

  1HTTP/1.1 200 OK
  2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Server: BceBos
  5
  6{
  7     "name":"bucket",
  8     "prefix":"",
  9     "delimiter":"/",
  10     "marker":"",
  11     "maxKeys":1000,
  12     "isTruncated":false,
  13     "contents":[
  14         {
  15            "key":"my-image.jpg",
  16            "lastModified":"2009-10-12T17:50:30Z",
  17            "eTag":"fba9dede5f27731c9771645a39863328",
  18            "size":434234,
  19            "storageClass":"STANDARD",
  20            "owner":{
  21                "id":"168bf6fd8fa74d9789f35a283a1f15e2",
  22                "displayName":"mtd"
  23           }
  24         },
  25         {
  26            "key":"my-image1.jpg",
  27            "lastModified":"2009-10-12T17:51:30Z",
  28            "eTag":"0cce7caecc8309864f663d78d1293f98",
  29            "size":124231,
  30            "storageClass":"COLD",
  31            "owner":{
  32                "id":"168bf6fd8fa74d9789f35a283a1f15e2",
  33                "displayName":"mtd"
  34         }
  35      ]
  36}

• 请求示例（JSON）2， 列举根目录下的部分文件和子目录，受maxKeys限制(不包括子目录下的文件)

  JSON 复制

  1GET /?delimiter=/ HTTP/1.1
  2Host: <BucketName>.bj.bcebos.com
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Authorization: <AuthorizationString>

• 响应示例（JSON）2

  JSON 复制

  1HTTP/1.1 200 OK
  2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
  3Date: Wed, 06 Apr 2016 06:34:40 GMT
  4Server: BceBos
  5
  6{
  7    "name":"bucket",
  8    "prefix":"" ,
  9    "delimiter":"/",
  10    "marker":"",
  11    "maxKeys":1000,
  12    "isTruncated":false,
  13    "contents":[
  14        {
  15            "key":"my-image.jpg",
  16            "lastModified":"2009-10-12T17:50:30Z",
  17            "eTag":"fba9dede5f27731c9771645a39863328",
  18            "size":434234,
  19            "storageClass":"STANDARD",
  20            "owner":{
  21                "id":"168bf6fd8fa74d9789f35a283a1f15e2",
  22                "displayName":"mtd"
  23            }
  24        }
  25    ],
  26    "commonPrefixes":[
  27         {"prefix":"photos/"},
  28         {"prefix":"mtd/"}
  29    ]
  30}