了解事件筛选基础知识处理不符合筛选条件的记录筛选条件规则语法将筛选条件附加到事件源映射（控制台）将筛选条件附加到事件源映射（Amazon CLI）将筛选条件附加到事件源映射（Amazon SAM）筛选条件的加密使用具有不同 Amazon Web Services 服务的筛选条件

控制 Lambda 向您的函数发送的事件

您可以使用事件筛选，控制 Lambda 将流或队列中的哪些记录发送给函数。例如，您可以添加筛选条件，以便函数仅处理包含特定数据参数的 Amazon SQS 消息。事件筛选仅适用于某些事件源映射。您可以将筛选条件添加到以下 Amazon 服务的事件源映射中：

Amazon DynamoDB
Amazon Kinesis Data Streams
Amazon MQ
Amazon Managed Streaming for Apache Kafka (Amazon MSK)
自行管理的 Apache Kafka
Amazon Simple Queue Service(Amazon SQS)

有关在特定事件源中筛选的具体信息，请参阅使用具有不同 Amazon Web Services 服务的筛选条件。Lambda 不支持 Amazon DocumentDB 的事件筛选。

默认情况下，您可以为单个事件源映射定义最多五个不同的筛选条件。筛选条件是使用逻辑运算符 OR 组合起来的。如果来自事件源的记录符合一个或多个筛选条件，则 Lambda 会将该记录包含在发送到函数的下一个事件中。如果不符合任何筛选条件，Lambda 会丢弃该记录。

注意

如果您需要为一个事件源定义 5 个以上的筛选条件，可请求将每个事件源的配额提高到 10 个筛选条件。如果您尝试添加的筛选条件数量超过当前配额允许的数量，则在创建事件源时，Lambda 将会返回错误。

了解事件筛选基础知识

筛选条件 (FilterCriteria) 对象是一个由筛选条件 (Filters) 列表组成的结构。每个筛选条件都是一个用于定义事件筛选模式 (Pattern) 的结构。模式是 JSON 筛选条件规则的字符串表示。FilterCriteria 对象的结构如下所示。


{
   "Filters": [
        {
            "Pattern": "{ \"Metadata1\": [ rule1 ], \"data\": { \"Data1\": [ rule2 ] }}"
        }
    ]
}

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


{
    "Metadata1": [ rule1 ],
    "data": {
        "Data1": [ rule2 ]
    }
}

筛选条件模式可以包括元数据属性和/或数据属性。可用元数据参数和数据参数的格式根据充当事件源的 Amazon Web Services 服务而有所不同。例如，假设事件源映射从 Amazon SQS 队列接收到以下记录：


{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "City": "Seattle",\n "State": "WA",\n "Temperature": "46"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
    },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
    "awsRegion": "us-east-2"
}

元数据属性是包含有关创建记录的事件的信息的字段。在示例 Amazon SQS 记录中，元数据属性包括 messageID、eventSourceArn 和 awsRegion 等字段。
数据属性是包含流或队列中数据的记录的字段。在 Amazon SQS 事件示例中，数据字段的键是 body，数据属性是字段 City、State 和 Temperature。

不同类型的事件源为其数据字段使用不同的键值。要对数据属性进行筛选，请确保在筛选条件的模式中使用正确的键。如需数据筛选键列表，并查看每个支持的 Amazon Web Services 服务的筛选模式示例，请参阅使用具有不同 Amazon Web Services 服务的筛选条件。

事件筛选可处理多层 JSON 筛选。例如，考虑以下来自 DynamoDB 流的记录片段：


"dynamodb": {
    "Keys": {
        "ID": {
            "S": "ABCD"
        }
        "Number": {
            "N": "1234"
    },
    ...
}

假设您只想处理排序键值 Number 为 4567 的记录。在这种情况下，您的 FilterCriteria 对象与以下类似：


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
        }
    ]
}

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


{
    "dynamodb": {
        "Keys": {
            "Number": {
                "N": [ "4567" ]
                }
            }
        }
}

处理不符合筛选条件的记录

Lambda 如何处理不符合筛选条件的记录取决于事件源。

对于 Amazon SQS，如果消息不符合筛选条件，Lambda 会自动从队列中删除该消息。您无需在 Amazon SQS 中手动删除这些消息。
对于 Kinesis 和 DynamoDB，在筛选条件评估记录后，流迭代器会跳过此记录。如果记录不符合筛选条件，您无需从事件源手动删除记录。保留期结束后，Kinesis 和 DynamoDB 会自动删除这些旧记录。如果您希望提前删除记录，请参阅更改数据保留期。
对于 Amazon MSK、自行管理的 Apache Kafka 和 Amazon MQ 消息，Lambda 会丢弃与筛选条件中包含的所有字段不匹配的消息。对于 Amazon MSK 和自行管理的 Apache Kafka，Lambda 在成功调用函数后，会为匹配和不匹配的消息提交偏移。对于 Amazon MQ，Lambda 在成功调用函数后确认匹配的消息，并在筛选不匹配的消息时确认此类消息。

