Filtrado de eventos de Lambda - AWS Lambda

Filtrado de eventos de Lambda

Para los orígenes de eventos de Amazon Kinesis, Amazon DynamoDB y Amazon Simple Queue Service (Amazon SQS), puede utilizar el filtrado de eventos para controlar qué eventos envía Lambda a su función para su procesamiento. Por ejemplo, puede definir criterios de filtro para que procese solo los registros de un flujo de Kinesis que tenga el código de estado ERROR.

Puede definir hasta cinco filtros diferentes para un único origen de eventos. Si un evento cumple alguno de estos cinco filtros, Lambda envía el evento a la función. De lo contrario, Lambda descarta el evento. Un evento cumple los criterios de filtro o no los cumple. Si usa plazos de procesamiento por lotes, Lambda aplica los criterios de filtro a cada evento nuevo para determinar si se agrega al lote actual.

Conceptos básicos del filtrado de eventos

Un objeto de criterios de filtro (FilterCriteria) es una estructura que consta de una lista de filtros (Filters). Cada filtro (Filter) es una estructura que define un patrón de filtrado de eventos (Pattern). Un Pattern es una representación de cadenas de una regla de filtro de JSON. Un objeto FilterCriteria es similar al siguiente ejemplo:

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

Para mayor claridad, este es el valor del Pattern del filtro ampliado en JSON no cifrado:

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

Un objeto FilterCriteria consta de tres partes principales: propiedades de metadatos, propiedades de datos y patrones de filtrado. Por ejemplo, supongamos que recibe un evento de Kinesis de un origen de eventos similar al siguiente:

"kinesis": { "partitionKey": "1", "sequenceNumber": "49590338271490256608559692538361571095921575989136588898", "data": { "City": "Seattle", "State": "WA", "Temperature": "46", "Month": "December" }, "approximateArrivalTimestamp": 1545084650.987 }
  • Las propiedades de metadatos son los campos del objeto de eventos. En el ejemplo FilterCriteria, Metadata1 hace referencia a una propiedad de metadatos. En el ejemplo del evento de Kinesis, Metadata1 podría referirse a un campo como partitionKey.

  • Las propiedades de datos son los campos del cuerpo del evento. En el ejemplo FilterCriteria, Data1 hace referencia a una propiedad de datos. En el ejemplo del evento de Kinesis, Data1 podría referirse a campos como City y Temperature.

    nota

    Para filtrar las propiedades de datos, asegúrese de incluirlas en FilterCriteria dentro de la clave adecuada. Esta clave depende del origen de eventos. Para los orígenes de eventos de Kinesis, la clave de datos es data. Para los orígenes de eventos de Amazon SQS, la clave de datos es body. Para los orígenes de eventos de DynamoDB, la clave de datos es dynamodb.

  • Las reglas de filtro definen el filtro que quiere aplicar a una propiedad específica. En el ejemplo FilterCriteria, rule1 se aplica a Metadata1, y rule2 se aplica a Data1. La sintaxis de la regla de filtro depende del operador de comparación que utilice. Para obtener más información, consulte Sintaxis de la regla de filtro Ejemplos de filtrado.

Al crear un objeto FilterCriteria, especifique solo las propiedades de metadatos y las propiedades de datos con las que quiere que coincida el filtro. Para que Lambda considere el evento como una coincidencia, el evento debe contener todos los nombres de campos incluidos en un filtro. Lambda ignora los campos que no se incluyen en un filtro.

Sintaxis de la regla de filtro

Para las reglas de filtro, Lambda admite el mismo conjunto de sintaxis y reglas que Amazon EventBridge. Para obtener más información, consulte Amazon EventBridge event patterns (Patrones de eventos de Amazon EventBridge) en la Guía del usuario de Amazon EventBridge.

A continuación, se muestra un resumen de todos los operadores de comparación disponibles para el filtrado de eventos de Lambda.

Operador de comparación Ejemplo Sintaxis de reglas

Null

El valor de UserID (ID de usuario) es nulo

“UserID”: [null]

Vacío

LastName (Apellido) está vacío

“LastName”: [“”]

Igual

El valor de Name (Nombre) es “Alice”

“Name”: [“Alice”]

And

El valor de Location (Ubicación) es “New York” y el de Day (Día) es “Monday”

“Location”: [“New York”], “Day”: [“Monday”]

O bien

El valor de PaymentType (Tipo de pago) es “Credit” (Crédito) o “Debit” (Débito)

“PaymentType”: [“Credit”, “Debit”]

No

