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

# Amazon EventBridge 管道中的事件篩選
<a name="eb-pipes-event-filtering"></a>

使用 EventBridge 管道，您可以篩選指定來源的事件，並僅處理部分事件。此篩選的運作方式與使用事件模式篩選 EventBridge 事件匯流排或 Lambda 事件來源映射對應的運作方式相同。如需有關事件模式的詳細資訊，請參閱 [建立 Amazon EventBridge 事件模式](eb-event-patterns.md)。

篩選條件標準 `FilterCriteria` 物件是由篩選條件清單 (`Filters`) 組成的結構。每個篩選條件都是定義篩選模式的結構 (`Pattern`)。`Pattern` 是 JSON 篩選條件規則的字串表示法。`FilterCriteria` 物件看起來正如下列範例：

```
{
  "Filters": [
    {"Pattern": "{ \"Metadata1\": [ pattern1 ], \"data\": { \"Data1\": [ pattern2 ] }}"
    }
  ]
}
```

補充說明，此處是篩選條件的 `Pattern` 在純文字 JSON 中擴展的值：

```
{
  "Metadata1": [ pattern1 ],
  "data": {"Data1": [ pattern2 ]}
}
```

Amazon Kinesis、Amazon MQ、Amazon MSK 和自我管理 Apache Kafka 會將 Base64 編碼套用至承載，但不套用中繼資料欄位。例如，假設您的 Kinesis 串流包含以下事件：

```
{
  "kinesisSchemaVersion": "1.0",
  "partitionKey": "1",
  "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
  "data": {"City": "Seattle",
    "State": "WA",
    "Temperature": "46",
    "Month": "December"
  },
  "approximateArrivalTimestamp": 1545084650.987
}
```

當事件流經您的管道時，使用 base64 編碼的 `data` 欄位看起來會如下所示：

```
{
  "kinesisSchemaVersion": "1.0",
  "partitionKey": "1",
  "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
  "data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
  "approximateArrivalTimestamp": 1545084650.987,
  "eventSource": "aws:kinesis",
  "eventVersion": "1.0",
  "eventID": "shardId-000000000006:49590338271490256608559692538361571095921575989136588898",
  "eventName": "aws:kinesis:record",
  "invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
  "awsRegion": "us-east-2",
  "eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
}
```

當您建立事件篩選條件時，EventBridge 管道可以存取事件內容。此內容可能是 JSON 逸出，例如 Amazon SQS `body` 欄位或以 base64 編碼 (例如 Kinesis `data` 欄位)。如果您的資料是有效的 JSON，則目標參數的輸入範本或 JSON 路徑可以直接參考內容，因為 EventBridge 管道會自動解碼內容。例如，如果 Kinesis 事件來源是有效的 JSON，您可以使用 `<$.data.someKey>` 參考變數。

繼續我們的範例，若要篩選`data`物件外部的未編碼`partitionKey`中繼資料，以及`data`物件內部的 base64 編碼`City`屬性，您可以使用下列篩選條件：

```
{
  "partitionKey": [ "1" ],
  "data": {
    "City": [ "Seattle" ]
  }
}
```

建立事件模式時，您可以根據來源 API 傳送的欄位進行篩選，而不是輪詢作業新增的欄位。下列欄位不能用於事件模式：
+ `awsRegion`
+ `eventSource`
+ `eventSourceARN`
+ `eventVersion`
+ `eventID`
+ `eventName`
+ `invokeIdentityArn`
+ `eventSourceKey`

下列各節說明每個支援事件來源類型的篩選行為。

## 篩選 Amazon SQS 訊息
<a name="pipes-filter-sqs"></a>

如果 Amazon SQS 訊息不符合您的篩選條件標準，EventBridge 會自動從佇列中刪除該訊息。您不需要在 Amazon SQS 中手動刪除這些訊息。將多個管道連接到一個 SQS 佇列不太可能是有用的設定 - 管道會競爭如果不相符，將會捨棄的訊息。

Amazon SQS 訊息內文可以包含任何字串，而不只是 JSON。EventBridge 管道預期您的`FilterCriteria`格式符合傳入訊息的格式，無論是有效的 JSON 或純字串。如果不相符，EventBridge 管道會捨棄訊息。如果您的 `FilterCriteria`不包含 `body`，表示您僅依中繼資料篩選，EventBridge 管道會略過此檢查。下表摘要說明評估：


| 篩選條件模式 格式 | 傳入格式 | 結果 | 
| --- | --- | --- | 
|  純文字的字串  |  純文字的字串  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  純文字的字串  |  有效的 JSON  |  EventBridge 捨棄訊息。  | 
|  有效的 JSON  |  純文字的字串  |  EventBridge 捨棄訊息。  | 
|  有效的 JSON  |  有效的 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  沒有 的篩選條件模式 `body`  |  純文字的字串  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  沒有 的篩選條件模式 `body`  |  有效的 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 

## 篩選 Kinesis 和 DynamoDB 訊息
<a name="pipes-filter-kinesis-dynamobd"></a>

