本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 條件式處理的表達式語法
<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`的條件不相符 （即日誌層級是 ERROR 以外的任何項目） 時使用`when_else`和執行。  

```
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>

下表顯示哪些處理器支援條件式處理和哪個層級。


**處理器條件式支援**  

| 處理器 | 條件式支援 | Level | 
| --- | --- | --- | 
| add\$1entries | 是 | 處理器和項目 | 
| copy\$1values | 是 | 處理器和項目 | 
| delete\$1entries | 是 | 處理器 | 
| move\$1keys | 是 | 處理器和項目 | 
| flatten | 是 | 處理器 | 
| lowercase\$1string | 是 | 處理器 | 
| uppercase\$1string | 是 | 處理器 | 
| trim\$1string | 是 | 處理器 | 
| substitute\$1string | 是 | 處理器和項目 | 
| 截斷 | 是 | 處理器 | 
| extract\$1value | 是 | 處理器和項目 | 
| convert\$1entry\$1type | 是 | 處理器 | 
| date | 是 | 處理器 | 
| 剖析 | 是 | 處理器 | 
| list\$1to\$1map | 是 | 處理器 | 
| rename\$1keys | 是 | 處理器和項目 | 
| select\$1entries | 是 | 處理器 | 
| translate | 是 | 處理器 | 
| grok | 是 | 處理器 | 
| drop\$1events | 是 | 處理器 （必要） | 
| OCSF、CSV、JSON、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 | 否 | — | 

## 運算子
<a name="expression-operators"></a>


**支援的運算子**  

| Category | 運算子 | 範例 | 
| --- | --- | --- | 
| 關聯式 | <, <=, >, >= | 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 | 
| Regex 比對 | =\$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 個字元。
+ Parser 處理器 (Grok 除外） 不支援條件式處理。這包括 JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 和 OCSF 剖析器。
+ 如果在管道中使用 Grok 處理器做為剖析器 （第一個處理器），且其`when`條件評估為 false，則整個管道不會針對該日誌事件執行。