Enumerate Objects under Bucket
Last Updated：2021-09-13
Interface Description
This interface is used to get the object message list of the specified bucket.
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, including 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.
Request URI
GET /v1/{bucketName}
| Parameter Name | Parameter Type | Required | Description | Example Value | Parameter Position |
|---|---|---|---|---|---|
| bucketName | String | Yes | BucketName | "bucketName_example" | Path |
| 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. | "delimiter_example" | Query |
| marker | String | No | The objects are sorted in alphabetical order and returned from the first one after the marker. | "marker_example" | Query |
| maxKeys | Integer | 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. | 56 | Query |
| prefix | String | No | Key prefix. Under its limitation, the object key returned must use it as the prefix. | "prefix_example" | Query |
Request Body Parameters
Instructions for Data Structure of Request Body Field
Response Body Parameters
Instructions for Data Structure of Response Body Field
| Parameter Name | Parameter Type | Description | Example Value |
|---|---|---|---|
| name | String | Bucket name | bucket |
| prefix | String | Query prefix | |
| delimiter | String | Query terminator | / |
| marker | String | Starting point of this query | |
| maxKeys | Integer | Maximum number of requests returned | 1000 |
| isTruncated | Boolean | 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. | false |
| contents | List |
A list of objects returned |
Data Structure Description of Contents Field
| Parameter Name | Parameter Type | Description | Example Value |
|---|---|---|---|
| key | String | Object name | my-image1.jpg |
| lastModified | String | Last modification time of the object | 2009-10-12T17:51:30Z |
| eTag | String | HTTP protocol entity tag of the object | 0cce7caecc8309864f663d78d1293f98 |
| size | Integer | Size of the object content (bytes) | 124231 |
| storageClass | String | Storage class of the object. It returns STANDARD_IA for infrequent access, COLD for cold storage, ARCHIVE for archive storage, and STANDARD for standard storage. | COLD |
| owner | Owner | Object uploader information |
Data Structure Description of Owner Field
| Parameter Name | Parameter Type | Description | Example Value |
|---|---|---|---|
| id | String | Object uploader ID | 168bf6fd8fa74d9789f35a283a1f15e2 |
| displayName | String | Object uploader name | mtd |
Request Example
GET /v1/bucketName_example?delimiter=delimiter_example&marker=marker_example&maxKeys=56&prefix=prefix_example
<Common Request Header>
{ }Response Example
HTTP/1.1 200 OK
<Common response header>
{
"isTruncated" : false,
"maxKeys" : 1000,
"contents" : [ {
"owner" : {
"displayName" : "mtd",
"id" : "168bf6fd8fa74d9789f35a283a1f15e2"
},
"storageClass" : "COLD",
"size" : 124231,
"eTag" : "0cce7caecc8309864f663d78d1293f98",
"lastModified" : "2009-10-12T17:51:30Z",
"key" : "my-image1.jpg"
}, {
"owner" : {
"displayName" : "mtd",
"id" : "168bf6fd8fa74d9789f35a283a1f15e2"
},
"storageClass" : "COLD",
"size" : 124231,
"eTag" : "0cce7caecc8309864f663d78d1293f98",
"lastModified" : "2009-10-12T17:51:30Z",
"key" : "my-image1.jpg"
} ],
"prefix" : "prefix",
"delimiter" : "/",
"marker" : "marker",
"name" : "bucket"
}Error Code
Refer to the universal error code.