帮你快速理解、总结文档立即下载

创建存储桶

最近更新时间:2026-10-21 18:34:06
本文档已由 AI 辅助审校
我的收藏

功能说明

在指定地域创建一个高性能桶(PUT Bucket)。创建桶请求发往 service 域名,要创建的目标桶名通过 client.Host 单独指定。高性能桶创建时必须指定 VPC 网络相关信息,通过自定义请求头传入。

方法原型

func (s *BucketService) Put(ctx context.Context, opt *BucketPutOptions) (*Response, error)

参数说明

参数名称
参数描述
类型
是否必选
ctx
请求上下文,用于控制超时与取消
context.Context
是
opt
创建桶选项,VPC 网络信息通过 XOptionHeader 传入
*BucketPutOptions
是
高性能桶创建时必须携带以下自定义请求头(通过 opt.XOptionHeader 设置),缺任意一个都会返回 InvalidArgument:
请求头
参数描述
类型
是否必选
x-cos-vpc-id
VPC ID
string
是
x-cos-subnet-id
子网 ID
string
是
x-cos-zone
可用区
string
是

返回结果说明

参数名称
参数描述
类型
*Response
响应对象,创建成功状态码为 200
*cos.Response
error
错误信息,成功时为 nil
error

使用案例

创建桶请求发往 service 域名,client.Host 指定要创建的目标桶名(<BucketName>-x--<APPID>),VPC 网络信息通过 XOptionHeader 传入。
package main

import (
"context"
"log"
"net/http"
"net/url"
"os"
"time"

"github.com/tencentyun/cos-go-sdk-v5"
)

func main() {
// 请求发往 service 域名。
su, _ := url.Parse("https://service.cosrapid.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: su, ServiceURL: su}

base := &cos.AuthorizationTransport{
SecretID: os.Getenv("SECRETID"),
SecretKey: os.Getenv("SECRETKEY"),
}
c := cos.NewClient(b, &http.Client{
Transport: cos.NewRapidCredentialTransport(base),
Timeout: 30 * time.Second,
})

// 用 client.Host 单独指定要创建的目标桶名。
c.Host = "examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com"

// VPC 网络信息通过自定义请求头传入。
header := &http.Header{}
header.Set("x-cos-vpc-id", "vpc-xxxxxxxx")
header.Set("x-cos-subnet-id", "subnet-xxxxxxxx")
header.Set("x-cos-zone", "ap-guangzhou-3")

ctx := context.Background()
_, err := c.Bucket.Put(ctx, &cos.BucketPutOptions{XOptionHeader: header})
if err != nil {
log.Fatalf("PutBucket failed: %v", err)
}
log.Println("bucket created")
}

注意事项

创建桶请求发往 service 域名 https://service.cosrapid.<Region>.myqcloud.com,要创建的目标桶名由 client.Host 单独指定,格式为 <BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com。
x-cos-vpc-id、x-cos-subnet-id、x-cos-zone 为必需请求头,缺任意一个都会返回 InvalidArgument。
桶名在同一地域内需全局唯一,重复创建已存在的桶会返回错误。
错误处理方式请参见 异常处理。