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

创建存储桶

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

本页目录：

在指定地域创建高性能桶。创建时需要提供 VPC ID、子网 ID 和可用区，可使用命名参数或 Metadata 请求头。

注意事项

要创建的目标桶名由 Bucket 参数指定，格式为 <BucketName>-x--<APPID>。
高性能桶的三个网络参数合并后必须齐全非空，否则 SDK 在发送请求前本地报错；同名头取值冲突同样本地报错。
命名参数仅用于高性能桶，普通桶传入非 None 值会在本地报错；普通桶原有 Metadata 行为保持不变，其他接口也不新增这些参数。
桶名在同一地域内需全局唯一。重复创建已存在的桶时，按其当前状态返回对应的 HTTP 409 错误：桶可用返回 BucketAlreadyExists，创建中返回 BucketCreating，删除中返回 BucketDeleting。
创建桶属于控制面接口，使用基础凭证签名，不走 session。

请求

调用形式

client.create_bucket(Bucket=bucket, VpcId=vpc_id,
                     SubnetId=subnet_id, Zone=zone)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
待创建的高性能桶完整名称，格式为 <BucketName>-x--<APPID>，例如 examplebucket-x--1250000000
string
是
VpcId
高性能桶绑定的 VPC ID，例如 vpc-xxxxxxxx
string
与 Metadata 合并后必填
SubnetId
高性能桶绑定的子网 ID，例如 subnet-xxxxxxxx
string
与 Metadata 合并后必填
Zone
高性能桶所在可用区，例如 ap-guangzhou-3
string
与 Metadata 合并后必填
kwargs
可选请求参数，使用本文列出的参数；可用 Metadata 传入上述三个网络头
dict
否
VpcId / SubnetId / Zone 对应 x-cos-vpc-id / x-cos-subnet-id / x-cos-zone 请求头：
命名参数为 None 表示未提供，允许由 Metadata 补齐；两者会按头名大小写不敏感合并。
合并后三个字段的有效值必须齐全且非空，缺失、空字符串或纯空白值会在发送请求前本地报错。
同名头取值冲突时本地报错，不静默覆盖。
Metadata 的键是完整 HTTP 头名，不会自动添加 x-cos-meta- 前缀。
命名参数仅用于高性能桶；普通桶传入非 None 值会在本地报错。

响应

参数名称
参数描述
类型
None
创建请求被受理时无返回内容，对应 HTTP 200
None
返回 None 只表示创建请求已受理，不代表存储桶已可用。请使用 head_bucket 查询 x-cos-bucket-status，待服务端报告 Available 后再进行对象操作。

错误码

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

实际案例

# -*- 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'

# 使用命名参数创建桶。
client.create_bucket(
    Bucket=bucket,
    VpcId='vpc-xxxxxxxx',
    SubnetId='subnet-xxxxxxxx',
    Zone='ap-guangzhou-3')

# 创建请求受理后，轮询 x-cos-bucket-status，待 Available 后再进行对象操作。
status = client.head_bucket(Bucket=bucket).get('x-cos-bucket-status')
print('bucket status: %s' % status)
如需使用 Metadata，用下面的调用替换上面的创建调用；不要对同一桶连续执行两次创建：
client.create_bucket(
    Bucket=bucket,
    Metadata={
        'x-cos-vpc-id': 'vpc-xxxxxxxx',
        'x-cos-subnet-id': 'subnet-xxxxxxxx',
        'x-cos-zone': 'ap-guangzhou-3',
    })

中国站