筛选条件规则语法

对于筛选条件规则，Lambda 支持 Amazon EventBridge 规则，并使用与 EventBridge 相同的语法。有关更多信息，请参阅 Amazon EventBridge 用户指南中的 Amazon EventBridge 事件模式。

以下是可用于 Lambda 事件筛选的所有比较运算符的汇总。

比较运算符	示例	Rule syntax（规则语法）
Null	用户 ID 为空	"UserID": [ null ]
空	姓氏为空	"LastName": [""]
等于	名字为“Alice”	"Name": [ "Alice" ]
等于（忽略大小写）	名字为“Alice”	“Name”：[ { "equals-ignore-case": "alice" } ]
并且	位置为“纽约”，日期为“星期一”	"Location": [ "New York" ], "Day": ["Monday"]
Or	付款类型为“信用卡”或“借记卡”	"PaymentType": [ "Credit", "Debit"]
或（多个字段）	位置为“纽约”，或日期为“星期一”。	“$or”：[ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ]
非	天气是除“下雨”以外的任何天气	"Weather": [ { "anything-but": [ "Raining" ] } ]
数值（等于）	价格为 100	"Price": [ { "numeric": [ "=", 100 ] } ]
数值（范围）	价格大于 10，且小于等于 20	"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ]
存在	产品名存在	"ProductName": [ { "exists": true } ]
不存在	产品名不存在	"ProductName": [ { "exists": false } ]
始于	地区位于美国	"Region": [ {"prefix": "us-" } ]
结束于	文件名以 .png 扩展名结尾。	“FileName”：[ { "suffix": ".png" } ]

注意

与 EventBridge 一样，对于字符串，Lambda 使用精确的逐个字符匹配，而不进行小写化或任何其他字符串标准化。此外，对于数值，Lambda 使用字符串表示。例如，300、300.0 和 3.0e2 不相等。

请注意，Exists 运算符仅适用于事件源 JSON 中的叶节点，与中间节点不匹配。例如，使用以下 JSON，筛选条件模式 { "person": { "address": [ { "exists": true } ] } }" 找不到匹配项，因为 "address" 是中间节点。


{
  "person": {
    "name": "John Doe",
    "age": 30,
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "country": "USA"
    }
  }
}

将筛选条件附加到事件源映射（控制台）

按照以下步骤使用 Lambda 控制台创建包含筛选条件的新事件源映射。

使用筛选条件创建新事件源映射（控制台）

打开 Lamba 控制台的函数页面。
选择要为其创建事件源映射的函数名称。
在 Function overview（函数概览）下，选择 Add trigger（添加触发器）。
对于 Trigger configuration（触发器配置），请选择支持事件筛选的触发器类型。有关受支持的服务列表，请参阅本页开头的列表。
展开其他设置。
在 Filter criteria（筛选条件）下，选择 Add（添加），然后定义并输入筛选条件。例如，您可以输入以下筛选条件。
```
{ "Metadata" : [ 1, 2 ] }
```
这指示 Lambda 只处理字段 Metadata 等于 1 或 2 的记录。您可以继续选择添加，以添加更多筛选条件，但不得超过最大允许数量。
添加完筛选条件后，选择保存。

使用控制台输入筛选条件时，只需输入筛选条件模式，无需提供 Pattern 键或转义引号。在上述说明的第 6 步中，{ "Metadata" : [ 1, 2 ] } 对应于下面的 FilterCriteria。


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

在控制台中创建事件源映射后，您可以在触发器详细信息中看到格式化后的 FilterCriteria。有关使用控制台创建事件筛选条件的更多示例，请参阅使用具有不同 Amazon Web Services 服务的筛选条件。

将筛选条件附加到事件源映射（Amazon CLI）

假设您希望事件源映射具有以下 FilterCriteria：


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

要使用 Amazon Command Line Interface（Amazon CLI）创建包含这些筛选条件的新事件源映射，请运行以下命令。


aws lambda create-event-source-mapping \
    --function-name my-function \
    --event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

此 create-event-source-mapping 命令将为包含指定 FilterCriteria 的函数 my-function 创建新的 Amazon SQS 事件源映射。

要将这些筛选条件添加到现有事件源映射中，请运行以下命令。


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

请注意，要更新事件源映射，您需要其 UUID。您可以通过 list-event-source-mappings 调用获取 UUID。Lambda 还会在 create-event-source-mapping CLI 响应中返回 UUID。

