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

查询存储桶

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

本页目录：

查询一个高性能桶是否存在以及当前调用方是否有权限访问（HEAD Bucket）。目标桶由 Bucket 参数指定，结果以 HTTP 状态码及响应头部呈现，无响应体。

注意事项

HTTP 状态码可用于区分结果：200表示桶存在且有权限，403表示请求未获授权，不能据此判断桶是否存在，404表示桶不存在。
返回的响应头字典保留服务端原始头名和值，同时提供小写别名，可按 x-cos-bucket-status 等小写键读取。
查询桶属于控制面接口，使用基础凭证签名，不走 session。

请求

方法原型

def head_bucket(self, Bucket, **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
待查询的高性能桶完整名称，格式为 <BucketName>-x--<APPID>
string
是
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回值为响应头部字典：
参数名称
参数描述
类型
响应头 dict
成功时返回响应头部字典，可通过 x-cos-bucket-status、x-cos-owner-uin、x-cos-vpc-id、x-cos-subnet-id、x-cos-zone、x-cos-creation-date 等键读取桶状态与网络信息
dict
桶存在且有权限返回200；无权限返回403；不存在返回404。

错误码

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

实际案例

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

# 高性能桶经 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'

# 桶存在且有权限时返回响应头字典；无权限或不存在时抛出 CosServiceError。
try:
    resp = client.head_bucket(Bucket=bucket)
    print('bucket status: %s' % resp.get('x-cos-bucket-status'))
except CosServiceError as e:
    print('HeadBucket failed, status: %s, code: %s' % (
        e.get_status_code(), e.get_error_code()))

中国站