文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>操作指南>访问管理>访问权限配置说明>访问策略语言>生效条件

生效条件

最近更新时间：2025-07-10 18:03:12

我的收藏

本页目录：

简介

生效条件是访问策略语言中的一部分，一个完整的生效条件包括如下元素：
条件键：表示生效条件的具体类型，例如用户访问来源 IP、授权时间等。
条件操作符：表示生效条件的判断方法。
条件值：指条件键的值。
说明：
当您使用条件键编写策略时，请务必遵循最小权限原则，仅为适用请求（action）添加相应的条件键，避免在指定操作（action）时使用通配符“*”，导致请求失败。
当您使用访问管理 CAM 控制台创建策略时，请注意语法格式，version、principal、statement、effect、action、resource、condition 语法元素需保持全小写。

生效条件示例

以下存储桶策略示例中的生效条件（condition）表示用户必须在 10.217.182.3/24 或者 111.21.33.72/24 网段才能完成授权 cos:PutObject 操作。其中，
条件键为 qcs:ip，表示生效条件的类型是 IP。
条件操作符为 ip_equal，表示生效条件的判断方法是判断 IP 地址是否相等。
条件值为数组 ["10.217.182.3/24","111.21.33.72/24"]，表示生效条件判断的规定值。若用户处于数组中任意一个 IP 所在的网段，条件判断都为 true。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "ip_equal":{
                    "qcs:ip":[
                        "10.217.182.3/24",
                        "111.21.33.72/24"
                    ]
                }
            }
        }
    ]
}

COS 支持的条件键

对象存储（Cloud Object Storage，COS）支持的条件键包括两类，一类是所有请求都适用的，包括 IP、VPC 和 HTTPS；一类是来自请求头部和请求参数的条件键，一般只适用于需要携带该请求头部或者请求参数的请求。关于这些条件键的说明和使用实例可参见 条件键说明及使用示例 文档。
说明：
生效条件、条件键等概念都是针对用户请求的访问管理进行的。由于生命周期、存储桶复制规则生效时的删除、复制等动作是由 COS 发起，不是用户发起的请求，条件键对生命周期、存储桶复制规则发起的动作无效。

适用于大部分请求的条件键

第一类，大部分请求都适用的条件键，如下表所示。
条件键
适用请求
含义
类型
所有请求
检查请求是否使用了 HTTPS 协议
Boolean
所有请求
请求来源的 IP 网段
IP
所有 https 请求
https 请求使用的 TLS 版本
Numeric
cos:host
所有请求
请求的 Host 头部
String

来自请求头部和请求参数的条件键

第二类，来自请求头部（Header）和请求参数（Param）的条件键。由于不同的请求具有不同的请求头部和请求参数，因此这些条件键一般只适合在包含这类头部或请求参数的请求中使用。
例如，条件键 cos:content-type 适用于需要使用请求头部 Content-Type 的上传类请求（PutObject 等），条件键 cos:response-content-type 只适用于 GetObject 请求，因为只有该请求支持请求参数 response-content-type。
下表列出了 COS 目前支持的来自请求头部和请求参数的条件键和这些条件键适用的请求。
条件键
适用请求
检测请求头部/请求参数
类型
PutObject
PostObject
InitiateMultipartUpload
请求头部：x-cos-storage-class
String
GetObject
DeleteObject
PostObjectRestore
PutObjectTagging
GetObjectTagging
DeleteObjectTagging
HeadObject
请求参数：versionid
String
GetBucket
GetBucketObjectVersions
ListMultipartUploads
ListLiveChannels
请求参数：prefix
String
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-acl
String
该请求头适用范围广，关注代表性请求，例如带请求体的请求
请求头部：Content-Length
Numeric
该请求头适用范围广，关注代表性请求，例如带请求体的请求
请求头部：Content-Type
String
GetObject
请求参数：response-content-type
String
PutBucket
PutBucketTagging
请求头部：x-cos-tagging
请求参数：tagging
String
PutObject
PutObject-Copy
InitiateMultipartUpload
CompleteMultipartUpload
请求头部：x-cos-forbid-overwrite
String
PutObject PutObject-Copy InitiateMultipartUpload
PutObjectRetention
请求头部：x-cos-object-lock-mode
请求体字段：PutObjectRetention 请求体的 Retention.Mode
String
PutObject
PutObject-Copy
InitiateMultipartUpload
PutObjectRetention
请求头部：x-cos-object-lock-remaining-retention-days
请求体字段：PutObjectRetention 请求体的 Retention.RetainUntilDate
Timestamp
PutObject
PutObject-Copy
InitiateMultipartUpload
PutObjectRetention
请求头部：x-cos-object-lock-remaining-retention-days
请求体字段：PutObjectRetention 请求体的 Retention.RetainUntilDate
Timestamp
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-grant-read
String
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-grant-read-acp
String
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-grant-write
String
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-grant-write-acp
String
PutObject
PutObject-Copy
PostObject
PutObjectACL
PutBucket
PutBucketACL
InitiateMultipartUpload
请求头部：x-cos-grant-full-control
String

条件操作符