要从事件源中删除筛选条件，您可以运行以下包含空 FilterCriteria 对象的 update-event-source-mapping 命令。


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria "{}"

有关使用 Amazon CLI 创建事件筛选条件的更多示例，请参阅使用具有不同 Amazon Web Services 服务的筛选条件。

将筛选条件附加到事件源映射（Amazon SAM）

假设您要在 Amazon SAM 中配置事件源以使用以下筛选条件：


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

要将这些筛选条件添加到事件源映射中，请将以下代码段插入事件源的 YAML 模板中。


FilterCriteria: 
  Filters: 
    - Pattern: '{"Metadata": [1, 2]}'

有关为事件源映射创建和配置 Amazon SAM 模板的更多信息，请参阅《Amazon SAM 开发人员指南》中的 EventSource 部分。有关使用 Amazon SAM 模板创建事件筛选条件的更多示例，请参阅使用具有不同 Amazon Web Services 服务的筛选条件。

筛选条件的加密

默认情况下，Lambda 不会加密您的筛选条件对象。对于可能在筛选条件对象中包含敏感信息的应用场景，您可以使用自己的 KMS 密钥对其进行加密。

加密筛选条件对象后，您可以使用 GetEventSourceMapping API 调用查看其纯文本版本。您必须拥有 kms:Decrypt 权限才能成功查看纯文本筛选条件。

注意

如果您的筛选条件对象已加密，Lambda 会在 ListEventSourceMappings 调用的响应中编辑 FilterCriteria 字段的值。相反，此字段显示为 null。要查看 FilterCriteria 的真实值，请使用 GetEventSourceMapping API。

要在控制台中查看 FilterCriteria 解密后的值，请确保您的 IAM 角色包含使用 GetEventSourceMapping 的权限。

您可以通过控制台、API/CLI 或 Amazon CloudFormation 指定自己的 KMS 密钥。

使用客户自有 KMS 密钥加密筛选条件（控制台）

打开 Lamba 控制台的函数页面。
选择添加触发器。如果您已有触发器，请选择配置选项卡，然后选择触发器。选择现有触发器，然后选择编辑。
选中使用客户自主管理型 KMS 密钥加密旁边的复选框。
在选择客户自主管理型 KMS 加密密钥中，选择已启用的现有密钥或创建新密钥。根据操作的不同，您需要以下部分或全部权限：kms:DescribeKey、kms:GenerateDataKey 和 kms:Decrypt。使用 KMS 密钥政策授予这些权限。

如果您使用自己的 KMS 密钥，密钥政策中必须允许以下 API 操作：

kms:Decrypt – 必须授予区域 Lambda 服务主体 (lambda.AWS_region.amazonaws.com)。允许 Lambda 使用此 KMS 密钥解密数据。
- 为防止跨服务混淆代理问题，密钥政策使用 aws:SourceArn 全局条件密钥。aws:SourceArn 密钥的正确值是您的事件源映射资源的 ARN，因此只有在知道其 ARN 之后，才能将其添加到政策中。在向 KMS 发出解密请求时，Lambda 还会在加密上下文中转发 aws:lambda:FunctionArn 和 aws:lambda:EventSourceArn 密钥及其各自的值。这些值必须与密钥政策中的指定条件相匹配，解密请求才能成功。您无需为自行管理的 Kafka 事件源添加 EventSourceArn，因为它们没有 EventSourceArn。
kms:Decrypt – 还必须授予打算使用密钥在 GetEventSourceMapping 或 DeleteEventSourceMapping API 调用中查看纯文本筛选条件的主体。
kms:DescribeKey – 提供客户自主管理型密钥详细信息以允许主体使用密钥。
kms:GenerateDataKey – 为 Lambda 提供代表指定主体生成数据密钥以加密筛选条件的权限（信封加密）。

您可以使用 Amazon CloudTrail 来跟踪 Lambda 代表您发出的 Amazon KMS 请求。有关 CloudTrail 事件示例，请参阅为 Lambda 监控您的加密密钥。

我们还建议使用 kms:ViaService 条件密钥将 KMS 密钥的使用限制为仅限来自 Lambda 的请求。此密钥的值是区域 Lambda 服务主体 (lambda.AWS_region.amazonaws.com)。以下是授予所有相关权限的密钥政策示例：

例 Amazon KMS 密钥政策


