# 条件付き処理の式構文
<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` 条件を適用できるレベルは 2 つあります。

プロセッサレベル `when` (外部レベル)  
プロセッサ設定の最上位にある `when`。式が false と評価された場合、プロセッサ全体がスキップされ、プロセッサ内のオペレーションは実行されません。条件付き処理をサポートしているすべてのプロセッサは、このレベルをサポートします。  

**Example プロセッサレベルの条件 — プロセッサ全体をスキップする**  
次の `delete_entries` プロセッサは、環境が本番環境またはステージングの場合にのみ実行されます。条件が false の場合、どのキーも削除されません。  

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

エントリレベル `when` (各エントリ内)  
`entries` 配列内の個々のエントリ内にある `when`。各エントリは個別に評価されます — 式が false の場合、その特定のエントリのみがスキップされ、同じプロセッサ内の他のエントリは引き続き実行されます。`entries` 配列を持つプロセッサのみが、このレベル (`add_entries`、`copy_values`、`rename_keys`、`move_keys`、`extract_value`、`substitute_string` など) をサポートします。  

**Example エントリレベルの条件 — 個々のエントリをスキップする**  
次の `add_entries` プロセッサは、各エントリの条件に応じて異なるキーを追加します。最初のエントリは、ログレベルが ERROR の場合にのみ `severity` を追加します。2 番目のエントリは条件がないため、それは常に `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 の場合に実行されます。2 番目のエントリは、`when_else` を使用して、最初のエントリの `when` 条件が一致しない場合 (つまり、ログレベルが 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 | はい | プロセッサとエントリ | 
| 切り詰め | はい | プロセッサ | 
| 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 文字です。
+ パーサープロセッサ (Grok を除く) は条件付き処理をサポートしていません。これには、JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53、および OCSF パーサーが含まれます。
+ Grok プロセッサをパイプラインのパーサー (最初のプロセッサ) として使用し、その `when` 条件が false と評価された場合、パイプライン全体がそのログイベントに対して実行されません。