Lambda のイベントフィルタリング - AWS Lambda

Lambda のイベントフィルタリング

Amazon Kinesis、Amazon DynamoDB、および Amazon Simple Queue Service (Amazon SQS) の各イベントソースでは、イベントフィルタリングを使用して、処理のために Lambda が関数に送信するイベントを制御できます。例えば、ステータスコードが ERROR の Kinesis ストリームからのレコードのみを処理するようにフィルター条件を定義できます。

単一のイベントソースに対して最大 5 つの異なるフィルターを定義することができます。イベントがこれら 5 つのフィルターのいずれかに該当する場合は、Lambda がそのイベントを関数に送信します。該当しない場合は、Lambda がそのイベントを破棄します。イベントは、フィルター条件に該当するか、該当しないかのいずれかになります。バッチ処理ウィンドウを使用している場合、Lambda は新しいイベントそれぞれにフィルター条件を適用して、それを現在のバッチに追加するかどうかを決定します。

イベントフィルタリングの基本

フィルター条件 (FilterCriteria) オブジェクトは、フィルターのリスト (Filters) で構成される構造です。各フィルター (Filter)は、イベントフィルタリングパターン (Pattern) を定義する構造です。Pattern は、JSON フィルタールールの文字列表現です。FilterCriteria オブジェクトは、以下の例のようになります。

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

以下は、わかりやすくするためにプレーン JSON で展開したフィルターの Pattern の値を記載しています。

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

FilterCriteria オブジェクトには、メタデータプロパティ、データプロパティ、およびフィルターパターンの 3 つの主要部分があります。例えば、イベントソースから以下のような Kinesis イベントを受け取るとします。

"kinesis": { "partitionKey": "1", "sequenceNumber": "49590338271490256608559692538361571095921575989136588898", "data": { "City": "Seattle", "State": "WA", "Temperature": "46", "Month": "December" }, "approximateArrivalTimestamp": 1545084650.987 }
  • メタデータプロパティは、イベントオブジェクトのフィールドです。この FilterCriteria 例では、Metadata1 がメタデータプロパティを参照します。この Kinesis イベントの例では、Metadata1partitionKey などのフィールドを参照できます。

  • データプロパティは、イベント本文のフィールドです。この FilterCriteria 例では、Data1 がデータプロパティを参照します。この Kinesis イベントの例では、Data1City および Temperature などのフィールドを参照できます。

    注記

    データプロパティをフィルタリングするには、それらを適切なキー内の FilterCriteria に含めるようにしてください。このキーは、イベントソースに応じて異なります。Kinesis イベントソースの場合、データキーは data です。Amazon SQS イベントソースのデータキーは body です。DynamoDB イベントソースのデータキーは dynamodb です。

  • フィルタールールは、特定のプロパティに適用するフィルターを定義します。この FilterCriteria 例では、rule1Metadata1 に適用され、rule2Data1 に適用されます。フィルタールールの構文は、使用する比較演算子に応じて異なります。詳細については、「フィルタールールの構文 フィルタリングの例」を参照してください。

FilterCriteria オブジェクトを作成するときは、フィルターに一致させるメタデータプロパティとデータプロパティのみを指定します。Lambda がイベントを一致として見なすには、フィルターに含まれているすべてのフィールド名がイベントに含まれている必要があります。Lambda は、フィルターに含まれていないフィールドを無視します。

フィルタールールの構文

Lambda は、フィルタールールに対して Amazon EventBridge と同じ構文とルールのセットをサポートします。詳細については、「Amazon EventBridge ユーザーガイド」の「Amazon EventBridge のイベントパターン」を参照してください。

以下は、Lambda のイベントフィルタリングで使用できるすべての比較演算子の概要です。

比較演算子 ルール構文

Null

UserId が Null

"UserID": [ null ]

LastName が空白

"LastName": [""]

等しい

Name が「Alice」

"Name": [ "Alice" ]

および

Location が「New York」、および Day が「Monday」

"Location": [ "New York" ], "Day": ["Monday"]

または

PaymentType が「Credit」または「Debit」

"PaymentType": [ "Credit", "Debit"]

以外

Weather が「Raining」以外

"Weather": [ { "anything-but": [ "Raining" ] } ]

数値 (等しい)

Price が 100

"Price": [ { "numeric": [ "=", 100 ] } ]

数値 (範囲)

Price が 10 より大きく 20 以下

"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ]

存在する

ProductName が存在

"ProductName": [ { "exists": true } ]

存在しない

ProductName が存在しない

"ProductName": [ { "exists": false } ]

から始まる

Region が US にある

"Region": [ {"prefix": "us-" } ]

注記

