帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>对象操作>列举对象

列举对象

最近更新时间：2026-10-21 18:34:07
我的收藏

本页目录：

列举高性能桶中的对象（GET Bucket），支持指定目录、列出当前层级内容并分页翻页。对高性能桶发起请求时，SDK 自动完成会话鉴权。高性能桶使用目录语义列举。

注意事项

高性能桶使用目录语义列举，Delimiter 为空时 SDK 仅对高性能桶规范化为 /，普通桶仍保留原来的空 delimiter 行为。
非空 Prefix 必须以 / 结尾，不支持按任意字符串前缀递归列举。
分页时保持 Prefix 不变，把返回的 NextMarker 直接作为下一次的 Marker。高性能桶的游标是当前目录内的相对名字，不要从 Contents.Key 推导或额外拼接 Prefix。
服务端对名称与游标使用 query 编码：空格编码为 +，字面加号编码为 %2B。SDK 默认按该规则解码后返回（+ 还原为空格，%2B 还原为字面加号，百分号只解码一次）；显式传入 EncodingType='url' 时保留编码，调用方应使用 urllib.parse.unquote_plus 解码名称及 Key/Marker 后再使用，不要使用 unquote 等通用 URL 解码，否则 + 不会还原为空格。
列举对象属于数据面接口，SDK 使用 session 临时凭证签名。

请求

方法原型

def list_objects(self, Bucket, Prefix="", Delimiter="", Marker="", MaxKeys=1000,
                 EncodingType="", **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
高性能桶完整名称，格式为 <BucketName>-x--<APPID>
string
是
Prefix
待列举的目录前缀；非空值须以 / 结尾，仅列举该目录当前层级
string
否
Delimiter
分隔符，高性能桶按目录语义列举；为空时 SDK 自动规范化为 /
string
否
Marker
当前目录内的相对名称游标；使用上一页的 NextMarker，不拼接 Prefix
string
否
MaxKeys
单次返回的最大对象数，取值范围 1~1000，默认 1000
int
否
EncodingType
返回结果的编码方式，可选值：url
string
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

下面是一页最多返回2项且需继续翻页的返回示例；文件与子目录合计2项：
{
    'Prefix': 'photos/',
    'NextMarker': 'sub',
    'MaxKeys': '2',
    'IsTruncated': 'true',
    'Contents': [
        {'Key': 'photos/a.jpg', 'ETag': '...', 'Size': '1024',
         'LastModified': '2023-10-13T09:13:10Z'},
        # ...
    ],
    'CommonPrefixes': [
        {'Prefix': 'photos/sub/'},
        # ...
    ],
}
参数名称
参数描述
类型
Prefix
本次列举使用的前缀
string
Marker
本次列举的起始标记
string
NextMarker
当前目录内的相对名称游标；IsTruncated 为 true 时原样用于下一次 Marker
string
MaxKeys
本次列举的最大对象数
string
IsTruncated
是否需要继续翻页；下一页可能为空，直到返回 false 为止
string
Contents
对象列表，每项含 Key、ETag、Size、LastModified 等
list
CommonPrefixes
使用分隔符时聚合出的公共前缀（相当于子目录）
list

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码文档。

实际案例

# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig, CosS3Client

# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。
config = CosConfig(
    Scheme='http',
    Region='ap-guangzhou',
    SecretId=os.environ['COS_SECRET_ID'],
    SecretKey=os.environ['COS_SECRET_KEY'],
    Token=os.environ.get('COS_SECURITY_TOKEN'),
    EnableRapidDomain=True)
client = CosS3Client(config)

bucket = 'examplebucket-x--1250000000'
marker = ''
while True:
    # 非空 Prefix 必须以 / 结尾；分页时保持 Prefix 不变。
    resp = client.list_objects(
        Bucket=bucket, Prefix='photos/', Marker=marker, MaxKeys=100)
    contents = resp.get('Contents') or []
    if isinstance(contents, dict):
        contents = [contents]
    for obj in contents:
        print('Key: %s, Size: %s' % (obj['Key'], obj.get('Size')))
    if resp.get('IsTruncated') != 'true':
        break
    marker = resp.get('NextMarker', '')
print('ListObjects OK')

中国站