本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 轉換處理器
轉換處理器透過新增、複製、移動或移除欄位來修改日誌事件的結構。
## add\_entries 處理器
將靜態金鑰/值對新增至日誌事件。最多可將 1 個`add_entries`處理器新增至管道。
**組態**
使用下列參數設定 add\_entries 處理器：
```
processor:
- add_entries:
entries:
- key: "environment"
value: "production"
overwrite_if_key_exists: false
```Parameters
`entries` (必要)
要新增至每個日誌事件的鍵/值對陣列。
`entries[].key` (必要)
要新增至日誌事件的欄位名稱。支援使用點表示法的巢狀欄位。
`entries[].value` (必要)
要指派給金鑰的靜態值。
`entries[].overwrite_if_key_exists` (選用)
決定金鑰已存在時行為的布林值旗標。預設為 false。
`when` (選用)
處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when` (選用)
入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when_else` (選用)
只有在相同處理器中沒有其他`when`條件相符時，才會執行的備用項目。表達式值可識別要考慮`when`的條件。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
## copy\_values 處理器
將值從一個欄位複製到另一個欄位。最多可將 1 個`copy_values`處理器新增至管道。
**組態**
使用下列參數設定 copy\_values 處理器：
```
processor:
- copy_values:
entries:
- from_key: "user_id"
to_key: "backup_user"
overwrite_if_to_key_exists: false
```Parameters
`entries` (必要)
在每個日誌事件上執行的複製操作陣列。
`entries[].from_key` (必要)
要從中複製值的欄位名稱。將點表示法用於巢狀欄位。
`entries[].to_key` (必要)
要複製值的欄位名稱。如果使用點表示法，則會建立巢狀結構。
`entries[].overwrite_if_to_key_exists` (選用)
當目標欄位已存在時，控制行為的布林值旗標。預設為 false。
`when` (選用)
處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when` (選用)
入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when_else` (選用)
只有在相同處理器中沒有其他`when`條件相符時，才會執行的備用項目。表達式值可識別要考慮`when`的條件。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
## delete\_entries 處理器
從日誌事件中移除指定的欄位。
**組態**
使用下列參數設定 delete\_entries 處理器：
```
processor:
- delete_entries:
with_keys: ["temp_field", "debug_info"]
```Parameters
`with_keys` (必要)
要從每個日誌事件中移除的欄位名稱陣列。支援使用點符號刪除巢狀欄位。
`when` (選用)
決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
## move\_keys 處理器
將欄位從一個位置移至另一個位置。
**組態**
使用下列參數設定 move\_keys 處理器：
```
processor:
- move_keys:
entries:
- from_key: "old_field"
to_key: "new_field"
overwrite_if_to_key_exists: true
```Parameters
`entries` (必要)
移動操作陣列。最多 5 個項目。
`entries[].from_key` (必要)
來源欄位名稱。最多 128 個字元。
`entries[].to_key` (必要)
目標欄位名稱。最多 128 個字元。
`entries[].overwrite_if_to_key_exists` (選用)
是否覆寫現有的目標欄位。
`when` (選用)
處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when` (選用)
入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
`entries[].when_else` (選用)
只有在相同處理器中沒有其他`when`條件相符時，才會執行的備用項目。表達式值可識別要考慮`when`的條件。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
## 平面處理器
扁平化巢狀物件結構。
**組態**
使用下列參數設定平面處理器：
```
processor:
- flatten:
source: "metadata"
target: "flattened"
remove_processed_fields: true
exclude_keys: ["sensitive_data"]
```Parameters
`source` (必要)
包含要扁平化之巢狀物件的欄位。
`target` (必要)
扁平化金鑰的目標欄位字首。
`remove_processed_fields` (選用)
是否在平面化後移除原始巢狀欄位。
`exclude_keys` (選用)
要從平面化中排除的索引鍵陣列。最多 20 個金鑰，每個最多 128 個字元。
`when` (選用)
決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
## 查詢處理器
使用來自 CloudWatch Logs 查詢資料表的資料來豐富日誌事件。處理器會將日誌事件中的欄位與查詢資料表中的欄位進行比對，並將指定的欄位附加至日誌事件。將此處理器用於資料擴充案例，例如將使用者 IDs映射至使用者詳細資訊、將產品代碼映射至產品資訊，或將錯誤代碼映射至錯誤描述。最多可將 1 個`lookup`處理器新增至管道。
**注意**
如果在管道中使用查詢資料表，您必須為執行角色提供資料表的`logs:GetLookupTable`許可。如需詳細資訊，請參閱[CloudWatch 管道 IAM 政策和許可](pipeline-iam-reference.md)。
**組態**
使用下列參數設定查詢處理器：
```
processor:
- lookup:
lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:my_lookup_table"
match_keys:
- log_key: "src_ip"
lookup_key: "ip_address"
entries:
- source: "hostname"
target: "src_hostname"
overwrite_if_exists: true
```Parameters
`lookup_table` (必要)
用於擴充的 CloudWatch Logs 查詢資料表 ARN。長度上限為 2048 個字元。
`match_keys` (必要)
金鑰對陣列，定義如何比對日誌事件欄位以查詢資料表欄位。最少 1 個，最多 5 個相符金鑰。指定多個相符索引鍵時，查詢資料表資料列必須符合所有索引鍵才能產生結果 (AND 邏輯）。
`match_keys[].log_key` (必要)
日誌事件中要比對的欄位名稱。最多 128 個字元。
`match_keys[].lookup_key` (必要)
要比對之查詢資料表中的資料欄名稱。最多 128 個字元。
`entries` (必要)
要從相符查詢資料表資料列新增至日誌事件的欄位陣列。最少 1 個，最多 10 個項目。
`entries[].source` (必要)
查詢資料表中要從中擷取值的資料欄名稱。最多 128 個字元。
`entries[].target` (選用)
要新增至日誌事件的欄位名稱。如果未指定，資料`source`欄名稱會用作欄位名稱。最多 128 個字元。
`entries[].overwrite_if_exists` (選用)
布林值旗標，決定目標欄位在日誌事件中已存在時的行為。預設為 false。
`when` (選用)
決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱 [條件式處理的表達式語法](conditional-processing.md)。
**範例**
考慮`network_assets`使用下列資料列命名為 的查詢資料表：
**network\_assets 查詢資料表**
| ip\_address | hostname | owner | location |
| --- | --- | --- | --- |
| 10.0.1.12 | Web-server-01 | team-alpha | us-east-1 |
| 10.0.2.45 | db-server-03 | team-beta | us-west-2 |
| 10.0.3.78 | cache-node-07 | team-alpha | eu-west-1 |
根據下列日誌事件：
```
{
"timestamp": "2026-05-04T12:00:00Z",
"src_ip": "10.0.2.45",
"action": "connection_opened",
"bytes": 2048
}
```
以及下列處理器組態：
```
processor:
- lookup:
lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:network_assets"
match_keys:
- log_key: "src_ip"
lookup_key: "ip_address"
entries:
- source: "hostname"
target: "src_hostname"
- source: "owner"
- source: "location"
target: "src_region"
overwrite_if_exists: false
```
處理器會產生下列豐富的日誌事件：
```
{
"timestamp": "2026-05-04T12:00:00Z",
"src_ip": "10.0.2.45",
"action": "connection_opened",
"bytes": 2048,
"src_hostname": "db-server-03",
"owner": "team-beta",
"src_region": "us-west-2"
}
```
**IAM 許可**
當管道使用查詢處理器時，管道的執行角色必須包含參考資料表的`logs:GetLookupTable`許可。下列範例政策陳述式會授予此許可：
```
{
"Effect": "Allow",
"Action": "logs:GetLookupTable",
"Resource": "arn:aws:logs:::lookup-table:"
}
```