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

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

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

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

筛选条件规则语法

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

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

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

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

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

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

使用控制台输入筛选条件时，只需输入筛选条件模式，无需提供 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 权限才能成功查看纯文本筛选条件。

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

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

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

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

{
    "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 调用时以纯文本形式查看筛选条件。

{
    "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 服务 的筛选键。

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