EventBridge と同様に、Lambda は文字列に対して文字単位の厳密な一致を使用し、大文字変換やその他の文字列の正規化は行いません。数値の場合、Lambda は文字列表現も使用します。たとえば、300、300.0、3.0e2 は等しいとはみなされません。

フィルタリングの例

Kinesis イベントソースがあり、特定の partitionKey (メタデータプロパティ) を持つイベントのみを処理するとします。さらに、「Los Angeles」に等しい Location フィールド (データプロパティ) を持つイベントのみを処理します。この場合、FilterCriteria オブジェクトは以下のようになります。

{ "Filters": [ { "Pattern": "{ \"partitionKey\": [ \"1\" ], \"data\": { \"Location\": [ \"Los Angeles\" ] }}" } ] }

以下は、わかりやすくするためにプレーン JSON で展開したフィルターの Pattern の値を記載しています。

{ "partitionKey": [ "1" ], "data": { "Location": [ "Los Angeles" ] } }

上記の例では、partitionKeyLocation の両方に比較演算子の等しいを使用します。

もう 1 つの例として、Temperature データプロパティが 50 を超えるが 60 以下であるイベントのみを処理するとします。この場合、FilterCriteria オブジェクトは以下のようになります。

{ "Filters": [ { "Pattern": "{ \"data\": { \"Temperature\": [ {\"numeric\": [ \">\", 50, \"<=\", 60 ] }]}" } ] }

以下は、わかりやすくするためにプレーン JSON で展開したフィルターの Pattern の値を記載しています。

{ "data": { "Temperature": [ {"numeric": [ ">", 50, "<=", 60 ] } ] } }

上記の例では、Temperature に比較演算子の数値 (範囲) を使用します。

マルチレベルフィルタリング

イベントフィルタリングを使用して、マルチレベル JSON のフィルタリングを処理することもできます。例えば、以下のようなデータオブジェクトを持つ DynamoDB ストリームイベントを受け取るとします。

"dynamodb": { "Keys": { "Id": { "N": "101" } }, "NewImage": { "Message": { "S": "New item!" }, "Id": { "N": "101" } }, "SequenceNumber": "111", "SizeBytes": 26, "StreamViewType": "NEW_AND_OLD_IMAGES" }

キー ID 値の N が 101 であるイベントのみを処理したいとしましょう。この場合、FilterCriteria オブジェクトは以下のようになります。

{ "Filters": [ { "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Id\": { \"N\": [ "101" ] } } } }" } ] }

以下は、わかりやすくするためにプレーン JSON で展開したフィルターの Pattern の値を記載しています。

{ "dynamodb": { "Keys": { "Id": { "N": [ "101" ] } } } }

上記の例では、dynamodb データフィールド内のネストされた複数レイヤーである N に比較演算子の等しいを使用します。

イベントソースマッピングへのフィルター条件のアタッチ (コンソール)

Lambda コンソールを使用してフィルター条件を持つ新しいイベントソースマッピングを作成するには、以下の手順を実行します。

フィルター条件が設定された新しいイベントソースマッピングを作成する (コンソール)

  1. Lambda コンソールの [Functions] (関数) ページを開きます。

  2. イベントソースマッピングを作成する関数の名前を選択します。

  3. [Function overview] (関数の概要) で [Add trigger] (トリガーを追加) をクリックします。

  4. [Trigger configuration] (トリガーの設定) で、イベントフィルタリングをサポートするトリガータイプを選択します。これには、[SQS][DynamoDB]、および [Kinesis] が含まれます。

  5. [Additional settings] (追加の設定) を展開します。

  6. [Filter criteria] (フィルター条件) で、フィルターを定義して入力します。例えば、以下を入力できます。

    { "a" : [ 1, 2 ] }

    これは、フィールド a が 1 または 2 に等しいレコードのみを処理するように Lambda に指示します。

  7. [Add] (追加) をクリックします。

コンソールを使用してフィルター条件を入力する場合は、フィルターパターンのみを指定します。上記の手順のステップ 6 では、{ "a" : [ 1, 2 ] } が以下の FilterCriteria に対応します。

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

コンソールでイベントソースマッピングを作成すると、トリガーの詳細にフォーマットされた FilterCriteria が表示されます。コンソールを使用してフィルターを入力する場合、Pattern キーまたはエスケープ引用符を入力する必要はありません。

注記

デフォルトで、イベントソースごとに 5 つの異なるフィルターを設定できます。イベントソースごとに 10 個までクォータの引き上げをリクエストできます。Lambda コンソールでは、アカウントの現在のクォータに応じて最大 10 個のフィルターを追加できます。現在のクォータで許可されている数よりも多くのフィルターを追加しようとすると、Lambda がイベントソースの作成時にエラーをスローします。

