Interface Description

This interface is used to get the object message list of the specified bucket.

Request

• Request syntax

     GET / HTTP/1.1
     Host: <BucketName>.bj.bcebos.com
     Date: <Date> 
     Authorization: <AuthorizationString>

• Request header field

  No special header parameters.

• Request parameters

  Field	Type	Required?	Description
  delimiter	String	No	Delimiter. This item is mainly used to implement the logic of the list folder. If the delimiter is specified during the request, BOS truncates the matched object name according to certain rules (from the prefix to the first delimiter), and the truncated string is returned as the data of CommonPrefixes after the deduplication. The delimiter length is limited to 1.
  marker	String	No	The objects are sorted in alphabetical order and returned from the first one after the marker.
  maxKeys	Int	No	The maximum length of the object list returned is 1,000 by default. If the specified value is greater than 1,000, take 1,000 for operation.
  prefix	String	No	Key prefix, which limits that the object key returned must use it as the prefix.

Response

• Response header field

  No special head parameter response

• Response element

  Name	Type	Description
  commonPrefixes	Array	This item is returned only when the delimiter is specified.
  +prefix	String	Match the object from the beginning of the prefix to the first delimiter and return it as a set of elements.
  contents	Array	A list of objects returned
  +key	String	Object Name
  +lastModified	Date	Last modification time of this object
  +eTag	String	HTTP protocol entity tag of the object
  +size	Int	Size of the object content (byte)
  +storageClass	String	Storage type of the object. It returns STANDARD_IA for infrequent access, COLD for cold storage, ARCHIVE for archive storage and STANDARD for standard storage.
  +owner	Container	Object uploader information
  ++id	String	Object uploader ID
  ++displayName	String	Object uploader name
  delimiter	String	Query terminator
  isTruncated	Bool	It indicates whether the query returns the complete results. False: it indicates that all results are returned this time. True: it indicates that not all results are returned this time.
  maxKeys	Int	Maximum number of requests returned
  marker	String	Starting point of this query
  name	String	Bucket name
  nextMarker	String	Only when the IsTruncated is true, this item is returned as the the marker value for the next query.
  prefix	String	Query prefix

  Considerations

  The delimiter can be used to implement the folder logic:

  1. If the prefix is set to a folder name, the return value can list the files starting with this prefix, i.e., all recursion files in this folder and files in the subfolder.
  2. If the delimiter is set to “/”, the return value only lists the files in this folder, the subfolder name in this folder is returned in the CommonPrefixes section, and the recursion files in the subfolder are not displayed. For example, there are three objects in a bucket, i.e., fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. If the prefix is set to "fun/", three objects are returned. If the delimiter is set to "/" additionally, the file "fun/test.jpg" and the prefix "fun/movie/" are returned.

Example

• Request examples (JSON) 1

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

• Response example (JSON) 1 listing all objects recursively

  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"
           }
        ]
  }

• Request example (JSON) 2 listing all files in the root directory (excluding files in a subdirectory)

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

• Response example (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/"}
      ]
  }