您的篩選條件標準處理 Kinesis 或 DynamoDB 記錄後，串流迭代器將向前移動超過此記錄。如果記錄不滿足篩選條件標準，則無需從事件來源中手動刪除記錄。保留期之後，Kinesis 和 DynamoDB 會自動刪除這些舊記錄。如果希望更快地刪除記錄，請參閱[變更資料保留期間](https://docs.aws.amazon.com/kinesis/latest/dev/kinesis-extended-retention.html)。

若要正確篩選來自串流事件來源的事件，資料欄位和資料欄位的篩選條件標準都必須是有效的 JSON 格式。(若為 Kinesis，資料欄位為 `data`。若為 DynamoDB，資料欄位為 `dynamodb`。) 如果其中一個欄位不是有效的 JSON 格式，則 EventBridge 會捨棄訊息或擲回例外狀況。下表摘要說明特定行為：


| 篩選條件模式 格式 | 傳入格式 | 結果 | 
| --- | --- | --- | 
|  有效的 JSON  |  有效的 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  有效的 JSON  |  非 JSON  |  EventBridge 捨棄訊息。  | 
|  `data` (Kinesis) 或 `dynamodb`(DynamoDB) 沒有篩選條件模式  |  有效的 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  `data` (Kinesis) 或 `dynamodb`(DynamoDB) 沒有篩選條件模式  |  非 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  非 JSON  |  任何  |  EventBridge 在管道建立或更新時擲回例外狀況。篩選條件模式必須是有效的 JSON 格式。  | 

## 篩選 Amazon Managed Streaming for Apache Kafka、自我管理 Apache Kafka 和 Amazon MQ 訊息
<a name="pipes-filter-poller"></a>

**注意**  
將篩選條件標準連接至 Apache Kafka 或 Amazon MQ 管道後，最多可能需要 15 分鐘才能將篩選條件規則套用至事件。

若為 [Amazon MQ 來源](eb-pipes-mq.md)，訊息欄位為 `data`。若為 Apache Kafka 來源 ([Amazon MSK](eb-pipes-msk.md) 和[自我管理的 Apache Kafka](eb-pipes-kafka.md))，則有兩個訊息欄位：`key` 和 `value`。

EventBridge 會排除與篩選條件中包含的所有欄位不相符的訊息。對於 Apache Kafka，EventBridge 會在成功叫用目標後，遞交相符和不相符訊息的位移。若為 Amazon MQ，EventBridge 會在成功調用函數後確認相符的訊息，並在篩選時確認不相符的訊息。

Apache Kafka 和 Amazon MQ 訊息必須是 UTF-8 編碼的字符串，可以是純字串或 JSON 格式。這是因為 EventBridge 會在套用篩選條件之前，將 Apache Kafka 和 Amazon MQ 位元組陣列解碼成 UTF-8。如果您的訊息使用其他編碼方式，例如 UTF-16 或 ASCII，或者訊息格式與 `FilterCriteria` 格式不相符，則 EventBridge 只會處理中繼資料篩選條件。下表摘要說明特定行為：


| 篩選條件模式 格式 | 傳入格式 | 結果 | 
| --- | --- | --- | 
|  純文字的字串  |  純文字的字串  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  純文字的字串  |  有效的 JSON  |  僅中繼資料上的 EventBridge 篩選條件，忽略 `data` 欄位 (Amazon MQ) 或 `key`和 `value` 欄位 (Apache Kafka)  | 
|  有效的 JSON  |  純文字的字串  |  僅中繼資料上的 EventBridge 篩選條件，忽略 `data` 欄位 (Amazon MQ) 或 `key`和 `value` 欄位 (Apache Kafka)  | 
|  有效的 JSON  |  有效的 JSON  |  以您的篩選條件標準為依據的 EventBridge 篩選條件。  | 
|  `data` (Amazon MQ) 或 `key`和 `value`(Apache Kafka) 沒有篩選條件模式  |  純文字的字串  |  僅中繼資料上的 EventBridge 篩選條件，忽略 `data` 欄位 (Amazon MQ) 或 `key`和 `value` 欄位 (Apache Kafka)  | 
|  `data` (Amazon MQ) 或 `key`和 `value`(Apache Kafka) 沒有篩選條件模式  |  有效的 JSON  |  僅中繼資料上的 EventBridge 篩選條件，忽略 `data` 欄位 (Amazon MQ) 或 `key`和 `value` 欄位 (Apache Kafka)  | 
|  任何  |  非 UTF 編碼字串  |  僅中繼資料上的 EventBridge 篩選條件，忽略 `data` 欄位 (Amazon MQ) 或 `key`和 `value` 欄位 (Apache Kafka)  | 

## Lambda ESM 和 EventBridge 管道之間的差異
<a name="pipes-filter-esm-diff"></a>

篩選事件時，Lambda ESM 和 EventBridge 管道的運作方式通常相同。主要區別在於 ESM 有效載荷中不存在該 `eventSourceKey` 欄位。

## 在管道篩選條件中使用比較運算子
<a name="pipes-filter-comparison-operators"></a>

比較運算子可讓您建構符合事件中欄位值的事件模式。

如需支援在管道篩選條件中使用的比較運算子完整清單，請參閱 [比較運算子](eb-create-pattern-operators.md)。