本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
您可以使用事件篩選來控制 Lambda 將哪些記錄從串流或佇列中傳送至函數。例如，您可以新增篩選條件，讓函數僅處理包含特定資料參數的 Amazon SQS 訊息。事件篩選僅對特定事件來源映射有效。您可以將篩選條件新增至下列事件來源映射 AWS 服務：
-
Amazon DynamoDB
-
Amazon Kinesis Data Streams
-
Amazon MQ
-
Amazon Managed Streaming for Apache Kafka (Amazon MSK)
-
自我管理的 Apache Kafka
-
Amazon Simple Queue Service (Amazon SQS)
如需使用特定事件來源進行篩選的特定資訊，請參閱使用具有不同 的篩選條件 AWS 服務。Lambda 不支援 Amazon DocumentDB 的事件篩選。
依預設，最多可以為單一事件來源映射定義五種不同的篩選條件。篩選條件透過 OR 運算邏輯關聯。如果事件來源的記錄滿足一個或多個篩選條件，則 Lambda 會在它傳送至函數的下一個事件中包含該記錄。如果全部篩選條件都不滿足，則 Lambda 會捨棄該記錄。
注意
如果需要為一個事件來源定義五個以上的篩選條件，則可以為每個事件來源請求增加最多 10 個篩選條件的配額。如果您嘗試新增超過目前配額許可的篩選條件，Lambda 將在您嘗試建立事件來源時傳回錯誤。
主題
了解事件篩選基本知識
篩選條件標準 (FilterCriteria) 物件是由篩選條件清單 (Filters) 組成的結構。每個篩選條件均是定義事件篩選模式 (Pattern) 的結構。模式是 JSON 篩選條件規則的字串表示法。FilterCriteria 物件的結構如下所示。
{
"Filters": [
{
"Pattern": "{ \"Metadata1\": [ rule1 ], \"data\": { \"Data1\": [ rule2 ] }}"
}
]
}補充說明，此處是篩選條件的 Pattern 在純文字 JSON 中擴展的值。
{
"Metadata1": [ rule1 ],
"data": {
"Data1": [ rule2 ]
}
}篩選條件模式可以包含中繼資料屬性、資料屬性或兩者。可用的中繼資料參數和資料參數的格式會根據作為事件來源的 AWS 服務 而變化。例如，假設您的事件來源映射從 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欄位。
不同類型的事件來源對其資料欄位使用不同的索引鍵值。若要篩選資料屬性，請務必在篩選條件模式中使用正確的索引鍵。如需資料篩選金鑰的清單，以及查看每個支援之篩選模式的範例 AWS 服務，請參閱 使用具有不同 的篩選條件 AWS 服務。
事件篩選可處理多級 JSON 篩選。例如，考慮 DynamoDB 串流中的下列記錄片段：
"dynamodb": {
"Keys": {
"ID": {
"S": "ABCD"
}
"Number": {
"N": "1234"
},
...
}假設您只想處理排序索引鍵 Number 值為 4567 的記錄。在這種情況下，您的 FilterCriteria 物件看起來像這樣：
{
"Filters": [
{
"Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
}
]
}補充說明，此處是篩選條件的 Pattern 在純文字 JSON 中擴展的值。
{
"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 |
UserID 為 Null (空值) |
"UserID": [ null ] |
|
空白 |
LastName 為空白 |
"LastName": [""] |
|
等於 |
名稱為「Alice」 |
"Name": [ "Alice" ] |
|
等於 (忽略大小寫) |
名稱為「Alice」 |
"Name": [ { "equals-ignore-case": "alice" } ] |
|
及 |
位置為「紐約」，日期是「週一」 |
"Location": [ "New York" ], "Day": ["Monday"] |
|
或 |
PaymentType 為「信用卡」或「轉帳卡」 |
"PaymentType": [ "Credit", "Debit"] |
|
或 (多個欄位) |
位置為「紐約」，或日期是「週一」。 |
"$or": [ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ] |
|
Not |
天氣是「下雨」以外的任何天氣 |
"Weather": [ { "anything-but": [ "Raining" ] } ] |
|
數字 (等於) |
價格為 100 |
"Price": [ { "numeric": [ "=", 100 ] } ] |
|
數字 (範圍) |
價格大於 10，且小於或等於 20 |
"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ] |
|
存在 |
ProductName 已經存在 |
"ProductName": [ { "exists": true } ] |
|
不存在 |
ProductName 不存在 |
"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 主控台來建立具有篩選條件標準的新事件來源映射。
若要使用篩選條件標準 (主控台) 建立新事件來源映射
-
開啟 Lambda 主控台中的函數頁面
。 -
選擇要建立事件來源映射的函數名稱。
-
在函數概觀下，選擇新增觸發條件。
-
若為 Trigger configuration (觸發程序組態)，選擇支援事件篩選的觸發程序類型。如需支援的服務清單，請參閱本頁開頭的清單。
-
展開 Additional settings (其他設定)。
-
在 Filter criteria (篩選條件標準) 下，選擇 Add (新增)，然後定義並輸入您的篩選條件。例如，您可以輸入下列指令。
{ "Metadata" : [ 1, 2 ] }這會指示 Lambda 僅處理欄位
Metadata等於 1 或 2 的記錄。您可以繼續選取新增，新增更多篩選條件，直至達到允許的數目上限為止。 -
完成新增篩選條件時，請選擇儲存。
使用主控台輸入篩選條件標準時，僅需輸入篩選模式，而不需要提供 Pattern 索引鍵或逸出引號。在上述指示的步驟 6 中，{ "Metadata" : [ 1, 2 ] } 會對應下列 FilterCriteria。
{
"Filters": [
{
"Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
}
]
}在主控台中建立事件來源映射之後，您可以在觸發程序詳細資訊中看見格式化的 FilterCriteria。如需有關使用主控台建立事件篩選條件的更多範例，請參閱 使用具有不同 的篩選條件 AWS 服務。
將篩選條件標準連接至事件來源映射 (AWS CLI)
假設您想要事件來源映射具有下列 FilterCriteria：
{
"Filters": [
{
"Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
}
]
}若要使用 AWS Command Line Interface (AWS CLI) 使用這些篩選條件建立新的事件來源映射，請執行下列命令。
aws lambda create-event-source-mapping \ --function-namemy-function\ --event-source-arnarn: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 "{}"
如需使用 建立事件篩選條件的更多範例 AWS CLI，請參閱 使用具有不同 的篩選條件 AWS 服務。
將篩選條件標準連接至事件來源映射 (AWS SAM)
假設您想要在 中設定事件來源 AWS SAM ，以使用下列篩選條件：
{
"Filters": [
{
"Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
}
]
}若要將這些篩選條件標準新增到事件來源映射，請將下列程式碼片段插入事件來源的 YAML 範本中。
FilterCriteria:
Filters:
- Pattern: '{"Metadata": [1, 2]}'如需建立和設定事件來源映射 AWS SAM 範本的詳細資訊，請參閱 AWS SAM 開發人員指南中的 EventSource 一節。如需使用 AWS SAM 範本建立事件篩選條件的更多範例，請參閱 使用具有不同 的篩選條件 AWS 服務。
篩選條件加密
依預設，Lambda 不會加密篩選條件物件。對於可以在篩選條件物件中包含敏感資訊的使用案例，您可以使用自己的 KMS 金鑰來加密它。
加密篩選條件物件後，可以使用 GetEventSourceMapping API 呼叫檢視其純文字版本。必須具有 kms:Decrypt 許可，才能成功以純文字檢視篩選條件。
注意
如果篩選條件物件已加密，Lambda 會在 ListEventSourceMappings 呼叫回應中修訂 FilterCriteria 欄位的值。反之，此欄位會顯示為 null。若要查看真實的 FilterCriteria 值，請使用 GetEventSourceMapping API。
若要在主控台中檢視解密的 FilterCriteria 值，請確定您的 IAM 角色包含 GetEventSourceMapping 的許可。
您可以透過主控台、API/CLI 或 AWS CloudFormation指定自己的 KMS 金鑰。
若要使用客戶擁有的 KMS 金鑰加密篩選條件 (主控台)
-
開啟 Lambda 主控台中的函數頁面
。 -
選擇 Add trigger (新增觸發條件)。如果已有觸發條件，請選擇組態標籤，然後選擇觸發條件。選取現有觸發條件，然後選擇編輯。
-
選取使用客戶管理的 KMS 金鑰加密旁邊的核取方塊。
-
針對選擇客戶管理的 KMS 加密金鑰，選取現有的已啟用金鑰或建立新的金鑰。視操作而定，您需要以下部分或全部許可：
kms:DescribeKey、kms:GenerateDataKey和kms:Decrypt。使用 KMS 金鑰政策來授予這些許可。
如果您使用自己的 KMS 金鑰，必須在金鑰政策中允許下列 API 操作：
-
kms:Decrypt– 必須授予區域 Lambda 服務主體 (lambda.)。這將允許 Lambda 使用此 KMS 金鑰解密資料。AWS_region.amazonaws.com.rproxy.goskope.com-
為了防止跨服務混淆代理人問題，金鑰政策會使用
aws:SourceArn全域條件金鑰。aws:SourceArn金鑰鍵的正確值是事件來源映射資源的 ARN，因此您只有在知道其 ARN 之後，才能將此值新增至政策。在向 KMS 提出解密請求時，Lambda 也會在加密內容中轉送aws:lambda:FunctionArn和aws:lambda:EventSourceArn金鑰及其個別值。這些值必須符合金鑰政策中指定的條件，解密請求才會成功。不需要包含 EventSourceArn for Self-managed Kafka 事件來源，因為它們沒有 EventSourceArn。
-
-
kms:Decrypt– 還必須授予想要使用金鑰在 GetEventSourceMapping 或 DeleteEventSourceMapping API 呼叫中檢視純文字篩選條件的主體。 -
kms:DescribeKey— 提供客戶管理之金鑰的詳細資訊，以便指定主體可以使用金鑰。 -
kms:GenerateDataKey– 提供許可，讓 Lambda 代表指定的主體 (封套加密) 產生資料金鑰來加密篩選條件。
您可以使用 AWS CloudTrail 來追蹤 Lambda 代表您提出的 AWS KMS 請求。如需 CloudTrail 事件範例，請參閱 監控 Lambda 的加密金鑰。
我們也建議使用 kms:ViaService 條件金鑰，將 KMS 金鑰的使用限制為僅限來自 Lambda 的請求。此金鑰的值是區域 Lambda 服務主體 (lambda.)。以下是授予所有相關許可的金鑰政策範例：AWS_region.amazonaws.com
範例 AWS 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 AWS CLI 命令。使用 --kms-key-arn 旗標指定 KMS 金鑰 ARN。
aws lambda create-event-source-mapping --function-name my-function \ --maximum-batching-window-in-seconds 60 \ --event-source-arnarn:aws:sqs:us-east-1:123456789012:my-queue\ --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \ --kms-key-arnarn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599
如果已有事件來源映射，請改用 UpdateEventSourceMapping AWS CLI 命令。使用 --kms-key-arn 旗標指定 KMS 金鑰 ARN。
aws lambda update-event-source-mapping --function-name my-function \ --maximum-batching-window-in-seconds 60 \ --event-source-arnarn:aws:sqs:us-east-1:123456789012:my-queue\ --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \ --kms-key-arnarn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599
此操作會覆寫先前指定的 KMS 金鑰。如果您指定 --kms-key-arn 旗標和空引數，Lambda 會停止使用 KMS 金鑰來加密篩選條件。反之，Lambda 會預設回使用 Amazon 擁有的金鑰。
若要在 AWS CloudFormation 範本中指定您自己的 KMS 金鑰，請使用 AWS::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 呼叫的 AWS CloudTrail 日誌中。如果您的函數使用事件篩選，FilterCriteria 欄位會顯示為空白 ({})。如果您具有正確 KMS 金鑰的 kms:Decrypt 許可，仍然可以在 GetEventSourceMapping API 呼叫的回應中以純文字檢視篩選條件。
在 CreateEventSourceMapping 呼叫的下列 AWS 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"
}使用具有不同 的篩選條件 AWS 服務
不同類型的事件來源對其資料欄位使用不同的索引鍵值。若要篩選資料屬性，請務必在篩選條件模式中使用正確的索引鍵。下表提供每個支援的篩選金鑰 AWS 服務。
| AWS 服務 | 篩選索引鍵 |
|---|---|
| DynamoDB | dynamodb |
| Kinesis | data |
| Amazon MQ | data |
| Amazon MSK | value |
| 自我管理的 Apache Kafka | value |
| Amazon SQS | body |
下列各節提供不同類型事件來源的篩選模式範例。其還為每個支援之服務提供支援的傳入資料格式和篩選條件模式內文格式的定義。
