Conceptos básicos del filtrado de eventos Gestión de registros que no cumplen con los criterios de filtro Sintaxis de la regla de filtro Adjuntar criterios de filtro a una asignación de origen de eventos (consola)Adjuntar criterios de filtro a una asignación de origen de eventos (AWS CLI)Adjuntar criterios de filtro a una asignación de origen de eventos (AWS SAM)Uso de filtros con diferentes Servicios de AWS

Controle qué eventos envía Lambda a la función

Puede utilizar el filtrado de eventos para controlar qué registros de un flujo o una cola envía Lambda a su función. Por ejemplo, puede agregar un filtro para que la función solo procese los mensajes de Amazon SQS que contengan ciertos parámetros de datos. El filtrado de eventos solo funciona con determinadas asignaciones de orígenes de eventos. Puede agregar filtros a las asignaciones de orígenes de eventos de los siguientes servicios de AWS:

Amazon DynamoDB
Amazon Kinesis Data Streams
Amazon MQ
Amazon Managed Streaming for Apache Kafka (Amazon MSK)
Apache Kafka autoadministrado
Amazon Simple Queue Service (Amazon SQS)

Para obtener información específica sobre el filtrado con orígenes de eventos específicos, consulte Uso de filtros con diferentes Servicios de AWS. Lambda no es compatible con el filtrado de eventos para Amazon DocumentDB.

De manera predeterminada, puede definir hasta cinco filtros diferentes para una única asignación de orígenes de eventos. Los filtros se unen de forma lógica. Si un registro del origen de eventos cumple con uno o más de sus filtros, Lambda incluye el registro en el siguiente evento que envíe a su función. Si no se cumple con ninguno de los filtros, Lambda descarta el registro.

nota

Si necesita definir más de cinco filtros para un origen de eventos, puede solicitar un aumento de cuota de hasta 10 filtros para cada origen de eventos. Si intenta agregar más filtros de los que permite su cuota actual, Lambda devolverá un error al intentar crear el origen de eventos.

Temas

Conceptos básicos del filtrado de eventos
Gestión de registros que no cumplen con los criterios de filtro
Sintaxis de la regla de filtro
Adjuntar criterios de filtro a una asignación de origen de eventos (consola)
Adjuntar criterios de filtro a una asignación de origen de eventos (AWS CLI)
Adjuntar criterios de filtro a una asignación de origen de eventos (AWS SAM)
Uso de filtros con diferentes Servicios de AWS

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 es una estructura que define un patrón de filtrado de eventos (Pattern). Un patrón es una representación de cadenas de una regla de filtro de JSON. La estructura de un objeto FilterCriteria es la siguiente:


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

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


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

El patrón de filtro puede incluir propiedades de metadatos, propiedades de datos o ambas. Los parámetros de metadatos disponibles y el formato de los parámetros de datos varían según el Servicio de AWS que actúe como origen del evento. Por ejemplo, supongamos que su asignación de orígenes de eventos recibe el siguiente registro de una cola de 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"
}

Las propiedades de metadatos son los campos que contienen información sobre el evento que creó el registro. En el registro de Amazon SQS de ejemplo, las propiedades de metadatos incluyen campos como messageID, eventSourceArn y awsRegion.
Las propiedades de datos son los campos del registro que contienen los datos de su flujo o cola. En el evento de Amazon SQS de ejemplo, la clave del campo de datos es body y las propiedades de datos son los campos City, State y Temperature.

Los diferentes tipos de orígenes de eventos utilizan diferentes valores de clave para sus campos de datos. Para filtrar las propiedades de datos, asegúrese de utilizar la clave correcta en el patrón del filtro. Para obtener una lista de las claves de filtrado de datos y ver ejemplos de patrones de filtro para cada uno de los Servicio de AWS compatibles, consulte Uso de filtros con diferentes Servicios de AWS.

El filtrado de eventos puede gestionar el filtrado JSON multinivel. Por ejemplo, fíjese en el siguiente fragmento de un registro de un flujo de DynamoDB:


"dynamodb": {
    "Keys": {
        "ID": {
            "S": "ABCD"
        }
        "Number": {
            "N": "1234"
    },
    ...
}

Supongamos que desea procesar solo los registros en los que el valor de la clave de clasificación Number sea 4567. En este caso, el objeto FilterCriteria sería similar al siguiente:


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
        }
    ]
}

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


{
    "dynamodb": {
        "Keys": {
            "Number": {
                "N": [ "4567" ]
                }
            }
        }
}

Gestión de registros que no cumplen con los criterios de filtro

La forma en que Lambda gestiona los registros que no cumplen con los criterios del filtrado depende del origen del evento.

En Amazon SQS, si un mensaje no cumple con los criterios de filtro, Lambda lo elimina automáticamente de la cola. No tiene que eliminar manualmente estos mensajes en Amazon SQS.
En Kinesis y DynamoDB, después de que los criterios de filtro evalúan un registro, 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).
En el caso de los mensajes de Amazon MSK, Apache Kafka autoadministrado y Amazon MQ, Lambda elimina los mensajes que no coinciden con todos los campos incluidos en el filtro. Para Amazon MSK y Apache Kafka autoadministrado, Lambda compila los desplazamientos de los mensajes coincidentes y no coincidentes después de invocar la función de forma correcta. En el caso de Amazon MQ, Lambda reconoce los mensajes coincidentes después de invocar la función de forma correcta y reconoce los mensajes no coincidentes al filtrarlos.

