ListObjects
更新时间：2026-09-18
接口描述
本接口用于获得指定 Bucket 的 Object 信息列表。请求需要通过 BOS 鉴权，鉴权信息通过 Authorization 请求头传递。
本接口支持通过 prefix 限定 Object key 前缀，通过 marker 和 maxKeys 分页列举，通过 delimiter 实现文件夹逻辑。
请求
请求结构
Http
1GET / HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Date: {Date}
4Authorization: {AuthorizationString}请求头域
无特殊 Header 参数。请求需包含 Host、Date、Authorization 等公共请求 Header。
请求参数
以下参数均为 Query 参数；本接口无 Path 参数和 Body 参数。
| 参数名（字段） | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
| delimiter | String | Query | 否 | 分隔符，主要用于实现 list 文件夹逻辑。指定 delimiter 时，BOS 会将匹配到的 Object 名称按照从 prefix 到第一个 delimiter 的规则截取，并将截取后的字符串去重后作为 commonPrefixes 返回。delimiter 长度限制为 1 个字符。 |
| marker | String | Query | 否 | Object 按字母序排列，从 marker 之后的第一个 Object 开始返回。 |
| maxKeys | Integer | Query | 否 | 返回 Object 列表的最大长度，默认值为 1000；最大值为 1000。若指定值大于 1000，则按 1000 处理。 |
| prefix | String | Query | 否 | Key 前缀，限定返回的 Object key 必须以此前缀开头。 |
响应
响应头域
无特殊 Header 参数。响应中的 x-bce-request-id 可用于定位请求。
响应参数
| 名称 | 类型 | 描述 |
|---|---|---|
| commonPrefixes | Array | 仅当指定 delimiter 时返回此项。 |
| commonPrefixes[].prefix | String | 匹配以 prefix 开始到第一次出现 delimiter 字符之间的 Object，作为一组元素返回。 |
| contents | Array | 返回的 Object 列表。 |
| contents[].key | String | Object 名称。 |
| contents[].lastModified | Date | 此 Object 最后一次被修改的时间。 |
| contents[].eTag | String | Object 的 HTTP 协议实体标签。 |
| contents[].size | Integer | Object 内容的大小，单位为字节。 |
| contents[].storageClass | String | Object 的存储类型。可选值：STANDARD（标准存储）、STANDARD_IA（低频存储）、COLD（冷存储）、ARCHIVE（归档存储）。 |
| contents[].owner | Object | Object 上传者的用户信息。 |
| contents[].owner.id | String | Object 上传者的用户 ID。 |
| contents[].owner.displayName | String | Object 上传者的名称。 |
| delimiter | String | 本次查询使用的分隔符。 |
| isTruncated | Boolean | 指明查询结果是否完整返回；false 表示本次已返回所有结果，true 表示本次未返回所有结果。 |
| maxKeys | Integer | 请求返回的最大数目。 |
| marker | String | 本次查询的起点。 |
| name | String | Bucket 名称。 |
| nextMarker | String | 当 isTruncated 为 true 时返回此项，作为下次查询 marker 的值。 |
| prefix | String | 查询的前缀。 |
注意事项
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/。
示例
请求示例
示例 1：递归列举所有 Object
Http
1GET / HTTP/1.1
2Host: bucket.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: <AuthorizationString>示例 1：递归列举所有 Object
Http
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 ]
37}示例 2：列举根目录下的部分文件和子目录
Http
1GET /?delimiter=/ HTTP/1.1
2Host: bucket.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: <AuthorizationString>响应示例
示例 2：列举根目录下的部分文件和子目录
Http
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 {
28 "prefix": "photos/"
29 },
30 {
31 "prefix": "mtd/"
32 }
33 ]
34}评价此篇文章