OBS管理控制台单击桶名称进入对象列表页，默认对象名按照字典序排序来列举对象。您也可以根据实际场景需求，按照“大小”和“最后修改时间”进行排序列举对象。
工作原理
在OBS列举桶内对象中，各参数（参数名以API为准）通过以下逻辑协同工作，以实现精准、可控的数据读取：
prefix用于界定检索范围，系统仅返回以该值开头的对象名，起到“划定选区”的作用。如图1所示，当prefix设置为“test/”时，列举结果则返回包含该前缀的对象test/a、test/b、test/c。
图1 列举条件为prefix的工作原理说明 
其中marker负责设定读取起点，系统将从字典序大于该值的对象开始列举，从而实现断点续传。如图2所示，当marker设置为“test/b”时，列举结果则返回“test/b”后面的对象test/c、logs/2026。
图2 列举条件为marker的工作原理说明 
关于目录展示方式，由delimiter分隔符（通常为 /）决定：
- 若未指定delimiter，系统将递归展开所有层级的子目录对象；
- 若未指定prefix，只指定delimiter=/，从对象名的首字符到第一次出现/的对象名会被分成一组，形成一条CommonPrefixes，如图3所示；若指定prefix=t，delimiter=/，从对象名首字母t到第一次出现/字符串的对象名会被分成一组，形成一条CommonPrefixes，如图4。
图3 列举条件为只指定delimiter的工作原理说明 
图4 列举条件为指定prefix和delimiter的工作原理说明 
此外max-keys作为硬性约束，限制单次请求返回的最大条目数（上限1000）。一旦结果超过此限制，响应将标记 IsTruncated=true，并通过 NextMarker告知下一次请求的起始位置，以此完成分页列举。如图5所示，当max-keys为2时，单次返回的列举结果为test/a、test/b。
图5 列举条件为max-keys的工作原理说明 
如需深入了解各参数的详细定义、使用限制及响应示例，请参见使用SDK。
权限控制
只有桶拥有者和被授予obs:bucket:ListBucket（未开启多版本）、obs:bucket:ListBucketVersions（开启或暂停多版本）权限的用户才能列举对象。您可以使用IAM或桶策略进行授权，授权操作请参见创建IAM自定义策略或自定义创建桶策略。
约束与限制
- OBS不支持列举指定页数的对象。
- OBS不支持通过时间排序找到某个时间上传的对象，只能通过按前缀搜索找到目标对象。
- 对象列表页面的“大小”和“最后修改时间”仅对当前页面的对象进行排序。
使用方式
OBS支持通过控制台、API、SDK、obsutil方式列举对象，不支持使用OBS Browser+方式列举对象。
使用OBS控制台
- 在OBS管理控制台左侧导航栏选择“桶列表”。
- 在桶列表中，单击待操作的桶，进入“对象”页面。
- 当前页面将分页显示桶内的所有对象，默认每页显示50个对象。
- （可选）如果桶已开启了多版本控制功能，那么可以通过对象列表上方的“历史版本”开关来控制对象列表是否展示历史版本对象：
- 开关打开：对象列表展示当前版本对象和历史版本对象（包含已删除对象）。
- 开关关闭：对象列表仅展示当前版本对象。
使用命令行工具obsutil
命令结构：
- Windows操作系统
obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- macOS/Linux操作系统
./obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
运行示例：
- 示例2：以Windows操作系统为例，运行obsutil ls obs://bucket-test2，查询桶内对象。
obsutil ls obs://bucket-test2
Start at 2024-09-30 08:21:06.6300221 +0000 UTC
Listing objects .
Object list:
key LastModified Size StorageClass ETag
obs://bucket-test2/123 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/1_2-3.txt 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/1_2-3_33.txt 2022-03-29T09:17:51Z 200B standard "dcf204c11d791255adc63e61763c2426"
obs://bucket-test2/新建文本文档.txt
2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
Total size of bucket: 200B
Folder number: 0
File number: 4 - 示例3：以Windows操作系统为例，运行obsutil ls obs://bucket-test2/prefix，查询桶内以prefix为前缀的对象。
obsutil ls obs://bucket-test2/prefix
Start at 2024-09-30 08:24:36.7057148 +0000 UTC
Listing objects .
Object list:
key LastModified Size StorageClass ETag
obs://bucket-test2/prefix 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/prefix2 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
Total size of prefix [prefix]:: 0B
Folder number: 0
File number: 2
- 更多运行示例，请参见常见示例。
参数说明：
| 参数 | 约束 | 描述 |
| bucket | 必选 | 桶名。 |
| prefix | 可选 | 列举对象时的对象名前缀。 |
| s | 附加参数，可选 | 以精简格式显示查询结果。 |
| d | 附加参数，可选 | 仅列举当前目录下的对象和子目录，而非递归列举所有对象和子目录。 对于并行文件系统目录，大数据场景下（目录层级深、目录下文件多）的列举，建议使用此参数限制列举范围。 |
| v | 附加参数，可选 | 列举桶内多版本对象，列举结果包含最新版本的对象和历史版本的对象（如果有）。 |
| marker | 附加参数，可选 | 列举桶内对象的起始位置，返回结果是对象名按照字典序排序后该参数以后的所有对象。 |
| versionIdMarker | 附加参数，可选，必须与v和marker配合使用 | 列举桶内多版本对象的起始位置，返回结果是对象名和版本号按照字典序排序后该参数以后的所有对象。 说明： 如果versionIdMarker不是marker的一个版本号，则该参数无效。 |
| bf | 附加参数，可选 | 列举结果中字节数的显示格式。支持的值： 说明： 如果未设置该参数，则列举结果中字节数的显示格式由配置文件中的humanReadableFormat参数决定。 |
| du | 附加参数，可选 | 快速返回所列举对象的总大小，不显示具体的对象信息，可与其他参数配合使用。 |
| fs | 附加参数，可选 | 是否使用并行文件系统的列举方式，如果桶是并行文件系统，推荐加上该参数。 注意： - 该列举方式会因为目录结构，耗时会差别很大。
- 该参数开启后，会忽略marker和limit值，统计桶或者并行文件系统或者指定目录的大小。
- Util 5.5.12版本及以上支持该参数。
|
| limit | 附加参数，可选 | 列举结果的最大个数，小于等于0表示列举所有结果，不设置时的默认值为1000。 说明： 如果桶内对象较多，建议设置该值限制每次列举的对象个数，列举结束后，如果仍有对象，会在结果中返回下次请求的marker和versionIdMarker，用于继续列举剩余的对象。 |
| format | 附加参数，可选 | 指定以自定义格式打印列举结果。当前仅支持值[default]，指定列举结果在一行显示。 |
| bucket-cname | 附加参数，可选 | 指定桶绑定的自定义域名 |
| config | 附加参数，可选 | 运行当前命令时的自定义配置文件。可支持的配置参数请参考配置参数说明。 |
| e | 附加参数，可选 | 指定终端节点。 |
| i | 附加参数，可选 | 指定用户的AK。 |
| k | 附加参数，可选 | 指定用户的SK。 |
| t | 附加参数，可选 | 指定用户的securitytoken。 |
响应结果：
表1 Object list和Versioning Object list响应结果参数说明（普通对象和多版本对象） | 字段名 | 描述 |
| Key | 对象名。 |
| VersionId | 对象的版本ID。如果桶开启或暂停多版本控制，列举桶内多版本对象时，响应结果会展示该参数。 |
| LastModified | 对象的最近一次修改时间。 |
| Size | 对象的大小。 |
| StorageClass | 对象的存储类型。支持的值： - standard：标准存储，访问时延低、吞吐量高，适用于有大量热点文件（平均一个月多次）或小文件（小于1MB）。
- warm：低频访问存储，可用性略低于standard，适用于不频繁访问（平均一年少于12次）但在需要时也要求快速访问数据的业务场景。
- cold：归档存储，安全、持久且成本极低，适用于很少访问（平均一年访问一次）数据的业务场景。
- deep-archive：深度归档存储，适用于长期不访问（平均几年访问一次）数据的业务场景，其成本相比归档存储更低，但相应的数据恢复时间将更长，一般为数小时。
|
| ETag | 对象的ETag值。对象的base64编码的128位MD5摘要。ETag可用于校验对象内容是否发生变化，但不能作为对象的唯一标识。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的ETag。 |
最佳实践
性能优化
- 设置单页展示对象数量：在网络良好情况下桶内单页展示对象总数设为最大值（默认1000），可以减少请求往返次数并提升列举效率；同时需评估内存承载能力，防止因单次返回数据过多导致客户端内存异常。
- 缓存目录结构：针对变更频率较低的对象，可缓存其列举结果，避免重复调用API，从而降低请求成本与延迟。
成本控制
若业务需定期执行全量对象盘点，强烈建议使用桶清单功能。相比实时列举，该功能成本更低且支持周期性输出，更适合进行全量分析与审计。
日志与监控
为帮助用户及时感知并处理列举对象操作，OBS提供了从实时感知到事后审计的完整管控能力。用户可以通过配置CTS追踪listObjects事件，或通过CES对列举桶内对象的行为进行监控（接口ID：LIST.BUCKET.OBJECTS），还可以开启REST.GET.BUCKET操作的桶日志功能，系统会记录该操作的详细日志，供用户审计或进一步分析。了解配置监控日志相关操作，请参见使用桶日志记录OBS日志信息。