{
    "Version": "2012-10-17",
    "Id": "example-key-policy-1",
    "Statement": [
        {
            "Sid": "Allow Lambda to decrypt using the key",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.us-east-1.amazonaws.com"
            },
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnEquals" : {
                    "aws:SourceArn": [
                        "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:<esm_uuid>"
                    ]
                },
                "StringEquals": {
                    "kms:EncryptionContext:aws:lambda:FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:test-function",
                    "kms:EncryptionContext:aws:lambda:EventSourceArn": "arn:aws:sqs:us-east-1:123456789012:test-queue"
                }
            }
        },
        {
            "Sid": "Allow actions by an AWS account on the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key to specific roles",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
            },
            "Action": [
                "kms:Decrypt",
                "kms:DescribeKey",
                "kms:GenerateDataKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals" : {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

要使用自己的 KMS 密钥对筛选条件进行加密，也可以使用以下 CreateEventSourceMapping Amazon CLI 命令。使用 --kms-key-arn 标志指定 KMS 密钥 ARN。


aws lambda create-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

如果您已有事件源映射，请改用 UpdateEventSourceMapping Amazon CLI 命令。使用 --kms-key-arn 标志指定 KMS 密钥 ARN。


aws lambda update-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

此操作将覆盖先前指定的任何 KMS 密钥。如果您指定 --kms-key-arn 标志和空实参，Lambda 将停止使用您的 KMS 密钥来加密筛选条件。相反，Lambda 默认使用 Amazon 拥有的密钥。

要在 Amazon CloudFormation 模板中指定您自己的 KMS 密钥，请使用 Amazon::Lambda::EventSourceMapping 资源类型的 KMSKeyArn 属性。例如，您可以将以下代码段插入事件源的 YAML 模板中。


MyEventSourceMapping:
  Type: AWS::Lambda::EventSourceMapping
  Properties:
    ...
    FilterCriteria:
      Filters:
        - Pattern: '{"a": [1, 2]}'
    KMSKeyArn: "arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599"
    ...

要能够在 GetEventSourceMapping 或 DeleteEventSourceMapping API 调用中以纯文本形式查看加密的筛选条件，您必须拥有 kms:Decrypt 权限。

从 2024 年 8 月 6 日起，如果您的函数不使用事件筛选，FilterCriteria 字段将不再显示在 CreateEventSourceMapping、UpdateEventSourceMapping 和 DeleteEventSourceMapping API 调用的Amazon CloudTrail 日志中。如果您的函数确实使用了事件筛选，则 FilterCriteria 字段将显示为空 ({})。如果拥有正确 KMS 密钥的 kms:Decrypt 权限，则仍然可以在响应 GetEventSourceMapping API 调用时以纯文本形式查看筛选条件。

在以下 CreateEventSourceMapping 调用的 Amazon CloudTrail 示例日志条目中，由于该函数使用事件筛选，FilterCriteria 显示为空 ({})。即使 FilterCriteria 对象包含函数正在使用的有效筛选条件，也是如此。如果该函数不使用事件筛选，则 CloudTrail 根本不会在日志条目中显示 FilterCriteria 字段。


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AROA123456789EXAMPLE:userid1",
        "arn": "arn:aws:sts::123456789012:assumed-role/Example/example-role",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AROA987654321EXAMPLE",
                "arn": "arn:aws:iam::123456789012:role/User1",
                "accountId": "123456789012",
                "userName": "User1"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2024-05-09T20:35:01Z",
                "mfaAuthenticated": "false"
            }
        },
        "invokedBy": "AWS Internal"
    },
    "eventTime": "2024-05-09T21:05:41Z",
    "eventSource": "lambda.amazonaws.com",
    "eventName": "CreateEventSourceMapping20150331",
    "awsRegion": "us-east-2",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "requestParameters": {
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "functionName": "example-function",
        "enabled": true,
        "batchSize": 10,
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "scalingConfig": {},
        "maximumBatchingWindowInSeconds": 0,
        "sourceAccessConfigurations": []
    },
    "responseElements": {
        "uUID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
        "batchSize": 10,
        "maximumBatchingWindowInSeconds": 0,
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:example-function",
        "lastModified": "May 9, 2024, 9:05:41 PM",
        "state": "Creating",
        "stateTransitionReason": "USER_INITIATED",
        "functionResponseTypes": [],
        "eventSourceMappingArn": "arn:aws:lambda:us-east-2:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLEbbbbb"
    },
    "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
    "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}

使用具有不同 Amazon Web Services 服务的筛选条件

不同类型的事件源为其数据字段使用不同的键值。要对数据属性进行筛选，请确保在筛选条件的模式中使用正确的键。下表给出了每个受支持 Amazon Web Services 服务的筛选键。

Amazon Web Services 服务	筛选键
DynamoDB	`dynamodb`
Kinesis	`data`
Amazon MQ	`data`
Amazon MSK	`value`
自行管理的 Apache Kafka	`value`
Amazon SQS	`body`

以下各节介绍了不同类型事件源的筛选条件模式示例。还为每个受支持的服务提供支持的传入数据格式和筛选条件模式正文格式的定义。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

事件源映射标签

在控制台中测试