列举存储桶下的Object
更新时间：2024-07-26
接口说明
本接口用于获得指定Bucket的Object信息列表。
注意事项
Delimiter可以用来实现文件夹逻辑：
- 如果把prefix设为某个文件夹名，就可以罗列以此prefix开头的文件，即该文件夹下递归的所有的文件和子文件夹内的文件。
- 如果再把delimiter设置为 / 时，返回值就只罗列该文件夹下的文件，该文件夹下的子文件夹名返回在CommonPrefixes部分，子文件夹下递归的文件不被显示。 如一个bucket下存在三个object：fun/test.jpg，fun/movie/001.avi，fun/movie/007.avi。 若设定prefix为“fun/”，则返回三个object；如果增加设定delimiter为“/”，则返回文件“fun/test.jpg”和前缀“fun/movie/”。
在线调试
请求URI
GET /v1/{bucketName}
| 参数名称 | 参数类型 | 是否必须 | 描述 | 示例值 | 参数位置 |
|---|---|---|---|---|---|
| bucketName | String | 是 | BucketName | "bucketName_example" | Path |
| delimiter | String | 否 | 分隔符; 主要用此项实现list文件夹的逻辑。如果在请求的时候指定了delimiter，BOS把匹配到的Object名称按照一定规则（从preifx到第一个delimiter）截取，截取的字符串去重作为CommonPrefixes的数据返回; delimiter长度限制为1 | "delimiter_example" | Query |
| marker | String | 否 | object为字母序排列，从marker之后的第一个开始返回 | "marker_example" | Query |
| maxKeys | Integer | 否 | 返回object列表长度最大为1000，默认值是1000，如果指定的值大于1000，按1000操作 | 56 | Query |
| prefix | String | 否 | key前缀，限定返回的object key必须以此为前缀 | "prefix_example" | Query |
请求体参数
请求体字段数据结构说明
响应体参数
响应体字段数据结构说明
| 参数名称 | 参数类型 | 描述 | 示例值 |
|---|---|---|---|
| name | String | Bucket名称 | bucket |
| prefix | String | 查询的前缀 | |
| delimiter | String | 查询的结束符 | / |
| marker | String | 本次查询的起点 | |
| maxKeys | Integer | 请求返回的最大数目 | 1000 |
| isTruncated | Boolean | 指明是否查询 完整返回了；false-本次已经返回所有结果，true-本次还没有返回所有结果 | false |
| contents | List<Contents> | 返回的一个object的列表 |
Contents字段数据结构说明
| 参数名称 | 参数类型 | 描述 | 示例值 |
|---|---|---|---|
| key | String | Object名称 | my-image1.jpg |
| lastModified | String | 此Object最后一次被修改的时间 | 2009-10-12T17:51:30Z |
| eTag | String | Object的HTTP协议实体标签 | 0cce7caecc8309864f663d78d1293f98 |
| size | Integer | Object的内容的大小（字节数） | 124231 |
| storageClass | String | Object的存储类型，低频存储返回STANDARD_IA，冷存储返回COLD，归档存储返回ARCHIVE，标准存储返回STANDARD。 | COLD |
| owner | Owner | Object上传者的用户信息 |
Owner字段数据结构说明
| 参数名称 | 参数类型 | 描述 | 示例值 |
|---|---|---|---|
| id | String | Object上传者的用户id | 168bf6fd8fa74d9789f35a283a1f15e2 |
| displayName | String | Object上传者的名称 | mtd |
请求示例
GET /v1/bucketName_example?delimiter=delimiter_example&marker=marker_example&maxKeys=56&prefix=prefix_example
<公共请求头>
{ }响应示例
HTTP/1.1 200 OK
<公共响应头>
{
"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"
}错误码
请参考通用错误码