El valor de Weather (Tiempo) es cualquier valor menos “Raining” (Lluvia)

“Weather”: [{“anything-but”: [“Raining”]}]

Valor numérico (igual a)

El valor de Price (Precio) es 100

“Price”: [{“numeric”: [“=”, 100]}]

Valor numérico (rango)

El valor de Price (Precio) es superior a 10 e inferior o igual a 20

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

Exists

ProductName (Nombre de producto) existe

“ProductName”: [{“exists”: true}]

No existe

El valor de ProductName (Nombre de producto) no existe

“ProductName”: [{“exists”: false}]

Comienza por

El valor de Region (Región) se encuentra en US (EE. UU.)

“Region”: [{“prefix”: “us-”}]

nota

Al igual que EventBridge, para las cadenas, Lambda usa coincidencia exacta (carácter a carácter) sin necesidad de cambio de mayúsculas y minúsculas ni cualquier otra normalización de cadenas. Para los números, Lambda también usa la representación de cadenas. Por ejemplo, 300, 300.0 y 3.0e2 no se consideran iguales.

Ejemplos de filtrado

Supongamos que tiene un origen de eventos de Kinesis y quiere que su función gestione solo eventos con una partitionKey específica (una propiedad de metadatos). Además, solo quiere procesar eventos en los que el campo Location (una propiedad de datos) sea igual a “Los Angeles”. En este caso, el objeto FilterCriteria sería similar al siguiente:

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

Para mayor claridad, este es el valor del Pattern del filtro ampliado en JSON no cifrado.

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

En el ejemplo anterior, se usa el operador de comparación Equals (Igual a) para partitionKey y Location.

Por ejemplo, supongamos que solo quiere gestionar eventos en los que la propiedad de datos Temperature sea superior a 50, pero inferior o igual a 60. En este caso, el objeto FilterCriteria sería similar al siguiente:

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

Para mayor claridad, este es el valor del Pattern del filtro ampliado en JSON no cifrado.

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

En el ejemplo anterior se utiliza el operador de comparación Valor numérico (rango) para Temperature.

Filtrado multinivel

También puede utilizar el filtrado de eventos para gestionar el filtrado JSON multinivel. Por ejemplo, supongamos que recibe un evento de flujo de DynamoDB con un objeto de datos similar al siguiente:

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

Supongamos que solo quiere gestionar eventos en los que el valor del ID de clave, N, sea 101. En este caso, el objeto FilterCriteria sería similar al siguiente:

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

Para mayor claridad, este es el valor del Pattern del filtro ampliado en JSON no cifrado.

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

En el ejemplo anterior se utiliza el operador de comparación Equals (Igual a) para N, que anida varias capas dentro del campo de datos de dynamodb.

Adjuntar criterios de filtro a una asignación de origen de eventos (consola)

Siga estos pasos para crear una nueva asignación de origen de eventos con criterios de filtro mediante la consola de Lambda.

Para crear una nueva asignación de origen de eventos con criterios de filtro (consola)

  1. Abra la página de Functions (Funciones) en la consola de Lambda.

  2. Elija el nombre de la función para la que se creará una asignación de origen de eventos.

  3. En Function overview (Descripción general de la función), elija Add trigger (Agregar disparador).

  4. En Trigger configuration (Configuración del desencadenador), elija un tipo de desencadenador compatible con el filtrado de eventos. Por ejemplo, SQS, DynamoDB y Kinesis.

  5. Amplíe Additional settings (Configuración adicional).

  6. En Filter criteria (Criterios de filtro), defina e ingrese los filtros. Por ejemplo, puede ingresar lo siguiente:

    { "a" : [ 1, 2 ] }

    De este modo, Lambda solo procesa los registros en los que el campo a es igual a 1 o 2.

  7. Elija Add.

Al ingresar criterios de filtro mediante la consola, solo proporciona el patrón de filtro. En el paso 6 de las instrucciones anteriores, { "a" : [ 1, 2 ] } corresponde a los siguientes FilterCriteria:

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

Después de crear la asignación de origen de eventos en la consola, puede ver los FilterCriteria con formato en los detalles del desencadenador. Tenga en cuenta que, al ingresar los filtros mediante la consola, no es necesario proporcionar la clave del Pattern ni incluir ningún carácter de escape en las comillas.

nota

De forma predeterminada, puede tener cinco filtros diferentes por cada origen de eventos. Puede solicitar un aumento de cuota para un máximo de 10 filtros por cada origen de eventos. La consola de Lambda le permite agregar hasta 10 filtros en función de la cuota actual de la cuenta. Si intenta agregar más filtros de los que permite su cuota actual, se produce un error en Lambda al intentar crear el origen de eventos.

