tencent cloud

对象存储

动态与公告
产品动态
产品公告
产品简介
产品概述
功能概览
应用场景
产品优势
基本概念
地域和访问域名
规格与限制
产品计费
计费概述
计费方式
计费项
免费额度
计费示例
查看和下载账单
欠费说明
常见问题
快速入门
控制台快速入门
COSBrowser 快速入门
用户指南
创建请求
存储桶
对象
数据管理
批量处理
全球加速
监控与告警
运维中心
数据处理
内容审核
智能工具箱
数据工作流
应用集成
工具指南
工具概览
环境安装与配置
COSBrowser 工具
COSCLI 工具
COSCMD 工具
COS Migration 工具
FTP Server 工具
Hadoop 工具
COSDistCp 工具
HDFS TO COS 工具
GooseFS-Lite 工具
在线辅助工具
自助诊断工具
实践教程
概览
访问控制与权限管理
性能优化
使用 AWS S3 SDK 访问 COS
数据容灾备份
域名管理实践
图片处理实践
COS 音视频播放器实践
工作流实践
数据直传
内容审核实践
数据安全
数据校验
大数据实践
COS 成本优化解决方案
在第三方应用中使用 COS
迁移指南
本地数据迁移至 COS
第三方云存储数据迁移至 COS
以 URL 作为源地址的数据迁移至 COS
COS 之间数据迁移
Hadoop 文件系统与 COS 之间的数据迁移
数据湖存储
云原生数据湖
元数据加速
数据加速器 GooseFS
数据处理
数据处理概述
图片处理
媒体处理
内容审核
文件处理
文档处理
故障处理
获取 RequestId 操作指引
通过外网上传文件至 COS 缓慢
访问 COS 时返回403错误码
资源访问异常
POST Object 常见异常
API 文档
简介
公共请求头部
公共响应头部
错误码
请求签名
操作列表
Service 接口
Bucket 接口
Object 接口
批量处理接口
数据处理接口
任务与工作流
内容审核接口
云查毒接口
SDK 文档
SDK 概览
准备工作
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK
错误码
鸿蒙(Harmony) SDK
终端 SDK 质量优化
安全与合规
数据容灾
数据安全
访问管理
常见问题
热门问题
一般性问题
计费计量问题
域名合规问题
存储桶配置问题
域名和 CDN 问题
文件操作问题
日志监控问题
权限管理问题
数据处理问题
数据安全问题
预签名 URL 问题
SDK 类问题
工具类问题
API 类问题
服务协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表
文档对象存储实践教程访问控制与权限管理条件键说明及使用示例

条件键说明及使用示例

PDF
聚焦模式
字号
最后更新时间： 2025-10-09 14:41:22
在使用访问策略授予权限时，您可以指定策略的 生效条件，例如限制用户访问来源、上传文件的存储类型等。
本文档为您提供了在存储桶策略中使用对象存储（Cloud Object Storage，COS）条件键的常用示例，您可以在 生效条件 文档中查看 COS 支持的全部条件键和适用请求。
说明：
当您使用条件键编写策略时，请务必遵循最小权限原则，仅为适用请求（action）添加相应的条件键，避免在指定操作（action）时使用通配符“*”，导致请求失败，关于条件键的介绍，可参见 生效条件 文档。
当您使用访问管理 CAM 控制台创建策略时，请注意语法格式，version、principal、statement、effect、action、resource、condition 语法元素需保持全小写。

限制用户访问 IP（qcs:ip）

条件键 qcs:ip

使用条件键 qcs:ip 限制用户访问 IP，适用于所有请求。

示例：只允许指定 IP 来源的用户访问

