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

PutBucketPolicy

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

本页目录：

PutBucketPolicy 接口请求用于向存储桶写入授权策略。授权策略由若干条 statement 组成，描述允许或拒绝哪些账号对该存储桶执行哪些操作。
每次调用本接口将整体覆盖该存储桶上已存在的全部策略，请求体需提交完整的目标策略集合。

请求

请求语法

PUT /?policy HTTP/1.1
Host: <BucketName>-x--<APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Content-Type: application/json
Content-Length: <Length>
Authorization: <Auth String>

<Policy JSON Body>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

参数名称
描述
类型
是否必选
policy
用于声明本次请求操作的是存储桶策略，固定为空串。
string
是

请求头部

此接口仅使用 公共请求头部，无私有请求头部。请求体为 JSON，需将 Content-Type 设置为 application/json。

请求体

请求体为 JSON 文本，结构如下：
{
    "version": "2.0",
    "statement": [
        {
            "sid": "string",
            "effect": "allow",
            "action": ["name/cos:GetObject"],
            "resource": [
                "qcs::cosrapid:<Region>:uid/<APPID>:<BucketName>-x--<APPID>/*"
            ],
            "principal": {
                "qcs": [
                    "qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
                ]
            },
            "condition": {}
        }
    ]
}
字段说明：
节点名称
父节点
描述
类型
是否必选
version
无
策略版本号，固定为 2.0
string
是
statement
无
策略 statement 数组，描述本次写入的全部授权条目
Container 数组
是
sid
statement
statement 的标识符。同一存储桶下用于区分不同条目；省略时由服务端自动生成
string
否
effect
statement
授权效果，取值为 allow 或 deny
string
是
action
statement
被授权的操作列表，元素形如 name/cos:<ActionName>，例如 name/cos:GetObject、name/cos:PutObject、name/cos:HeadBucket 等
string 数组
是
resource
statement
被授权的资源列表。每个元素必须形如 qcs::cosrapid:<Region>:uid/<APPID>:<BucketName>-x--<APPID>/*，且 <Region> 和 <BucketName>-x--<APPID> 必须与请求 Host 中的存储桶完全一致，否则返回 InvalidArgument
string 数组
是
principal
statement
被授权的账号。键为 qcs，值的元素形如 qcs::cam::uin/<OwnerUin>:uin/<SubUin>，表示腾讯云账号（含子账号）；可使用 anyone 替换 <SubUin> 部分以表示匿名访问
map[string][]string
是
condition
statement
生效条件，键为条件运算符，值为条件键到取值列表的映射；留空表示无附加条件
map
否

响应

响应头部

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

响应体

请求成功，响应体为空。

错误码

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

实际案例

请求

PUT /?policy HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Fri, 13 Oct 2023 09:13:10 GMT
Content-Type: application/json
Content-Length: 428
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1484813288;32557709288&q-key-time=1484813288;32557709288&q-header-list=date;host&q-url-param-list=policy&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
    "version": "2.0",
    "statement": [
        {
            "sid": "grant-getobject",
            "effect": "allow",
            "action": ["name/cos:GetObject"],
            "resource": [
                "qcs::cosrapid:ap-guangzhou:uid/1250000000:examplebucket-x--1250000000/*"
            ],
            "principal": {
                "qcs": ["qcs::cam::uin/100000000001:uin/100000000011"]
            }
        }
    ]
}

响应

HTTP/1.1 204 No Content
Connection: keep-alive
Date: Fri, 13 Oct 2023 09:13:10 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

中国站