配置自定义规则语言属性

每个 Google Cloud Armor 安全政策规则都有优先级、匹配条件和操作。Cloud Armor 会执行与请求匹配的最高优先级规则的操作。优先级低于最高优先级匹配规则的规则不会进行评估，即使它们具有相同的匹配条件也是如此。

每个安全政策规则都支持两种类型的匹配条件：

基本匹配条件包含 IP 地址列表或 IP 地址范围列表。基本匹配条件是在通过 Google Cloud CLI 创建规则时使用 --src-ip-ranges 标志定义的。
高级匹配条件包含一个最多具有 5 个子表达式的表达式，可匹配传入请求的各种属性。高级匹配条件是在通过 Google Cloud CLI 创建规则时使用 --expression 标志定义的。

本页面介绍了高级匹配条件和 Cloud Armor 自定义规则语言，您可以使用该语言在安全政策规则的高级匹配条件中编写表达式。Cloud Armor 自定义规则语言是通用表达式语言 (CEL) 的子集。使用 Cloud Armor 自定义规则语言编写的表达式需要两个组成部分：

属性：要检查的数据
操作：如何使用数据

例如，以下表达式在操作 inIpRange() 中使用属性 origin.ip 和 9.9.9.0/24。在这种情况下，如果 origin.ip 在 9.9.9.0/24 IP 地址范围内，则表达式返回 true。

inIpRange(origin.ip, '9.9.9.0/24')

尽管前面的示例表达式仅匹配客户端 IP 地址，但当您在 Cloud Armor 安全政策规则中使用该示例表达式时，该规则在配额方面会被视为具有高级匹配条件的规则。如需了解详情，请参阅 Cloud Armor 配额和限制。

运维

以下参考信息描述了可与属性（由 x、y 和 k 表示）搭配使用来定义规则表达式的运算符。

运维	表达式	说明
相等	`x == y`	如果 x 等于 y，则返回 true。
相等，字符串字面量	`x == "foo"`	如果 x 等于指定常量字符串字面量，则返回 true。x
相等，原始字符串字面量	`x == R"fo'o"`	如果 x 等于不解释转义序列的指定原始字符串字面量，则返回 true。x原始字符串字面量便于表示自己必须使用转义序列字符的字符串。
逻辑非	`!x`	如果布尔值 x 为 false，则返回 true；如果布尔值 x 为 true，则返回 false。
不相等	`x != y`	如果 x 不等于 y，则返回 true。
串联	`x + y`	返回串联的字符串 xy。
逻辑与	`x && y`	如果 x 和 y 均为 true，则返回 true。
逻辑或	`x \|\| y`	如果 x、y 或两者均为 true，则返回 true。
包含子字符串	`x.contains(y)`	如果字符串 x 包含子字符串 y，则返回 true。
以子字符串开头	`x.startsWith(y)`	如果字符串 x 以子字符串 y 开头，则返回 true。
以子字符串结尾	`x.endsWith(y)`	如果字符串 x 以子字符串 y 结尾，则返回 true。
正则表达式匹配	`x.matches(y)`	如果字符串 x 与指定的 RE2 模式 y 部分匹配，则返回 true。RE2 模式是使用停用 Unicode 功能的 RE2::Latin1 选项编译的。
范围内的 IP 地址	`inIpRange(x, y)`	如果 IP 地址 x 包含在 IP 范围 y 内，则返回 true。
小写	`x.lower()`	返回字符串 x 的小写值。x
大写	`x.upper()`	返回字符串 x 的大写值。x
Base64 解码值	`x.base64Decode()`	返回 xx 的 base64 解码值；字符 `_ -` 首先被相应替换为 `/ +`。如果 xx 不是有效的 base64 值，则返回 `""`（空字符串）。
键映射值	`m['k']`	如果 k 可用，则返回字符串到字符串映射 m 中的键 k 处的值；否则返回错误。建议先使用 `"has(m['k'])==true"` 检查可用性。
在映射中检查键可用性	`has(m['k'])`	如果键 'k' 在映射 'm' 中可用，则返回 true。
转换为整数	`int(x)`	将字符串结果 x 转换为 `int` 类型。x接着可以将其用于使用标准算术运算符（例如 > 和 <=）进行整数比较。这仅适用于应该为整数的值。
长度	`size(x)`	返回字符串 x 的长度。x
解码网址	`x.urlDecode()`	返回 xx 的网址解码值；`%##` 格式的字符序列会被替换为非 ASCII 等效字符，而 `+` 则被替换为空格。无效编码会按原样返回。
解码网址 (Unicode)	`x.urlDecodeUni()`	返回 xx 的网址解码值；除了 `urlDecode()` 之外，还会处理 `%u###` 格式的 Unicode 字符序列。无效编码会按原样返回。
将 utf8 转换为 Unicode	`x.utf8ToUnicode()`	返回 UTF-8 编码 xx 的小写 Unicode 表示形式。