以下策略示例描述为：允许属于主账号 ID 为100000000001（APPID 为1250000000）下的子账号 ID 100000000002，对北京地域的存储桶 examplebucket-bj 和广州地域的存储桶 examplebucket-gz 下的对象 exampleobject，在访问 IP 在 192.168.1.0/24 网段和 IP 为 101.226.100.185 或 101.226.100.186 时，拥有上传对象和下载对象的权限。
{
    "version": "2.0",
    "principal": {
        "qcs": [
            "qcs::cam::uin/100000000001:uin/100000000002"
        ]
    },
    "statement": [
        {
            "effect": "allow",
            "action": [
                "name/cos:PutObject",
                "name/cos:GetObject"
            ],
            "resource": [
                "qcs::cos:ap-beijing:uid/1250000000:examplebucket-bj-1250000000/*",
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-gz-1250000000/exampleobject"
            ],
            "condition": {
                "ip_equal": {
                    "qcs:ip": [
                        "192.168.1.0/24",
                        "101.226.100.185",
                        "101.226.100.186"
                    ]
                }
            }
        }
    ]
}

只允许访问对象的最新版本或者指定版本（cos:versionid）

请求参数 versionid

请求参数 versionid 表示对象的版本号，关于版本控制相关内容可查看 版本控制概述。您可以在下载对象（GetObject）、删除对象（DeleteObject）时使用请求参数 versionid 指定需要操作的对象版本。
不带 versionid 请求参数时，请求默认作用于对象的最新版本。
versionid 请求参数为一个空字符串时，等同于不带 versionid 请求参数时。
versionid 请求参数为字符串 "null" 的情况。对于一个存储桶在开启版本控制之前上传的对象，开启版本控制后，这批对象的版本号统一是字符串 "null"。

条件键 cos:versionid

条件键 cos:versionid 用于限制请求参数 versionid。

示例1：只允许用户获取指定版本号的对象

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，需要向其子用户（uin:100000000002）进行授权，仅允许子用户获取指定版本号的对象。
采用以下存储桶策略后，子用户（uin:100000000002）发起下载对象请求时，只有在携带了 versionid 参数，且 versionid 的值为版本号 “MTg0NDUxNTc1NjIzMTQ1MDAwODg” 时，请求才会成功。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ]
}
添加显式拒绝
当使用上述策略为子用户授予权限时，由于子用户可能通过其他途径获得没有任何条件的相同权限，范围更大的授权策略生效。例如，若子用户处于某个用户组中，主账户为用户组赋予了 GetObject 权限而没有附加任何条件，以上策略对版本号的限制将不起作用。
为了应对这种情况，您可以在上述策略的基础上，通过添加显式拒绝的策略（deny）来完成更严格的权限限制。下面这个 deny 策略的含义是，子用户发起下载对象请求时，若没有携带 versionid 参数，或 versionid 的版本号不是 “MTg0NDUxNTc1NjIzMTQ1MDAwODg”，这个请求将被拒绝。由于 deny 的优先级高于其他策略，因此添加显式拒绝可以最高程度地避免权限漏洞。
{
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ],
    "version":"2.0"
}

示例2：只允许用户获取最新版本的对象

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，需要限制其子用户（uin:100000000002）只能获取最新版本的对象。
由于在不携带请求参数 versionid 或 versionid 为空字符串时，GetObject 默认获取最新版本的对象。因此，我们可以在条件中使用 string_equal_if_exist：
1. 若不携带 versionid，默认按照 true 处理，命中 allow 条件，请求将被 allow。
2. 若请求参数 versionid 为空，即 “”，同样会命中 allow 策略，只对获取最新版本的对象的请求进行授权。
 "condition": {
     "string_equal_if_exist": {
         "cos:versionid": ""
     }
 }
添加显式拒绝后，完整的存储桶策略如下所示：
{
 "statement":[
     {
         "principal":{
             "qcs":[
                 "qcs::cam::uin/100000000001:uin/100000000002"
             ]
         },
         "effect":"allow",
         "action":[
             "name/cos:GetObject"
         ],
         "condition":{
             "string_equal_if_exist":{
                 "cos:versionid":""
             }
         },
         "resource":[
             "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
         ]
     },
     {
         "principal":{
             "qcs":[
                 "qcs::cam::uin/100000000001:uin/100000000002"
             ]
         },
         "effect":"deny",
         "action":[
             "name/cos:GetObject"
         ],
         "condition":{
             "string_not_equal":{
                 "cos:versionid":""
             }
         },
         "resource":[
             "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
         ]
     }
 ],
 "version":"2.0"
}

示例3：不允许用户删除开启版本控制前上传的对象

