本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
控制 Lambda 傳送給函數的事件
您可以使用事件篩選來控制 Lambda 將哪些記錄從串流或佇列中傳送至函數。例如,您可以新增篩選器,以便函數僅處理包含特定資料參數的 Amazon SQS 訊息。事件篩選僅適用於特定事件來源對應。您可以將篩選器新增至下列 AWS 服務的事件來源對應:
-
Amazon DynamoDB
-
Amazon Kinesis Data Streams
-
Amazon MQ
-
Amazon Managed Streaming for Apache Kafka(Amazon)MSK
-
自我管理的 Apache Kafka
-
Amazon 簡單隊列服務(AmazonSQS)
如需使用特定事件來源篩選的特定資訊,請參閱使用不同的濾鏡 AWS 服務。Lambda 不支援 Amazon DocumentDB 的事件篩選。
依預設,最多可以為單一事件來源映射定義五種不同的篩選條件。您的篩選器在邏輯上是ORed在一起 如果事件來源的記錄滿足一個或多個篩選條件,則 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」 |
「名稱」:[{"equals-ignore-case「:「愛麗絲」}] |
及 |
位置為「紐約」,日期是「週一」 |
"Location": [ "New York" ], "Day": ["Monday"] |
或 |
PaymentType 是「信用卡」或「借記卡」 |
「PaymentType「: [「信用卡」,「借記卡」] |
或 (多個欄位) |
位置為「紐約」,或日期是「週一」。 |
"$or": [ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ] |
Not |
天氣是「下雨」以外的任何天氣 |
"Weather": [ { "anything-but": [ "Raining" ] } ] |
數字 (等於) |
價格為 100 |
"Price": [ { "numeric": [ "=", 100 ] } ] |
數字 (範圍) |
價格大於 10,且小於或等於 20 |
"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ] |
存在 |
ProductName 存在 |
「ProductName「:[{「存在」:真}] |
不存在 |
ProductName 不存在 |
「ProductName「:[{「存在」:假}] |
開頭為 |
區域位於美國 |
"Region": [ {"prefix": "us-" } ] |
結尾為 |
FileName 以 .png 副檔名結束。 |
「FileName「: [{「後綴」:「.png」}] |
注意
就像 EventBridge,對於字符串,Lambda 使用精確 character-by-character 匹配而不會折疊大小寫或任何其他字符串規範化。針對數字,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-name
my-function
\ --event-source-arnarn:aws:sqs:us-east-2:123456789012:my-queue
\ --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'
此 create-event-source-mapping命令會為my-function
具有指定的函數建立新的 Amazon SQS 事件來源映射FilterCriteria
。
若要將這些篩選條件標準新增到現有事件來源映射,請執行下列命令。
aws lambda update-event-source-mapping \ --uuid
"a1b2c3d4-5678-90ab-cdef-11111EXAMPLE"
\ --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'
請注意,若要更新事件來源對應,您需要它UUID。您可以UUID從電 list-event-source-mappings話中取得。Lambda 也返回 create-event-source-mappingCLI響應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 服務。
使用不同的濾鏡 AWS 服務
不同類型的事件來源對其資料欄位使用不同的索引鍵值。若要篩選資料屬性,請務必在篩選條件模式中使用正確的索引鍵。下表提供了每個支持的過濾鍵 AWS 服務。
AWS 服務 | 篩選索引鍵 |
---|---|
DynamoDB | dynamodb |
Kinesis | data |
Amazon MQ | data |
Amazon MSK | value |
自我管理的 Apache Kafka | value |
Amazon SQS | body |
下列各節提供不同類型事件來源的篩選器模式範例。其還為每個支援之服務提供支援的傳入資料格式和篩選條件模式內文格式的定義。