# 条件处理的表达式语法
<a name="conditional-processing"></a>

支持条件处理的 CloudWatch 管道处理器接受包含表达式的 `when` 参数。如果表达式的计算结果为 true，则执行处理器或条目。表达式使用点符号 (`.`) 来访问嵌套字段。例如，`user.role` 访问 `user` 对象内部的 `role` 字段。有关支持条件处理的处理器及其特定参数的更多详细信息，请参阅[CloudWatch 管道处理器](pipeline-processors.md)。有关配置示例，请参阅[常见处理器使用案例](processor-examples.md)。

## 处理器级和条目级条件
<a name="conditional-levels"></a>

根据处理器的不同，可以在两个级别应用 `when` 条件。

处理器级 `when`（外部级别）  
`when` 位于处理器配置的顶层。如果该表达式的计算结果为 false，则跳过整个处理器并且不会执行其中的任何操作。所有支持条件处理的处理器都支持此级别。  

**Example 处理器级条件：跳过整个处理器**  
以下 `delete_entries` 处理器仅在生产环境或暂存环境中运行。如果条件为 false，则不删除任何密钥。  

```
processor:
  - delete_entries:
      with_keys: ["password", "api_key", "ssn"]
      when: "environment in {'prod', 'staging'}"
```

条目级 `when`（在每个条目中）  
`when` 位于 `entries` 数组中单个条目内。每个条目均经过独立评估：如果表达式为 false，则仅跳过该特定条目，而同一处理器中的其他条目仍会执行。只有具有 `entries` 数组的处理器支持此级别（例如 `add_entries`、`copy_values`、`rename_keys`、`move_keys`、`extract_value` 和 `substitute_string`）。  

**Example 条目级条件：跳过单个条目**  
以下 `add_entries` 处理器根据每个条目的条件添加不同的密钥。仅当日志级别为 ERROR 时，第一个条目才会添加 `severity`。第二个条目总是添加 `processed`，因为它没有条件。  

```
processor:
  - add_entries:
      entries:
        - key: "severity"
          value: "high"
          when: "log.level == 'ERROR'"
        - key: "processed"
          value: "true"
```

支持这两个级别的处理器可将它们一起使用。如果同时指定了两者，则首先评估处理器级条件。如果为 false，则跳过整个处理器，并且不评估条目级条件。

**Example 两个级别相结合**  
处理器级 `when` 可确保整个处理器仅针对生产流量运行。其中，每个条目都有自己的条件来控制添加哪个密钥。  

```
processor:
  - add_entries:
      when: "environment == 'prod'"
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "warning"
          when: "log.level == 'WARN'"
```

有关显示哪些处理器支持哪个级别的表格，请参阅以下[条件处理支持](#conditional-support)一节。

**通过 `when_else` 回退**  
支持条目级条件的处理器也支持 `when_else`。带有 `when_else` 的条目充当回退选项：仅当同一处理器中的其他 `when` 条件都不匹配时，它才会执行。提供给 `when_else` 的表达式值用于标识要考虑哪组 `when` 条件，但条目本身仅根据这些条件的计算结果是否都为 false 来运行。没有显式否定检查：该条目只是在没有其他 `when` 匹配项时运行。

**Example 带有 when\$1else 的回退条目**  
第一个条目在日志级别为 ERROR 时运行。第二个条目仅在第一个条目的 `when` 条件不匹配时才使用 `when_else` 和运行（即，日志级别是除 ERROR 以外的项目）。  

```
processor:
  - add_entries:
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "info"
          when_else: "log.level == 'ERROR'"
```

## 条件处理支持
<a name="conditional-support"></a>

下表显示了哪些处理器支持条件处理以及支持哪个级别。


**处理器条件支持**  

| 处理器 | 条件支持 | 级别 | 
| --- | --- | --- | 
| add\$1entries | 是 | 处理器和条目 | 
| copy\$1values | 是 | 处理器和条目 | 
| delete\$1entries | 是 | 处理器 | 
| move\$1keys | 是 | 处理器和条目 | 
| flatten | 是 | 处理器 | 
| lowercase\$1string | 是 | 处理器 | 
| uppercase\$1string | 是 | 处理器 | 
| trim\$1string | 是 | 处理器 | 
| substitute\$1string | 是 | 处理器和条目 | 
| truncate | 是 | 处理器 | 
| extract\$1value | 是 | 处理器和条目 | 
| convert\$1entry\$1type | 是 | 处理器 | 
| date | 是 | 处理器 | 
| dissect | 是 | 处理器 | 
| list\$1to\$1map | 是 | 处理器 | 
| rename\$1keys | 是 | 处理器和条目 | 
| select\$1entries | 是 | 处理器 | 
| 翻译 | 是 | 处理器 | 
| grok | 是 | 处理器 | 
| drop\$1events | 是 | 处理器（必填） | 
| OCSF、CSV、JSON、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 | 否 | — | 

## 运算符
<a name="expression-operators"></a>


**支持的运算符**  

| 类别 | 运算符 | 示例 | 
| --- | --- | --- | 
| 关系 | <, <=, >, >= | status\$1code >= 200 and status\$1code < 300 | 
| 等于 | ==, \$1= | log.level == "ERROR" | 
| 有条件 | and, or, not | log.level == "ERROR" or log.level == "FATAL" | 
| 算术 | \$1, -, \$1, / | response\$1time \$1 1000 > 5000 | 
| 设置成员资格 | in, not in | environment in \$1"prod", "staging", "preprod"\$1 | 
| 正则表达式匹配 | =\$1, \$1\$1 | message =\$1 "^ERROR.\$1timeout" | 

## 函数
<a name="expression-functions"></a>

`length(value)`  
返回字符串或数组的长度。示例：`length(message) > 100`

`contains(value, search)`  
检查字符串是否包含子字符串或数组是否包含元素。示例：`contains(message, "error")`

`startsWith(field, prefix)`  
检查字符串是否以指定的前缀开头。示例：`startsWith(message, "ERROR")`

## 表达式示例
<a name="expression-examples"></a>

```
log.level == "ERROR"
status_code >= 200 and status_code < 300
environment in {"prod", "staging", "preprod"}
message =~ "^ERROR.*timeout"
user.role == "admin" and user.permissions.write == true
length(message) > 100 and contains(message, "error")
(log.level == "ERROR" or log.level == "FATAL") and environment == "prod"
```

## 限制
<a name="expression-limitations"></a>
+ 表达式最大长度为 256 个字符。
+ 解析器处理器（Grok 除外）不支持条件处理。这包括 JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 和 OCSF 解析器。
+ 如果将 Grok 处理器用作管道中的解析器（第一个处理器），并且其 `when` 条件的计算结果为 false，则不会针对该日志事件执行整个管道。