在开启版本控制前，您的存储桶中可能已上传了一部分对象，这些对象的版本号为“null”。有时候，您需要对这些对象开启额外的保护，例如，禁止用户对这些对象进行永久删除操作，也就是拒绝带版本号的删除操作。
下面这个存储桶策略示例，包含了两个策略：
1. 授权子用户使用 DeleteObject 请求删除存储桶中的对象。
2. 对 DeleteObject 请求的生效条件做了限制。当 DeleteObject 请求携带了请求参数 versionid，且 versionid 为"null"时，拒绝这个 DeleteObject 请求。
由此，若存储桶 examplebucket-1250000000中先上传了对象 A，随后存储桶开启了版本控制，此时对象 A 的版本号为字符串"null"。
添加了这个存储桶策略后，对象 A 将被保护起来。对于子用户针对对象 A 发起的 DeleteObject 请求，若请求不带版本号，由于开启了版本控制，对象 A 本身不会被永久删除，而只会被打上删除标记；若请求携带了 A 的版本号"null"，这个请求将被拒绝，保护对象 A 不被永久删除。
{
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:DeleteObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:DeleteObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"null"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ],
    "version":"2.0"
}

限制上传文件的大小（cos:content-length）

请求头部 Content-Length

RFC 2616中定义的 HTTP 请求内容长度（字节），在 PUT 和 POST 请求中经常使用。详情请参见 请求头部列表。

条件键 cos:content-length

上传对象时，可以通过条件键 cos:content-length 限制请求头部 Content-Length，进而限制上传对象的文件大小，以方便您更加灵活管理存储空间，避免上传过大、过小文件浪费存储空间与网络带宽。
在下面两个示例中，假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，可以通过 cos:content-length条件键限制子用户（uin:100000000002）上传请求的 Content-Length 头的大小。

示例1: 限制请求头部 Content-Length 的最大值

限制 PutObject 和 PostObject 上传请求必须携带 Content-Length 头部，且这个头部的值不得大于10字节。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject",
                "name/cos:PostObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_less_than_equal":{
                    "cos:content-length":10
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:PutObject",
                "name/cos:PostObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_greater_than_if_exist":{
                    "cos:content-length":10
                }
            }
        }
    ]
}

示例2: 限制请求头部 Content-Length 的最小值

限制 PutObject 和 PostObject 上传请求必须携带 Content-Length 头部，且 Content-Length 的值不得小于2字节。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject",
                "name/cos:PostObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_greater_than_equal":{
                    "cos:content-length":2
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:PutObject",
                "name/cos:PostObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_less_than_if_exist":{
                    "cos:content-length":2
                }
            }
        }
    ]
}

限制上传文件的类型（cos:content-type）

请求头部 Content-Type

RFC 2616中定义的 HTTP 请求内容类型（MIME），例如 application/xml 或 image/jpeg，详情请参见 请求头部列表。

条件键 cos:content-type

使用条件键 cos:content-type 可以对请求的 Content-Type 头部进行限制。

示例: 限定上传对象（PutObject）的 Content-Type 必须为 “image/jpeg”

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，可以通过 cos:content-type 条件键限制子用户（uin:100000000002）上传请求的 Content-Type 头的具体内容。
下面这个存储桶策略的含义是：限制使用 PutObject 上传对象必须携带 Content-Type 头部，且 Content-Type 的值为“image/jpeg”。
需要注意的是，string_equal 要求请求必须携带 Content-Type 头部，且 Content-Type 的值必须与规定值完全一致。在实际请求中，您需要明确指定请求的 Content-Type 头部。否则，当您的请求不携带 Content-Type 头部时，请求将会失败；此外，当您使用某些工具发起请求，并未明确指定 Content-Type 时，工具可能会为您自动添加不符合预期的 Content-Type 头部，也可能导致请求失败。
此外，推荐使用不区分大小写的条件运算符 string_equal_ignore_case 和 string_not_equal_ignore_case，原因是：如果使用 string_equal 和string_not_equal，当目的是禁止 text/html 类型上传文件，无法严格禁止设置 Content-Type 如 text/Html、tExt/html 的情况；使用不区分大小写的运算符，则可以起到严格禁止的效果。有关条件运算符，详情可参见 条件运算符。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal_ignore_case":{
                    "cos:content-type":"image/jpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_ignore_case_if_exist":{
                    "cos:content-type":"image/jpeg"
                }
            }
        }
    ]
}

