文档中心

对象存储

请输入

桶基础操作

ListObjects

功能描述

该接口用于列举桶中的对象。

要调用此接口，您需要拥有对桶的读访问权限。每次请求返回桶的部分对象（单次请求最多 1000 个），可以使用请求参数作为选择标准来返回桶中对象的子集。

说明

为了获取更好的用户体验，我们建议您在开发应用程序时优先使用新版本的 ListObjectsV2 接口。同时为了保持向后兼容性，TOS 会继续支持 ListObjects。

请求消息样式

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
delimiter	Query	String	否	-	对对象名进行分组的字符。通常使用 / 作为分组字符。
encoding-type	Query	String	否	url	指定对返回的内容进行编码的编码类型，取值说明如下： url：进行 URLEncode，遵循 application/x-www-form-urlencoded 标准。
max-keys	Query	Integer	否	100	返回对象的最大数量。默认值为 1000，取值范围为 1 ~ 1000，即一次请求最多返回 1000 个对象。
prefix	Query	String	否	abc	列举指定前缀的对象。
marker	Query	String	否	test.txt	列举对象的起始位置。设定从该值之后按字母排序返回对象列表。通常为上次请求返回体的 NextMarker值。

请求元素

该请求中无请求消息元素。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

名称	参数类型	示例值	说明
Name	String	test-bucket	桶名。
Prefix	String	abc	请求中带入的 prefix 参数。
Marker	String	abc	请求中带入的 marker 参数。
MaxKeys	Integer	100	请求中带入的 max-keys 参数。
Delimiter	String	d	请求中带入的 delimiter 参数。
EncodingType	String	url	请求中带入的 encoding-type 参数。
IsTruncated	Bool	true	返回的结果是否被截断，取值说明如下： false：已返回全部结果。 true：还有结果未返回。
NextMarker	String	abcd	如果结果未完全返回，标识下次请求的 marker 值。
CommonPrefixes	Array	[{"Prefix": "abcd"}]	请求中带 delimiter参数时，返回的响应中包含 CommonPrefixes分组信息。该元素标识以 delimiter结尾，并有共同前缀的对象名称的集合。
Contents	Array	-	对象信息的根节点。
Key	String	abcde	对象名。父节点为 Contents。
LastModified	String	2024-06-06T07:15:20.000Z	对象的最后修改时间。父节点为 Contents。
ETag	String	"32185e15494ca8e0eedf12bd218787f6"	在创建每个对象的时候生成，唯一标识一个对象的内容。父节点为 Contents。
Size	Integer	4813	对象大小，单位为字节。父节点为 Contents。
StorageClass	String	STANDARD	对象存储类型，取值说明如下： STANDARD：标准存储。 IA：低频访问存储。 INTELLIGENT_TIERING：智能分层存储。 ARCHIVE_FR：归档闪回存储。 ARCHIVE：归档存储。 COLD_ARCHIVE：冷归档存储。 DEEP_COLD_ARCHIVE：深度冷归档存储。说明深度冷归档目前处于邀测状态，如您需要使用该存储类型，请联系客户经理。父节点为 Contents。
Type	String	Appendable	对象为非 Normal 对象时，会返回此元素，取值说明如下： Appendable：该对象为追加写接口上传的对象。 Symlink：该对象为软链接对象。父节点为 Contents。
HashCrc64ecma	String	2217460101204276403	表示该对象的 64 位 CRC 值。该 64 位 CRC 根据 ECMA-182 标准计算得出。说明对 TOS 服务端支持 64 位 CRC 校验前创建的对象，则该消息头不会出现在响应消息中。父节点为 Contents。
Owner	Object	-	对象所有者。父节点为 Contents。
ID	String	1234567890	账号 ID。父节点为 Owner。
DisplayName	String	test-owner-name	账号名。父节点为 Owner。
ServiceManagedBy	String	Ark	对象托管服务标识。若对象由内部云服务托管管理，则返回对应服务名；否则该字段为空或省略。托管对象通常仅允许同一托管服务执行受限修改操作。父节点为 Contents。

请求示例

响应示例

最近更新时间：2026.10.21 16:29:33

这个页面对您有帮助吗？

有用

无用