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

快速入门

最近更新时间:2026-10-21 18:34:04
我的收藏
本文档介绍如何使用 Go SDK 访问高性能桶(Rapid Bucket),完成初始化客户端、创建访问会话以及上传下载对象等基础操作。

环境要求

Go 1.18 及以上版本。
已开通高性能桶服务,并已创建高性能桶;也可以按 Go SDK 创建存储桶 通过 SDK 创建。高性能桶的完整名称形如 <BucketName>-x--<APPID>,例如 examplebucket-x--1250000000。
已获取访问密钥 SecretId 和 SecretKey。建议使用子账号密钥并遵循最小权限原则。

安装 SDK

在项目中引入 COS Go SDK:
go get github.com/tencentyun/cos-go-sdk-v5
在代码中导入:
import "github.com/tencentyun/cos-go-sdk-v5"

鉴权说明

访问高性能桶时,统一使用 RapidCredentialTransport 包装底层基础凭证。它会在需要时自动调用 CreateSession 换取临时凭证并完成签名,临时凭证在有效期内自动缓存复用,底层基础凭证变更后自动重新签发,业务代码无需手动管理会话与临时凭证。
只需在初始化客户端时用 NewRapidCredentialTransport 包裹基础凭证,后续所有接口调用方式与普通 COS SDK 一致。

初始化客户端

访问高性能桶时,必须使用 NewRapidCredentialTransport 包裹底层基础凭证,并将其作为 http.Client 的 Transport 传入 NewClient:
package main

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

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

func main() {
// 高性能桶域名形如 https://<BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com
u, _ := url.Parse("https://examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}

// 底层基础凭证 transport,提供 SecretId / SecretKey。
// RapidCredentialTransport 用它签发 CreateSession,并继承其网络传输层。
base := &cos.AuthorizationTransport{
SecretID: os.Getenv("SECRETID"),
SecretKey: os.Getenv("SECRETKEY"),
}

// 关键:用 NewRapidCredentialTransport 包裹底层凭证,作为 http.Client.Transport。
c := cos.NewClient(b, &http.Client{
Transport: cos.NewRapidCredentialTransport(base),
Timeout: 30 * time.Second,
})

ctx := context.Background()
_ = ctx
_ = c
}
字段说明:
参数
描述
BucketURL
高性能桶访问域名,格式为 https://<BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com
AuthorizationTransport.SecretID
主账号或子账号的 SecretId
AuthorizationTransport.SecretKey
主账号或子账号的 SecretKey
NewRapidCredentialTransport
将基础凭证 transport 包裹为高性能桶专用 transport,自动完成会话鉴权
说明:
底层基础凭证 transport 除 AuthorizationTransport 外,也可使用 CVMCredentialTransport、StsCredentialTransport、CredentialTransport 等实现了 BaseTransport 接口的类型。

完整示例

以下示例演示初始化客户端后完成一次上传与下载。使用时将下面的代码替换上文 main 函数中 ctx := context.Background() 及其后的两行,并在 import 中补充 "fmt"、"io"、"log"、"strings":
ctx := context.Background()

// 上传对象。首次对高性能桶发起请求时,transport 会自动创建 session 并签名。
key := "quickstart/hello.txt"
_, err := c.Object.Put(ctx, key, strings.NewReader("hello rapid bucket"), nil)
if err != nil {
log.Fatalf("PutObject failed: %v", err)
}

// 下载对象。
resp, err := c.Object.Get(ctx, key, nil)
if err != nil {
log.Fatalf("GetObject failed: %v", err)
}
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Printf("object content: %s\\n", data)

后续操作

存储桶操作:创建存储桶、删除存储桶、查询存储桶、创建访问会话。
对象操作:上传对象、下载对象、删除对象、复制对象、重命名对象等。
分块上传操作:适用于大文件的分块上传。
存储桶策略:设置、获取、删除存储桶策略。
各接口的详细用法请参见对应文档。SDK 调用返回的错误处理方式请参见 异常处理。