COS 的条件键支持以下条件操作符，适用于字符串（String）、数值型（Numeric）、布尔型（Boolean）和 IP 等不同类型的条件键。
条件操作符
含义
类型
string_equal
字符串等于（区分大小写）
String
string_not_equal
字符串不等于（区分大小写）
String
string_like
字符串相似（区分大小写），当前支持在字符串前后添加通配符 *，例如 image/*
String
ip_equal
IP 等于
IP
ip_not_equal
IP 不等于
IP
numeric_equal
数值等于
Numeric
numeric_not_equal
数值不等于
Numeric
numeric_greater_than
数值大于
Numeric
numeric_greater_than_equal
数值大于等于
Numeric
numeric_less_than
数值小于
Numeric
numeric_less_than_equal
数值小于等于
Numeric

_if_exist 的含义

以上所有条件操作符都支持在后面添加 _if_exist 成为一个条件操作符。例如 string_equal_if_exist。条件操作符是否包含 _if_exist 的区别在于请求不带条件键对应的请求头或请求参数时如何处理。
条件操作符不含有 _if_exist，例如 string_equal，当请求不带对应的请求头/请求参数时，默认不命中条件，即为 False。
条件操作符含有 _if_exist，例如 string_equal_if_exist，当请求不带对应的请求头/请求参数时，默认命中条件，即为 True。

示例

示例1：允许下载指定的对象版本

例如，对于下面这个存储桶策略，效力为 allow，表示允许请求参数 versionid 为 “MTg0NDUxNTc1NjIzMTQ1MDAwODg” 的 GetObject 请求通过。如果命中了条件（True），根据 allow 的授权策略，请求会通过；如果没有命中条件（False），根据 allow 的授权策略，请求未获得授权，请求会失败。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ]
}
当条件操作符是 string_equal 或 string_equal_if_exist，condition 命中情况和请求是否通过如下表所示。
条件操作符
请求
是否命中 condition
请求是否通过
string_equal
不带 versionid
FALSE
不通过
string_equal_if_exist
不带 versionid
TRUE
通过
string_equal
带 versionid，是指定的
TRUE
通过
string_equal_if_exist
带 versionid，是指定的
TRUE
通过
string_equal
带 versionid，不是指定的
FALSE
不通过
string_equal_if_exist
带 versionid，不是指定的
FALSE
不通过

示例2：拒绝下载指定的对象版本

以下存储桶策略示例，效力为 deny，表示拒绝请求参数 versionid为 “MTg0NDUxNTc1NjIzMTQ1MDAwODg” 的 GetObject 请求。如果命中了条件（True），根据 deny 的授权策略，请求会失败；如果没有命中条件（False），根据 deny 的授权策略，请求不会被拒绝。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ]
}
当条件操作符是 string_equal 或 string_equal_if_exist，condition 命中情况和请求是否被拒绝如下表所示。
条件操作符
请求
是否命中 condition
请求拒绝/不拒绝
string_equal
不带 versionid
FALSE
不拒绝
string_equal_if_exist
不带 versionid
TRUE
拒绝
string_equal
带 versionid，是指定的
TRUE
拒绝
string_equal_if_exist
带 versionid，是指定的
TRUE
拒绝
string_equal
带 versionid，不是指定的
FALSE
不拒绝
string_equal_if_exist
带 versionid，不是指定的
FALSE
不拒绝

相关说明

特殊字符需经过 urlencode

请求参数中的特殊字符都需要经过 urlencode，因此您在存储桶策略中使用来自请求参数的条件键时，需要先经过 urlencode。例如，您在使用 cos:response-content-type 条件键时，条件值 "image/jpeg" 必须经过 urlencode 转换为 "image%2Fjpeg"，再填入存储桶策略中。

遵循最小权限原则，避免使用*号

使用条件键时，请遵循最小权限原则，只添加您需要设置权限的 action，避免使用通配符“*”。滥用通配符“*”，可能导致部分请求失败。例如下面这个例子，GetObject 之外的其他请求均不支持使用请求参数 response-content-type。
deny + string_equal_if_exist 条件操作符在请求中缺失这一条件键时，默认按照 true 处理。因此，当您发起 PutObject、PutBucket 等请求时会命中这个 deny statement，请求被拒绝。
allow + string_equal 在请求中缺失这一条件键时，默认按照 false 处理。因此，当您发起 PutObject、PutBucket 等请求时无法命中 allow statement 时，请求不被允许。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}
另一种方案，使用 allow+string_equal_if_exist 和 deny + string_not_equal，允许不带 response-content-type 请求参数的请求。
deny + string_equal 条件操作符在请求中缺失这一条件键时，默认按照 false 处理。因此，当您发起 PutObject、PutBucket 等请求时不会命中这个 deny statement，请求不被拒绝。
allow + string_equal_if_exist 在请求中缺失这一条件键时，默认按照 true 处理。因此，当您发起 PutObject、PutBucket 等请求时可以命中 allow statement，请求获得授权。
但这样使用条件操作符，您将无法对 GetObject 是否携带 response-content-type 进行限制。当 GetObject 不携带 response-content-type 请求参数时，它和其他请求一样，将被默认允许通过。只有当 GetObject 携带了 response-content-type 请求参数时，您才可以按照自己规定的条件，检查请求参数的内容是否与您预期的一致，从而实现有条件的授权。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}
因此，更加安全的方法是，遵循最小权限原则，不使用通配符“*”，将 action 限定在 GetObject。
如下面这个例子，策略生效条件被严格限定为：GetObject 请求必须携带 response-content-type，且请求参数的值必须为 "image%2Fjpeg"，才能获得授权。
对于其他请求，不受下面例子中策略的影响，您可以遵循最小权限原则，额外单独授权。
{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "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/1250000000:uin/1250000001"
                ]
            },
            "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"
                }
            }
        }
    ]
}

中国站
目录