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

查询存储桶列表

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

本页目录：

列出调用方主账号在指定地域下的所有高性能桶（GET Service，即 ListBuckets）。查询存储桶列表请求发往 service 域名，该域名不带存储桶名前缀，地域由 service 域名决定。

注意事项

查询存储桶列表请求发往 service 域名 service.cosrapid.<Region>.myqcloud.com，该域名不带存储桶名前缀；EnableRapidDomain=True 时由 SDK 自动设置。
本接口仅返回 service 域名对应 <Region> 下的存储桶；如需查看其他地域的存储桶，请更换 Region 后分别调用。
当 IsTruncated 为 true 时，将响应中的 NextMarker 作为下次请求的 Marker 传入，直到 IsTruncated 为 false。
本接口只能列出签名密钥所属账号的存储桶，属于控制面接口，使用基础凭证签名，不走 session。

请求

方法原型

def list_buckets(self, TagKey=None, TagValue=None, Region=None, CreateTime=None,
                 Range=None, Marker="", MaxKeys=2000, **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Marker
分页游标，取值为上一次响应的 NextMarker；首次请求无需携带
string
否
MaxKeys
单次返回的最大存储桶数量，取值范围1~2000，默认2000
int
否
kwargs
可选请求参数，使用本文列出的参数
dict
否
说明：
高性能桶列举请仅使用 Marker 与 MaxKeys。TagKey/TagValue、Region、CreateTime/Range 等普通 COS 桶过滤参数不属于高性能桶契约。

响应

返回值为解析后的 dict，对应 XML 根节点 ListAllMyBucketsResult：
{
    'Owner': {'ID': '...', 'DisplayName': '...'},
    'Marker': '',
    'NextMarker': '',
    'IsTruncated': 'false',
    'Buckets': {
        'Bucket': [
            {
                'Name': 'examplebucket-x--1250000000',
                'Location': 'ap-guangzhou',
                'CreationDate': '2023-10-13T09:13:10Z',
                'VpcId': 'vpc-abcdefgh',
                'SubnetId': 'subnet-abcdefgh',
                'Zone': 'ap-guangzhou-3',
                'Status': 'Available',
            },
            # ...
        ]
    },
}
参数名称
参数描述
类型
Owner
存储桶持有者信息，含 ID、DisplayName
dict
Marker
本次请求使用的分页游标
string
NextMarker
下一页分页游标，仅当 IsTruncated 为 true 时非空
string
IsTruncated
是否仍有未列举完的存储桶，true 表示存在下一页
string
Buckets.Bucket
存储桶列表，每项含 Name、Location、CreationDate、VpcId、SubnetId、Zone、Status
list
Bucket.Name
存储桶完整名称，格式为 <BucketName>-x--<APPID>
string
Bucket.Location
存储桶所在地域
string
Bucket.CreationDate
存储桶创建时间，ISO 8601 格式
string

错误码

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

实际案例

查询存储桶列表请求发往 service 域名。EnableRapidDomain=True 时 SDK 已自动把 ServiceDomain 设为 service.cosrapid.<Region>.myqcloud.com。
# -*- 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)

# 分页列举该地域下的全部高性能桶。
marker = ''
while True:
    res = client.list_buckets(Marker=marker, MaxKeys=2000)
    buckets = (res.get('Buckets') or {}).get('Bucket') or []
    if isinstance(buckets, dict):
        buckets = [buckets]
    for bucket in buckets:
        print('bucket: %s, region: %s, created: %s' % (
            bucket['Name'], bucket.get('Location'), bucket.get('CreationDate')))
    if res.get('IsTruncated') != 'true':
        break
    marker = res.get('NextMarker', '')

中国站