本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon P EventBridge ipes 中的事件筛选
<a name="eb-pipes-event-filtering"></a>

使用 Pip EventBridge es，您可以过滤给定源的事件并仅处理其中的一部分。这种筛选的工作方式与使用事件模式对 EventBridge 事件总线或 Lambda 事件源映射进行筛选的方式相同。有关事件模式的更多信息，请参阅 [创建 Amazon EventBridge 事件模式](eb-event-patterns.md)。

筛选标准 `FilterCriteria` 对象是由筛选条件 `Filters` 列表组成的结构。每个过滤器都是一个定义过滤模式 (`Pattern`) 的结构。`Pattern` 是 JSON 筛选条件规则的字符串表示。`FilterCriteria` 对象与以下示例类似：

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

为了更清楚起见，以下是在纯 JSON 中展开的筛选条件 `Pattern` 的值。

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

亚马逊 Kinesis、亚马逊 MQ、亚马逊 MSK 和自我管理 Apache Kafka 对有效负载应用 Base64 编码，但不对元数据字段应用 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"
}
```

创建事件过滤器时，Pi EventBridge pes 可以访问事件内容。这些内容要么是 JSON 转义的，例如 Amazon SQS `body` 字段，要么是 base64 编码的，例如 Kinesis `data` 字段。如果您的数据是有效的 JSON，则您的输入模板或目标参数的 JSON 路径可以直接引用内容，因为 Pip EventBridge es 会自动对其进行解码。例如，如果 Kinesis 事件源是有效的 JSON，您可以使用 `<$.data.someKey>` 引用变量。

继续我们的示例，要筛选对象外部的未编码`partitionKey`元数据和`data`对象内部的 base64 编码`City`属性，您可以使用以下过滤器：`data`

```
{
  "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 Pipes 希望您的`FilterCriteria`格式与传入消息的格式相匹配，可以是有效的 JSON，也可以是纯字符串。如果不匹配，Pip EventBridge es 就会丢弃该消息。如果您`FilterCriteria`不包含`body`，这意味着您只能按元数据进行筛选，Pip EventBridge es 会跳过此检查。下表汇总了评估结果：


| 筛选条件模式 格式 | 传入格式 | 结果 | 
| --- | --- | --- | 
|  纯字符串  |  纯字符串  |  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 在创建或更新 Pipe 时会引发异常。过滤器模式必须是有效的 JSON 格式。  | 

## 筛选亚马逊托管流媒体 Apache Kafka、自我管理 Apache Kafka 和亚马逊 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 格式。那是因为在应用筛选条件之前，将 Apache Kafka 和 Amazon MQ 字节数组 EventBridge 解码为 UTF-8。如果您的消息使用其他编码（例如 UTF-16 或 ASCII），或者消息格式与格式不匹配，则仅 EventBridge 处理元数据过滤器。`FilterCriteria`下表汇总了具体行为：


| 筛选条件模式 格式 | 传入格式 | 结果 | 
| --- | --- | --- | 
|  纯字符串  |  纯字符串  |  EventBridge 根据您的筛选条件进行筛选。  | 
|  纯字符串  |  有效 JSON  |  EventBridge 仅筛选元数据，忽略`data`字段 (Amazon MQ) 或`key`和`value`字段 (Apache Kafka)  | 
|  有效 JSON  |  纯字符串  |  EventBridge 仅筛选元数据，忽略`data`字段 (Amazon MQ) 或`key`和`value`字段 (Apache Kafka)  | 
|  有效 JSON  |  有效 JSON  |  EventBridge 根据您的筛选条件进行筛选。  | 
|  `data`（亚马逊 MQ）或`key`和（Apache Kafk `value` a）没有筛选模式  |  纯字符串  |  EventBridge 仅筛选元数据，忽略`data`字段 (Amazon MQ) 或`key`和`value`字段 (Apache Kafka)  | 
|  `data`（亚马逊 MQ）或`key`和（Apache Kafk `value` a）没有筛选模式  |  有效 JSON  |  EventBridge 仅筛选元数据，忽略`data`字段 (Amazon MQ) 或`key`和`value`字段 (Apache Kafka)  | 
|  任何  |  非 UTF 编码的字符串  |  EventBridge 仅筛选元数据，忽略`data`字段 (Amazon MQ) 或`key`和`value`字段 (Apache Kafka)  | 

## Lambda ESM 和 Pipes 之间的区别 EventBridge
<a name="pipes-filter-esm-diff"></a>

筛选事件时，Lambda ESM 和 Pip EventBridge es 的操作方式通常相同。主要区别在于 ESM 有效负载中不存在 `eventSourceKey` 字段。

## 在管道筛选器中使用比较运算符
<a name="pipes-filter-comparison-operators"></a>

比较运算符使您能够构造与事件中的字段值匹配的事件模式。

有关支持在管道筛选器中使用的比较运算符的完整列表，请参阅[比较运算符](eb-create-pattern-operators.md)。