属性

属性表示来自传入请求的信息，例如客户端 IP 地址或请求的网址路径。

字段	类型	字段说明
`origin.ip`	字符串	发起请求的客户端的 IP 地址。
`origin.user_ip`	字符串	来源客户端的 IP 地址，由上游代理添加在 `HTTP-HEADER` 中。在使用此属性之前，您必须在安全政策的 `advancedOptionsConfig` 字段中配置 `userIpRequestHeaders[]` 选项，以匹配 `True-Client-IP`、`X-Forwarded-For` 或 `X-Real-IP` 等来源。如需了解详情，请参阅用户 IP 地址概览。如果您未配置 `userIpRequestHeaders[]` 选项、配置的标头包含无效的 IP 地址值，或者配置的标头不存在，则 `origin.user_ip` 默认为 `origin.ip`。如需了解详情，请参阅 securityPolicy 资源参考文档。
`origin.tls_ja4_fingerprint`	字符串	如果客户端使用 `HTTPS`、`HTTP/2` 或 `HTTP/3` 进行连接，则为 JA4 TLS/SSL 指纹。如果不可用，则返回空字符串。
`origin.tls_ja3_fingerprint`	字符串	如果客户端使用 `HTTPS`、`HTTP/2` 或 `HTTP/3` 进行连接，则为 JA3 TLS/SSL 指纹。如果不可用，则返回空字符串。
`request.headers`	地图	HTTP 请求标头的字符串到字符串映射。如果标头包含多个值，则此映射中的值将是标头所有值的英文逗号分隔字符串。此映射中的键全部为小写。系统会检查外部应用负载均衡器接受的所有标头，并应用相同的标头限制。建议先使用 `has()` 检查可用性（例如 `has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'`）。
`request.method`	字符串	HTTP 请求方法。
`request.path`	字符串	所请求的 HTTP 网址路径。当您编写与 `request.path` 匹配的规则时，我们建议您对路径进行规范化，以便在出现网址编码、大小写变体或反斜杠时，能够轻松匹配语法。如需了解详情和示例，请参阅路径遍历和规范化。
`request.scheme`	字符串	HTTP 网址架构，例如 `http` 或 `https`。此属性的值均为小写。
`request.query`	字符串	HTTP 网址查询，格式为 `name1=value&name2=value2`，显示在 HTTP 请求的第一行中。未执行解码。
`origin.region_code`	字符串	与客户端 IP 相关联的 Unicode 国家/地区代码，例如 `US`。如果您要创建使用 ISO 3166-1 alpha 2 国家或区域代码的规则或表达式，请注意 Cloud Armor 会独立处理每个代码。Cloud Armor 规则和表达式显式使用这些区域代码来允许或拒绝请求。
`origin.asn`	整数	与客户端 IP 地址关联的自治系统编号 (ASN)。全局唯一 ASN 根据支持包含客户端 IP 地址的 IP 地址前缀的网络运营商确定。

reCAPTCHA 属性

本部分列出了仅适用于 reCAPTCHA 令牌或豁免 Cookie 的属性。如果要评估的 reCAPTCHA 令牌或豁免 Cookie 因以下任一原因而不可用或无效，则基于这些属性的子表达式会返回 false：

令牌格式不正确，无法解码。
令牌包含无效属性。例如，令牌是使用与规则的关联 reCAPTCHA 密钥不匹配的 reCAPTCHA 密钥生成的。
令牌已过期。

豁免 Cookie 特性

字段	类型	字段说明
`token.recaptcha_exemption.valid`	`bool`	是否存在有效的 reCAPTCHA 豁免 Cookie。

操作令牌特性

字段	类型	字段说明
`token.recaptcha_action.score`	`float`	reCAPTCHA 操作令牌中的分数。有效分数的范围为 `0.0` 到 `1.0`，其中 `0.0` 表示很可能是非法用户，`1.0` 表示很可能是合法用户。
`token.recaptcha_action.captcha_status`	`string`	reCAPTCHA 操作令牌中的人机识别系统状态。有效状态为 `NONE`、`PASS` 或 `FAIL`，其中 `NONE` 表示 reCAPTCHA 评估期间未涉及任何验证，因此操作令牌中缺少人机识别系统字段。
`token.recaptcha_action.action`	`string`	reCAPTCHA 操作令牌中的操作名称（最多 100 个字符）。请参阅操作名称。
`token.recaptcha_action.valid`	`bool`	是否存在有效的 reCAPTCHA 操作令牌。

会话令牌特性

字段	类型	字段说明
`token.recaptcha_session.score`	`float`	reCAPTCHA 会话令牌的分数。有效分数的范围为 `0.0` 到 `1.0`，其中 `0.0` 表示很可能是非法用户，`1.0` 表示很可能是合法用户。
`token.recaptcha_session.valid`	`bool`