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

PutBucket

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

本页目录：

PutBucket 接口请求用于在指定地域下创建一个 Rapid Bucket。该接口不支持匿名请求，调用方必须使用带签名的请求；创建成功后，调用方所属主账号即为存储桶持有者。

注意事项

存储桶命名

通过本接口创建的存储桶，其完整 BucketName 必须为 <BucketName>-x--<APPID> 格式，例如 examplebucket-x--1250000000。桶名不符合该格式时，接口将返回 InvalidBucketName。

同名存储桶已存在

请求指向的存储桶已存在时，按其当前状态返回对应的 HTTP 409 错误：
存储桶可用：返回 BucketAlreadyExists。
存储桶正在创建中：返回 BucketCreating。
存储桶正在删除中：返回 BucketDeleting。

请求

请求端点

创建高性能桶时，请求的连接端点与 Host 头指向不同的域名，需分别设置：
项目
取值
说明
连接端点（Endpoint）
service.cosrapid.<Region>.myqcloud.com
请求实际建立连接、发送的目标地址（service 域名）
Host 头
<BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com
标识要创建的目标桶，服务端据此解析桶名与 APPID
说明：
创建桶请求统一发往 service 域名建立连接，而 Host 头需独立填写为目标桶域名。二者不一致是正常且必需的：服务端从 Host 头解析出待创建的 BucketName 与 APPID，若 Host 头未按桶域名格式填写，将返回 InvalidBucketName。

请求语法

PUT / HTTP/1.1
# 连接端点为 service 域名；Host 头独立填目标桶域名
Host: <BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
x-cos-vpc-id: <VpcId>
x-cos-subnet-id: <SubnetId>
x-cos-zone: <Zone>
Content-Length: 0
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

此接口无请求参数。

请求头部

除公共请求头部外，本接口还使用以下私有请求头部：
名称
描述
类型
是否必选
x-cos-vpc-id
存储桶绑定的 VPC ID
string
是
x-cos-subnet-id
存储桶绑定的子网 ID
string
是
x-cos-zone
存储桶所在可用区，例如 ap-guangzhou-3
string
是
说明：
上述三个头部任一缺失或取值为空时，接口返回 InvalidArgument。

请求体

该请求的请求体为空。

响应

响应头部

仅返回 公共响应头部，本接口无私有响应头部。

响应体

请求成功，响应体为空。

错误码

除遵循统一的错误响应和错误码（详情请参见 错误码 文档）外，本接口还可能返回以下错误：
错误码
描述
HTTP 状态码
InvalidArgument
必需头部缺失或取值非法
400
InvalidBucketName
BucketName 格式非法（非 <BucketName>-x--<APPID> 格式等）
400
BucketAlreadyExists
存储桶已存在，存储桶名不可用
409
BucketCreating
存储桶正在创建中，资源尚未就绪
409
BucketDeleting
存储桶正在删除中，资源正在清理
409

实际案例

请求

PUT / HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Fri, 13 Oct 2023 09:13:10 GMT
x-cos-vpc-id: vpc-abcdefgh
x-cos-subnet-id: subnet-abcdefgh
x-cos-zone: ap-guangzhou-3
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1484813288;32557709288&q-key-time=1484813288;32557709288&q-header-list=content-length;date;host;x-cos-subnet-id;x-cos-vpc-id;x-cos-zone&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Length: 0
Date: Fri, 13 Oct 2023 09:13:10 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

中国站