限制下载请求返回的文件类型（cos:response-content-type）

请求参数 response-content-type

GetObject 接口支持加入请求参数 response-content-type，用于设置响应中 Content-Type 头部的值。

条件键 cos:response-content-type

使用条件键 cos:response-content-type，您可以对请求是否必须携带请求参数 response-content-type 参数值做限制。

示例：限制 Get Object 的请求参数 response-content-type 必须为 “image/jpeg”

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，以下存储桶策略的含义是，限制子用户（uin:100000000002）的 Get Object 请求必须携带请求参数 response-content-type，且请求参数值必须为“image/jpeg”，由于 response-content-type 是请求参数，发起请求时需要经过 urlencode，即 response-content-type=image%2Fjpeg，所以在设置 Policy 时，“image/jpeg”也需要经过 urlencode 填写"image%2Fjpeg"。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}

只允许使用了 HTTPS 协议的请求通过（cos:secure-transport）

条件键 cos:secure-transport

您可以使用条件键 cos:secure-transport 限制请求必须使用 HTTPS 协议。

示例1：下载请求需要使用 HTTPS 协议

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，以下存储桶策略的含义表示仅对由子用户（uin:100000000002）使用了 HTTPS 协议的 GetObject 请求进行授权。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "bool_equal":{
                    "cos:secure-transport":"true"
                }
            }
        }
    ]
}

示例2：拒绝任何不使用 HTTPS 协议的请求

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，以下存储桶策略的含义表示拒绝子用户（uin:100000000002）任何不使用 HTTPS 协议的请求。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "bool_equal":{
                    "cos:secure-transport":"false"
                }
            }
        }
    ]
}

只允许设置指定的存储类型（cos:x-cos-storage-class）

请求头部 x-cos-storage-class

用户可以通过请求头部 x-cos-storage-class 在上传对象时指定存储类型或修改对象的存储类型。

条件键 cos:x-cos-storage-class

您可以通过条件键 cos:x-cos-storage-class 限制请求头部 x-cos-storage-class，进而限制可能修改存储类型的请求。
COS 的存储类型字段包括：STANDARD、MAZ_STANDARD、STANDARD_IA、MAZ_STANDARD_IA、INTELLIGENT_TIERING、MAZ_INTELLIGENT_TIERING、ARCHIVE、DEEP_ARCHIVE。

示例：要求 PutObject 时必须将存储类型设置为标准类型

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，通过存储桶策略，限制子账户（uin:100000000002）的 PutObject 请求必须携带 x-cos-storage-class 头部，并且头部值为 STANDARD。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:x-cos-storage-class":"STANDARD"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:x-cos-storage-class":"STANDARD"
                }
            }
        }
    ]
}

只允许设置指定的存储桶/对象 ACL（cos:x-cos-acl）

请求头部 x-cos-acl

使用请求头部 x-cos-acl，您可以在上传对象、创建存储桶时指定访问控制列表（ACL），或修改对象、存储桶 ACL；关于 ACL 的相关介绍可参见 ACL概述。
存储桶的预设 ACL：private、public-read、public-read-write、authenticated-read。
对象的预设 ACL：default、private、public-read、authenticated-read、bucket-owner-read、bucket-owner-full-control。

条件键 cos:x-cos-acl

您可以通过条件键 cos:x-cos-acl 限制请求的头部 x-cos-acl，进而限制可能修改对象或存储桶 ACL 的请求。

示例：PutObject 时必须同时将对象的 ACL 设置为私有的

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，需要限制子用户（uin:100000000002）只能上传私有对象。以下策略要求发起 PutObject 请求必须携带 x-cos-acl 头部，并且头部值为 private。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:x-cos-acl":"private"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:x-cos-acl":"private"
                }
            }
        }
    ]
}

只允许列出指定目录下的对象（cos:prefix）

条件键 cos:prefix

您可以通过条件键 cos:prefix 限制请求参数 prefix。
注意：
prefix 的值若为特殊字符（中文、/ 等），写入存储桶策略前需要先经过 urlencode。