Sintaxis de la regla de filtro

Para las reglas de filtro, Lambda es compatible con las reglas de Amazon EventBridge y utiliza la misma sintaxis que EventBridge. Para obtener más información, consulte 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
Nulo	El valor de UserID (ID de usuario) es nulo	“UserID”: [null]
Vacío	LastName (Apellido) está vacío	“LastName”: [“”]
Igual a	El valor de Name (Nombre) es “Alice”	“Name”: [“Alice”]
Es igual a (omitir mayúsculas y minúsculas)	El valor de Name (Nombre) es “Alice”	"Name": [ { "equals-ignore-case": "alice" } ]
Y	El valor de Location (Ubicación) es “New York” y el de Day (Día) es “Monday”	“Location”: [“New York”], “Day”: [“Monday”]
Or (Disyunción)	El valor de PaymentType (Tipo de pago) es “Credit” (Crédito) o “Debit” (Débito)	“PaymentType”: [“Credit”, “Debit”]
O (varios campos)	El valor de Location (Ubicación) es “New York” o el de Day (Día) es “Monday”.	"$or": [ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ]
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]}]
Existe	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-”}]
Acaba con	FileName termina con la extensión .png.	"FileName": [ { "suffix": ".png" } ]

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.

Tenga en cuenta que el operador Exists solo funciona en los nodos hoja del origen de eventos JSON. No coincide con nodos intermedios. Por ejemplo, con el siguiente JSON, el patrón de filtro { "person": { "address": [ { "exists": true } ] } }" no encontraría ninguna coincidencia porque "address" es un nodo intermedio.


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

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)

Abra la página de Funciones en la consola de Lambda.
Elija el nombre de la función para la que se creará una asignación de origen de eventos.
En Descripción general de la función, elija Agregar desencadenador.
En Trigger configuration (Configuración del desencadenador), elija un tipo de desencadenador compatible con el filtrado de eventos. Para obtener una lista de los servicios compatibles, consulte la lista que aparece al principio de esta página.
Amplíe Configuración adicional.
En Filter criteria (Criterios de filtro), seleccione Add (Agregar), y luego defina e ingrese los filtros. Por ejemplo, puede ingresar lo siguiente.
```
{ "Metadata" : [ 1, 2 ] }
```
De este modo, Lambda solo procesa los registros en los que el campo Metadata es igual a 1 o 2. Puede volver a seleccionar Agregar para agregar más filtros hasta la cantidad máxima permitida.
Cuando haya terminado de agregar filtros, elija Guardar.

Al ingresar criterios de filtro mediante la consola, solo ingresa el patrón de filtro y no necesita ingresar la clave Pattern ni las comillas de escape. En el paso 6 de las instrucciones anteriores, { "Metadata" : [ 1, 2 ] } corresponde a los siguientes FilterCriteria.


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 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. Para obtener más ejemplos de cómo crear filtros de eventos con la consola, consulte Uso de filtros con diferentes Servicios de AWS.

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": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Para crear una nueva asignación de orígenes de eventos con estos criterios de filtro mediante la 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": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

El comando create-event-source-mapping crea una nueva asignación de orígenes 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 orígenes de eventos existente, ejecute el siguiente comando.


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 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 list-event-source-mappings. Lambda también devuelve el UUID en la respuesta de la CLI create-event-source-mapping.

Para eliminar los criterios de filtro de un origen de eventos, puede ejecutar el comando update-event-source-mapping con un objeto de FilterCriteria vacío.


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

Para obtener más ejemplos de cómo crear filtros de eventos con la AWS CLI, consulte Uso de filtros con diferentes Servicios de AWS.

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

Supongamos que desea configurar un origen de eventos en AWS SAM para utilizar los siguientes criterios de filtro:


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

Para agregar estos criterios de filtro a su asignación de orígenes de eventos, inserte el siguiente fragmento en la plantilla YAML de su origen de eventos.


FilterCriteria: 
  Filters: 
    - Pattern: '{"Metadata": [1, 2]}'

Para obtener más información sobre cómo crear y configurar una plantilla AWS SAM para una asignación de orígenes de eventos, consulte la sección EventSource de la Guía para desarrolladores de AWS SAM. Para obtener más ejemplos de cómo crear filtros de eventos con AWS SAM, consulte Uso de filtros con diferentes Servicios de AWS.

Uso de filtros con diferentes Servicios de AWS

Los diferentes tipos de orígenes de eventos utilizan diferentes valores de clave para sus campos de datos. Para filtrar las propiedades de datos, asegúrese de utilizar la clave correcta en el patrón del filtro. En la siguiente tabla se muestran las claves de filtrado para cada Servicio de AWS compatible.

Servicio de AWS	Clave de filtrado
DynamoDB	`dynamodb`
Kinesis	`data`
Amazon MQ	`data`
Amazon MSK	`value`
Apache Kafka autoadministrado	`value`
Amazon SQS	`body`

En las siguientes secciones se ofrecen ejemplos de patrones de filtro para diferentes tipos de orígenes de eventos. También proporcionan definiciones de los formatos de datos entrantes compatibles y los formatos de cuerpo de los patrones de filtro para cada servicio compatible.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Mapeos de origen de eventos

Pruebas en la consola