イベントソースマッピングへのフィルター条件のアタッチ (AWS CLI)

イベントソースマッピングに以下の FilterCriteria を設定するとします。

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

AWS Command Line Interface (AWS 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\": \"{ \"a\" : [ 1, 2 ]}\"}]}"

この CreateEventSourceMapping コマンドは、指定された FilterCriteria を使用して関数 my-function の新しい Amazon SQS イベントソースマッピングを作成します。

これらのフィルター条件を既存のイベントソースマッピングに追加するには、以下のコマンドを実行します。

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

イベントソースマッピングを更新するには、その UUID が必要であることに注意してください。UUID は、ListEventSourceMappings コールから取得できます。Lambda は、CreateEventSourceMapping API レスポンスでも UUID を返します。

イベントソースからフィルター条件を削除するには、空の FilterCriteria オブジェクトを使用して以下の UpdateEventSourceMapping コマンドを実行できます。

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

フィルタリングが適切な Amazon SQS メッセージ

Amazon SQS メッセージがフィルター条件を満たさない場合、Lambda はそのメッセージをキューから自動的に削除します。Amazon SQS でこれらのメッセージを手動で削除する必要はありません。

Amazon SQS の場合、メッセージ の body は任意の文字列にすることができますが、body が有効な JSON フォーマットであることを FilterCriteria が期待する場合は、これが問題になる可能性があります。逆の場合も同様です。着信メッセージの body が有効な JSON 形式である場合に、body がプレーン文字列であることをフィルター条件が期待していると、意図しない動作が発生する可能性があります。

この問題を回避するには、FilterCriteria 内の body の形式が、キューから受け取るメッセージの body に期待される形式と一致することを確認してください。メッセージをフィルタリングする前に、Lambda は着信メッセージの body の形式と body に対するフィルターパターンの形式を自動的に評価します。一致しない場合、Lambda はメッセージをドロップします。以下は、この評価を要約した表です。

着信メッセージの body の形式 フィルターパターンの body の形式 結果として生じるアクション

プレーン文字列

プレーン文字列

Lambda がフィルター条件に基づいてフィルタリングを実行します。

プレーン文字列

データプロパティのフィルターパターンがない

Lambda がフィルター条件に基づいて (他のメタデータプロパティのみを) フィルタリングします。

プレーン文字列

有効な JSON

Lambda がメッセージをドロップします。

有効な JSON

プレーン文字列

Lambda がメッセージをドロップします。

有効な JSON

データプロパティのフィルターパターンがない

Lambda がフィルター条件に基づいて (他のメタデータプロパティのみを) フィルタリングします。

有効な JSON

有効な JSON

Lambda がフィルター条件に基づいてフィルタリングを実行します。

FilterCriteria の一部として body を含めない場合、Lambda はこのチェックをスキップします。

フィルタリングが適切な Kinesis メッセージと DynamoDB メッセージ

フィルター条件が Kinesis または DynamoDB レコードを処理すると、ストリームイテレータはこのレコードを通り越して先に進みます。レコードがフィルター条件を満たさない場合に、そのレコードをイベントソースから手動で削除する必要はありません。保持期間が過ぎると、Kinesis と DynamoDB はこれらの古いレコードを自動的に削除します。それより早くレコードを削除したい場合は、「Changing the Data Retention Period」(データ保持期間の変更) を参照してください。

ストリームイベントソースからのイベントを適切にフィルタリングするには、データフィールドとデータフィールドのフィルター条件の両方が有効な JSON 形式である必要があります。(Kinesis のデータフィールドは data で、DynamoDB のデータフィールドは dynamodb です。) フィールドのどちらかが有効な JSON 形式ではない場合、Lambda はメッセージをドロップするか、例外をスローします。以下は、特定の動作を要約した表です。

着信データの形式 (data または dynamodb) データプロパティのフィルターパターンの形式 結果として生じるアクション

有効な JSON

有効な JSON

Lambda がフィルター条件に基づいてフィルタリングを実行します。

有効な JSON

データプロパティのフィルターパターンがない

Lambda がフィルター条件に基づいて (他のメタデータプロパティのみを) フィルタリングします。

有効な JSON

JSON 以外

Lambda がイベントソースマッピングの作成または更新時に例外をスローします。データプロパティのフィルターパターンは、有効な JSON 形式である必要があります。

JSON 以外

有効な JSON

Lambda がレコードをドロップします。

JSON 以外

データプロパティのフィルターパターンがない

Lambda がフィルター条件に基づいて (他のメタデータプロパティのみを) フィルタリングします。

JSON 以外

JSON 以外

Lambda がイベントソースマッピングの作成または更新時に例外をスローします。データプロパティのフィルターパターンは、有効な JSON 形式である必要があります。