示例：只允许列出存储桶指定目录下的对象

假设主账号（uin:100000000001）拥有存储桶 examplebucket-1250000000，需要限制子用户（uin:100000000002）只可列出存储桶中 folder1 目录下的对象。以下存储桶策略规定，子用户发起 GetBucket 请求必须携带 prefix 参数，且值为folder1/，由于 prefix 的值含有特殊字符/ ，写入存储桶策略前需要先经过 urlencode。因此策略语法描述为folder1%2F。
{
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetBucket"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:prefix":"folder1%2F"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetBucket"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:prefix":"folder1%2F"
                }
            }
        }
    ],
    "version":"2.0"
}

只允许使用指定版本的 TLS 协议（cos:tls-version）

条件键 cos:tls-version

您可以通过条件键 cos:tls-version 限制 HTTPS 请求的 TLS 版本，该条件键为 Numeric 类型，支持输入浮点数，例如 1.0、1.1、1.2 等。

示例1：仅对 TLS 协议版本为1.2的 HTTPS 请求进行授权

请求场景
预期
HTTPS 请求，TLS 版本为1.0
403，失败
HTTPS 请求，TLS 版本为1.2
200，成功
策略示例如下：
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_equal":{
                    "cos:tls-version":1.2
                }
            }
        }
    ]
}

示例2：拒绝 TLS 协议版本小于1.2的 HTTPS 请求

请求场景
预期
HTTPS 请求，TLS 版本为1.0
403，失败
HTTPS 请求，TLS 版本为1.2
200，成功
策略示例如下：
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_greater_than_equal":{
                    "cos:tls-version":1.2
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "numeric_less_than_if_exist":{
                    "cos:tls-version":1.2
                }
            }
        }
    ]
}

创建存储桶时强制设置指定存储桶标签（qcs:request_tag）

说明：
条件键 request_tag 仅适用于 PutBucket、PutBucketTagging 操作。GetService、PutObject、PutObjectTagging 等操作不支持本条件键。

条件键 qcs:request_tag

您可以通过条件键 qcs:request_tag 限制用户发起请求 PutBucket、PutBucketTagging 必须携带指定的存储桶标签。

示例：限制用户创建存储桶时必须携带指定的存储桶标签