Adjuntar criterios de filtro a una asignación de origen de eventos (AWS CLI)

Supongamos que quiere que una asignación de origen de eventos tenga los siguientes FilterCriteria:

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

Para crear una nueva asignación de origen de eventos con estos criterios de filtro mediante AWS Command Line Interface (AWS CLI), ejecute el siguiente comando:

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 ]}\"}]}"

El comando CreateEventSourceMapping crea una nueva asignación de origen de eventos de Amazon SQS para la función my-function con los FilterCriteria especificados.

Para agregar estos criterios de filtro a una asignación de origen de eventos existente, ejecute el siguiente comando:

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

Tenga en cuenta que, para actualizar una asignación de origen de eventos, necesita su UUID. Puede obtener el UUID con una llamada a ListEventSourceMappings. Lambda también devuelve el UUID en la respuesta de la API CreateEventSourceMapping.

Para eliminar los criterios de filtro de un origen de eventos, puede ejecutar el comando UpdateEventSourceMapping con un objeto FilterCriteria vacío:

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

Filtrar correctamente los mensajes de Amazon SQS

Si un mensaje de Amazon SQS no cumple los criterios de filtro, Lambda lo elimina automáticamente de la cola. No tiene que eliminar manualmente estos mensajes en Amazon SQS.

Para Amazon SQS, el body del mensaje puede ser cualquier cadena. Sin embargo, esto puede ser problemático si los FilterCriteria esperan que el formato JSON del body sea válido. El escenario inverso también es verdadero, si el formato JSON del body del mensaje entrante es válido, lo que puede dar lugar a un comportamiento no deseado si los criterios de filtro esperan que el body sea una cadena sin formato.

Para evitar este problema, asegúrese de que el formato del body de los FilterCriteria coincida con el formato esperado del body de los mensajes que recibe de la cola. Antes de filtrar los mensajes, Lambda evalúa automáticamente el formato del body del mensaje entrante y del patrón de filtro del body. Si no coincide, Lambda elimina el mensaje. En la siguiente tabla se resume esta evaluación:

Formato del body del mensaje entrante Formato del body del patrón de filtro Acción resultante

Cadena sin formato

Cadena sin formato

Lambda filtra en función de los criterios de filtro.

Cadena sin formato

Sin patrón de filtro para las propiedades de datos

Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

Cadena sin formato

JSON válido

Lambda elimina el mensaje.

JSON válido

Cadena sin formato

Lambda elimina el mensaje.

JSON válido

Sin patrón de filtro para las propiedades de datos

Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

JSON válido

JSON válido

Lambda filtra en función de los criterios de filtro.

Si no incluye el body como parte de los FilterCriteria, Lambda omite esta verificación.

Filtrar correctamente mensajes de Kinesis y DynamoDB

Una vez que los criterios de filtro procesan un registro de Kinesis o DynamoDB, el iterador de flujos supera este registro. Si el registro no cumple los criterios de filtro, no tiene que eliminarlo manualmente del origen de eventos. Tras el periodo de retención, Kinesis y DynamoDB eliminan automáticamente estos registros antiguos. Si quiere que los registros se eliminen antes, consulte Changing the Data Retention Period (Cambiar el periodo de retención de datos).

Para filtrar correctamente los eventos de los orígenes de eventos de flujos, el formato JSON del campo de datos y de los criterios de filtro del campo de datos debe ser válido. (Para Kinesis, el campo de datos es data. Para DynamoDB, el campo de datos es dynamodb). Si el formato JSON de alguno de los campos no es válido, Lambda elimina el mensaje o genera una excepción. En la siguiente tabla se resume el comportamiento específico:

Formato de los datos entrantes (data o dynamodb) Formato del patrón de filtro para las propiedades de datos Acción resultante

JSON válido

JSON válido

Lambda filtra en función de los criterios de filtro.

JSON válido

Sin patrón de filtro para las propiedades de datos

Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

JSON válido

No JSON

Lambda genera una excepción al crear o actualizar la asignación de origen de eventos. El formato JSON del patrón de filtro de las propiedades de datos debe ser válido.

No JSON

JSON válido

Lambda elimina el registro.

No JSON

Sin patrón de filtro para las propiedades de datos

Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

No JSON

No JSON

Lambda genera una excepción al crear o actualizar la asignación de origen de eventos. El formato JSON del patrón de filtro de las propiedades de datos debe ser válido.