ListObjects
Last Updated:2021-12-08
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 andSTANDARD
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:
- 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.
- 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/"} ] }