许多用户会通过存储桶标签管理存储桶，下面的策略示例为：限制用户只有在创建存储桶时，必须设置指定的存储桶标签 <a,b> 和 <c,d>，才能获得授权。
存储桶标签可以设置多个，存储桶标签键值、标签数量不同都会作为不同集合。假设用户携带的多个参数值为集合 A，条件规定的多个参数值为集合 B。在使用该条件键，可以通过限定词 for_any_value、for_all_value 的不同组合表示不同的含义。
for_any_value:string_equal 表示 A 和 B 存在交集时生效。
for_all_value:string_equal 表示 A 是 B 的子集时生效。
当使用 for_any_value:string_equal 时，对应的策略和请求表现如下：
请求场景
预期
PutBucket，请求头部 x-cos-tagging: a=b&c=d
200，成功
PutBucket，请求头部 x-cos-tagging: a=b
200，成功
PutBucket，请求头部 x-cos-tagging: a=b&c=d&e=f
200，成功
策略示例如下：
{
    "version": "2.0",
    "statement": [
        {
            "principal": {
                "qcs": [
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect": "allow",
            "action": [
                "name/cos:PutBucket"
            ],
            "resource": "*",
            "condition": {
                "for_any_value:string_equal": {
                    "qcs:request_tag": [
                        "a&b",
                        "c&d"
                    ]
                }
            }
        }
    ]
}
当使用 for_all_value:string_equal 时，对应的策略和请求表现如下：
请求场景
预期
PutBucket，请求头部 x-cos-tagging: a=b&c=d
200，成功
PutBucket，请求头部 x-cos-tagging: a=b
200，成功
PutBucket，请求头部 x-cos-tagging: a=b&c=d&e=f
403，失败
策略示例如下：
{
    "version": "2.0",
    "statement": [
        {
            "principal": {
                "qcs": [
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect": "allow",
            "action": [
                "name/cos:PutBucket"
            ],
            "resource": "*",
            "condition": {
                "for_all_value:string_equal": {
                    "qcs:request_tag": [
                        "a&b",
                        "c&d"
                    ]
                }
            }
        }
    ]
}

上传文件时强制携带禁止文件覆盖的请求头部（cos:x-cos-forbid-overwrite）

条件键 cos:x-cos-forbid-overwrite

使用条件键 cos:x-cos-forbid-overwrite 可以限制上传请求（ PutObject、PutObject-Copy、InitiateMultipartUpload、CompleteMultipartUpload）必须携带请求头部 x-cos-forbid-overwrite，进而严格禁止用户发起可能覆盖原有对象的请求。

示例：上传文件请求必须指定 x-cos-forbid-overwrite 为 true

假设主账号（uin:100000000001）拥有存储桶examplebucket-1250000000，需要限制子用户（uin:100000000002）上传对象时不可覆盖原有同名对象。以下策略限制子用户发起上传请求时（PutObject、PutObject-Copy、InitiateMultipartUpload、CompleteMultipartUpload）必须携带 x-cos-forbid-overwrite 头部且值必须为字符串 true。
{
	"version": "2.0",
	"statement": [{
			"principal": {
				"qcs": [
					"qcs::cam::uin/100000000001:uin/100000000002"
				]
			},
			"effect": "allow",
			"action": [
				"name/cos:PutObject"
			],
			"resource": [
				"qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
			],
			"condition": {
				"string_equal": {
					"cos:x-cos-forbid-overwrite": "true"
				}
			}
		},
		{
			"principal": {
				"qcs": [
					"qcs::cam::uin/100000000001:uin/100000000002"
				]
			},
			"effect": "deny",
			"action": [
				"name/cos:PutObject"
			],
			"resource": [
				"qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
			],
			"condition": {
				"string_not_equal_if_exist": {
					"cos:x-cos-forbid-overwrite": "true"
				}
			}
		}
	]
}

限制请求的访问域名（cos:host）

条件键 cos:host

您可以通过条件键 cos:host 通过限制用户请求的 Host 头部进而限制用户访问的域名。

示例1：禁止用户通过指定域名访问 COS

以下策略的含义是，禁止用户通过默认域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com 访问，用户可通过其他域名访问COS。
{
    "version": "2.0",
    "statement": [{
            "principal": {
                "qcs": [
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect": "deny",
            "action": [
                "*"
            ],
            "resource": [
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition": {
                "string_equal": {
                    "cos:host": "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com"
                }
            }
        },
        {
            "principal": {
                "qcs": [
                    "qcs::cam::uin/100000000001:uin/100000000002"
                ]
            },
            "effect": "allow",
            "action": [
                "*"
            ],
            "resource": [
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition": {
                "string_not_equal": {
                    "cos:host": "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com"
                }
            }
        }
    ]
}

示例2：限制用户仅能通过自定义域名下载对象

以下策略的含义是，限制用户仅能通过自定义域名 mydomain1.com 从存储桶目录 folder1下载对象（GetObject）。
{
	"version": "2.0",
	"statement": [{
			"principal": {
				"qcs": [
					"qcs::cam::uin/100000000001:uin/100000000002"
				]
			},
			"effect": "allow",
			"action": [
				"name/cos:GetObject"
			],
			"resource": [
				"qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/folder1/*"
			],
			"condition": {
				"string_equal": {
					"cos:host": "mydomain1.com"
				}
			}
		},
		{
			"principal": {
				"qcs": [
					"qcs::cam::uin/100000000001:uin/100000000002"
				]
			},
			"effect": "deny",
			"action": [
				"name/cos:GetObject"
			],
			"resource": [
				"qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/folder1/*"
			],
			"condition": {
				"string_not_equal": {
					"cos:host": "mydomain1.com"
				}
			}
		}
	]
}

限制对象锁定的模式（cos:object-lock-mode）

条件键 cos:object-lock-mode

您可以通过条件键 cos:object-lock-mode 限制用户上传对象必须设置对象锁定，并使用固定的模式。

示例：仅授权用户设置 COMPLIANCE 模式

{
  "statement": [
    {
      "action": [
        "name/cos:PutObject",
        "name/cos:InitiateMultipartUpload",
        "name/cos:PutObjectRetention"
      ],
      "effect": "allow",
      "principal": {
        "qcs": [
          "qcs::cam::uin/1250000000:uin/1250000001"
        ]
      },
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
      ],
      "condition": {
        "string_equal": {
          "cos:object-lock-mode": "COMPLIANCE"
        }
      }
    }
  ],
  "version": "2.0"
}

限制对象锁定的保留天数（cos:object-lock-remaining-retention-days）

条件键 cos:object-lock-remaining-retention-days

您可以通过条件键 cos:object-lock-remaining-retention-days 限制用户上传对象必须设置对象锁定，并设置固定的天数。
保留天数校验原理
该条件键传入的值仅支持为整数（假设为 A），设实际请求中 retain-until-date 的时间戳为 ts1（秒），当前时间的时间戳为 ts2（秒），换算为保留天数为（假设为 B）。
保留天数（B） = 向下取整[（ts1 - ts2）/（3600*24）]
例1：retain-until-date为2022-11-17T10:10:11，当前时间为2022-11-15T09:00:00，则保留天数（B）为2。
例2：retain-until-date为2022-11-17T10:10:11，当前时间为2022-11-15T12:00:00，则保留天数（B）为1。
是否满足条件，则是在比较 A、B 二值的大小。

示例：PutObject 上传对象的锁定天数必须大于 N 天

例如，限制锁定的剩余天数必须大于3天（不包括3天）。
说明：
条件键规定的剩余天数大于3天，即大于等于4天。请求时间为2022年10月1日16:00:00，则用户请求设定的 RetainUntilDate 必须晚于2022年10月5日16:00:00。
{
  "statement": [
    {
      "action": [
        "name/cos:PutObject",
        "name/cos:InitiateMultipartUpload",
        "name/cos:PutObjectRetention"
      ],
      "effect": "allow",
      "principal": {
        "qcs": [
          "qcs::cam::uin/1250000000:uin/1250000001"
        ]
      },
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
      ],
      "condition": {
        "numeric_greater_than": {
          "cos:object-lock-remaining-retention-days": 3
        }
      }
    }
  ],
  "version": "2.0"
}
使用不同的条件操作符，合法的 RetainUntilDate 如下：
条件键
含义
请求当前时间
入参：retain-until-date 的合法时间
备注
"numeric_equal":
{
"cos: x-cos-object-lock-remaining-retention-days": 3
}
等于3天
2022-11-01T12:00:00Z
[ 2022-11-04T12:00:00Z, 2022-11-05T11:59:59Z ]
闭区间
"numeric_greater_than":
{
"cos: x-cos-object-lock-remaining-retention-days": 3
}
大于3天（不包括3天）
2022-11-01T12:00:00Z
[ 2022-11-05T12:00:00Z, 之后 ]
闭区间
"numeric_less_than":
{
"cos: x-cos-object-lock-remaining-retention-days": 3
}
小于3天（不包括3天）
2022-11-01T12:00:00Z
[ 2022-11-01T12:00:01Z, 2022-11-04T11:59:59Z ]
闭区间

根据对象锁定的保留日期限制访问（cos:object-lock-retain-until-date）

条件键 cos:object-lock-retain-until-date

您可以通过条件键 cos:object-lock-retain-until-date 限制用户上传对象必须设置对象锁定，并设置指定日期，最小支持设置到整秒。

示例：限制 PutObject 上传对象的指定的锁定日期

以下请求表示 RetainUntilDate 必须晚于 2022-11-11T12:00:00Z。
{
  "statement": [
    {
      "action": [
        "name/cos:PutObject",
        "name/cos:InitiateMultipartUpload",
        "name/cos:PutObjectRetention"
      ],
      "effect": "allow",
      "principal": {
        "qcs": [
          "qcs::cam::uin/1250000000:uin/1250000001"
        ]
      },
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
      ],
      "condition": {
        "date_greater_than": {
          "cos:object-lock-retain-until-date": "2022-11-11T12:00:00Z"
        }
      }
    }
  ],
  "version": "2.0"
}

限制请求中携带的 ACL 授权头部

条件键

请求头部 x-cos-grant-full-control、x-cos-grant-read、x-cos-grant-write、x-cos-grant-read-acp、x-cos-grant-write-acp 被用于对象上传、对象复制、修改对象 ACL 的请求中，用于指定 ACL 权限信息，详情请参见 PutObject 的请求头部。如下表所示，对应的条件键可分别用于限制请求中是否允许携带对应头部，或限制对应头部的内容。
条件键
对应请求头部
cos:x-cos-grant-full-control
x-cos-grant-full-control
cos:x-cos-grant-read
x-cos-grant-read
cos:x-cos-grant-write
x-cos-grant-write
cos:x-cos-grant-read-acp
x-cos-grant-read-acp
cos:x-cos-grant-write-acp
x-cos-grant-write-acp
下面以 cos:x-cos-grant-full-control 为例演示如何限制 ACL 授权相关头部的使用，其他条件键的使用方法类似。这类条件键主要有两种使用场景：
限制该头部只能用于为某个账号授权，参见 示例1。
限制不能使用该头部进行授权，防止有些用户利用 PutObject 的权限篡改对象的 ACL 权限，参见 示例2。

示例1：限制 x-cos-grant-full-control 可以授权的账户

以下策略的效果为：为子账户授予上传对象的权限，但用户上传对象时必须携带 x-cos-grant-full-control 头部，且授权账号必须为主账号100000000001。x-cos-grant-full-control 头部中会包含"符号，在策略中使用时作为字符串传入，注意需要进行转义\\"。
{
	"statement": [{
			"action": [
				"name/cos:PutObject",
				"name/cos:PostObject",
				"name/cos:AppendObject",
				"name/cos:InitiateMultipartUpload"
			],
			"effect": "allow",
			"principal": {
				"qcs": [
					"qcs::cam::uin/1250000000:uin/1250000001"
				]
			},
			"resource": [
				"qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
			],
			"condition": {
				"string_equal": {
					"cos:x-cos-grant-full-control": "id=\\"100000000001\\""
				}
			}
		},
		{
			"action": [
				"name/cos:PutObject",
				"name/cos:PostObject",
				"name/cos:AppendObject",
				"name/cos:InitiateMultipartUpload"
			],
			"effect": "deny",
			"principal": {
				"qcs": [
					"qcs::cam::uin/1250000000:uin/1250000001"
				]
			},
			"resource": [
				"qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
			],
			"condition": {
				"string_not_equal_if_exist": {
					"cos:x-cos-grant-full-control": "id=\\"100000000001\\""
				}
			}
		}
	],
	"version": "2.0"
}

示例2：不允许通过 x-cos-grant-full-control 进行授权

以下策略的效果为：为子账户授予上传对象的权限，但用户上传对象时禁止携带 x-cos-grant-full-control 头部或只允许该头部设置为空。
{
	"statement": [{
			"action": [
				"name/cos:PutObject",
				"name/cos:PostObject",
				"name/cos:AppendObject",
				"name/cos:InitiateMultipartUpload"
			],
			"effect": "allow",
			"principal": {
				"qcs": [
					"qcs::cam::uin/1250000000:uin/1250000001"
				]
			},
			"resource": [
				"qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
			],
			"condition": {
				"string_equal_if_exist": {
					"cos:x-cos-grant-full-control": ""
				}
			}
		},
		{
			"action": [
				"name/cos:PutObject",
				"name/cos:PostObject",
				"name/cos:AppendObject",
				"name/cos:InitiateMultipartUpload"
			],
			"effect": "deny",
			"principal": {
				"qcs": [
					"qcs::cam::uin/1250000000:uin/1250000001"
				]
			},
			"resource": [
				"qcs::cos:ap-beijing:uid/1250000000:bjtest-1250000000/*"
			],
			"condition": {
				"string_not_equal": {
					"cos:x-cos-grant-full-control": ""
				}
			}
		}
	],
	"version": "2.0"
}

上一篇: 授权子账号按照存储桶标签拉取存储桶列表下一篇: 授予其他主账号下的子账号操作名下存储桶的权限

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