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

设置存储桶策略

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

功能说明

为高性能桶设置存储桶策略(PUT Bucket Policy),通过声明式的授权语句控制账号对桶及对象的访问权限。策略存储于 CAM,proxy 完成 COS 形态与 CAM 形态的转换。

方法原型

func (s *BucketService) PutPolicy(ctx context.Context, opt *BucketPutPolicyOptions) (*Response, error)

参数说明

type BucketPutPolicyOptions struct {
Statement []BucketStatement
Version string
Principal map[string][]string
}

type BucketStatement struct {
Principal map[string][]string
Action []string
Effect string
Resource []string
Condition map[string]map[string]interface{}
Sid string
}
参数名称
参数描述
类型
是否必选
ctx
请求上下文,用于控制超时与取消
context.Context
是
opt
桶策略内容
*BucketPutPolicyOptions
是
Statement
授权语句列表
[]BucketStatement
是
Version
策略语法版本,通常为 2.0
string
否
Principal
被授权者,key 仅支持 qcs 与 service;qcs 形如 qcs::cam::uin/<主账号uin>:uin/<子账号uin>
map[string][]string
是
Action
授权的操作列表,形如 name/cos:CreateSession、name/cos:GetObject
[]string
是
Effect
授权效果,取值 allow 或 deny(大小写不敏感)
string
是
Resource
授权作用的资源,需精确匹配当前请求的桶
[]string
是
Condition
生效条件,原样透传 CAM
map[string]map[string]interface{}
否
Sid
语句标识符
string
否

返回结果说明

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

使用案例

package main

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

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

func main() {
u, _ := url.Parse("https://examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
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,
})

ctx := context.Background()
opt := &cos.BucketPutPolicyOptions{
Version: "2.0",
Statement: []cos.BucketStatement{
{
Sid: "allow-get-and-session",
Effect: "allow",
Principal: map[string][]string{
"qcs": {"qcs::cam::uin/100000000001:uin/100000000011"},
},
Action: []string{
"name/cos:CreateSession",
"name/cos:GetObject",
},
Resource: []string{
"qcs::cosrapid:ap-guangzhou:uid/1250000000:examplebucket-x--1250000000/*",
},
},
},
}
_, err := c.Bucket.PutPolicy(ctx, opt)
if err != nil {
log.Fatalf("PutPolicy failed: %v", err)
}
log.Println("bucket policy set")
}

注意事项

Resource 必须精确匹配当前请求的桶,高性能桶的资源形态为 qcs::cosrapid:<Region>:uid/<APPID>:<BucketName>-x--<APPID>/*;指向其他桶、跨地域或通配 * 均会被拒绝(InvalidArgument)。
Principal 的 key 仅支持 qcs 与 service;qcs 形如 qcs::cam::uin/<主账号uin>:uin/<子账号uin>。
Effect 取值为 allow 或 deny;Action 原样透传 CAM。
PutPolicy 会以本次提交的策略整体覆盖桶上原有策略,而非增量合并,需提交完整的目标策略集合。
仅桶所有者可调用,非所有者调用返回 405 MethodNotAllowed。
错误处理方式请参见 异常处理。