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 Filtrado con DynamoDB Filtrado con Kinesis Filtrado con Amazon MQ Filtrado con Amazon MSK y Apache Kafka autoadministrado Filtrado con Amazon SQS

Filtrado de eventos de Lambda

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 funciona con 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)

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 devuelve 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
Filtrado con DynamoDB
Filtrado con Kinesis
Filtrado con Amazon MQ
Filtrado con Amazon MSK y Apache Kafka autoadministrado
Filtrado con Amazon SQS

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 se gestionan los registros que no cumplen con el filtro 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 o DynamoDB, una vez que los criterios de filtro procesan 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 Apache Kafka autoadministrado, Lambda compila los desplazamientos de los mensajes coincidentes y no coincidentes después de invocar correctamente la función. En el caso de Amazon MQ, Lambda reconoce los mensajes coincidentes después de invocar correctamente la función, y los 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 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
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 hijo de la fuente 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 seguir seleccionando Agregar para agregar más filtros hasta el número máximo permitido.
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 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.

Filtrado con DynamoDB

Supongamos que tiene una tabla de DynamoDB con la clave principal CustomerName y los atributos AccountManager y PaymentTerms. El siguiente es un registro de ejemplo de flujo de la tabla de DynamoDB.


{
      "eventID": "1",
      "eventVersion": "1.0",
      "dynamodb": {
          "ApproximateCreationDateTime": "1678831218.0",
          "Keys": {
              "CustomerName": {
                  "S": "AnyCompany Industries"
              },
              "NewImage": {
                  "AccountManager": {
                      "S": "Pat Candella"
                  },
                  "PaymentTerms": {
                      "S": "60 days"
                  },
                  "CustomerName": {
                      "S": "AnyCompany Industries"
                  }
              },
              "SequenceNumber": "111",
              "SizeBytes": 26,
              "StreamViewType": "NEW_IMAGE"
          }
      }
  }

Para filtrar en función de los valores de clave y atributos en la tabla de DynamoDB, utilice la clave dynamodb del registro. En las siguientes secciones, se muestran ejemplos de diferentes tipos de filtros.

Filtrar con claves de tabla

Supongamos que desea que su función procese únicamente los registros en los que la clave principal CustomerName sea “AnyCompany Industries”. El objeto FilterCriteria sería el siguiente.


{
     "Filters": [
          {
              "Pattern": "{ \"dynamodb\" : { \"Keys\" : { \"CustomerName\" : { \"S\" : [ \"AnyCompany Industries\" ] } } } }"
          }
      ]
 }

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


{
     "dynamodb": {
          "Keys": {
              "CustomerName": {
                  "S": [ "AnyCompany Industries" ]
                  }
              }
          }
 }

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Filtrar con atributos de tabla

Con DynamoDB, también puede utilizar las claves NewImage y OldImage para filtrar por los valores de los atributos. Supongamos que desea filtrar los registros en los que el atributo AccountManager de la última imagen de la tabla sea “Pat Candella” o “Shirley Rodriguez”. El objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\" : { \"NewImage\" : { \"AccountManager\" : { \"S\" : [ \"Pat Candella\", \"Shirley Rodriguez\" ] } } } }"
        }
    ]
}

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


{
    "dynamodb": {
        "NewImage": {
            "AccountManager": {
                "S": [ "Pat Candella", "Shirley Rodriguez" ]
            }
        }
    }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Filtrar con expresiones booleanas

También puede crear filtros mediante expresiones booleanas AND. Estas expresiones pueden incluir tanto los parámetros de clave como los de atributo de la tabla. Supongamos que desea filtrar los registros en los que el valor NewImage de AccountManager es “Pat Candella” y el valor OldImage es “Terry Whitlock”. El objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\" : { \"NewImage\" : { \"AccountManager\" : { \"S\" : [ \"Pat Candella\" ] } } } , \"dynamodb\" : { \"OldImage\" : { \"AccountManager\" : { \"S\" : [ \"Terry Whitlock\" ] } } } }"
        }
    ]
}

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


{ 
    "dynamodb" : { 
        "NewImage" : { 
            "AccountManager" : { 
                "S" : [ 
                    "Pat Candella" 
                ] 
            } 
        } 
    }, 
    "dynamodb": { 
        "OldImage": { 
            "AccountManager": { 
                "S": [ 
                    "Terry Whitlock" 
                ] 
            } 
        } 
    } 
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

nota

El filtrado de eventos de DynamoDB no es compatible con el uso de operadores numéricos (equivalentes numéricos e intervalo numérico). Incluso si los elementos de la tabla se almacenan como números, estos parámetros se convierten en cadenas en el objeto de registro JSON.

Uso del operador Exists con DynamoDB

Debido a la forma en que están estructurados los objetos de eventos JSON de DynamoDB, el uso del operador Exists requiere un cuidado especial. El operador Exists solo funciona en los nodos hijo en el evento JSON, por lo que si el patrón de filtro usa Exists para probar la presencia de un nodo intermedio, no funcionará. Considere el siguiente elemento de la tabla de DynamoDB:


{
  "UserID": {"S": "12345"},
  "Name": {"S": "John Doe"},
  "Organizations": {"L": [
      {"S":"Sales"},
      {"S":"Marketing"},
      {"S":"Support"}
    ]
  }
}

Es posible que deba crear un patrón de filtro como el siguiente para comprobar si hay eventos que contengan "Organizations":


{ "dynamodb" : { "NewImage" : { "Organizations" : [ { "exists": true } ] } } }

Sin embargo, este patrón de filtro nunca devolvería una coincidencia porque "Organizations" no es un nodo hijo. El siguiente ejemplo muestra cómo utilizar correctamente el operador Exists para crear el patrón de filtro deseado:


{ "dynamodb" : { "NewImage" : {"Organizations": {"L": {"S": [ {"exists": true } ] } } } } }

Formato JSON para filtrado de DynamoDB

Para filtrar correctamente los eventos de orígenes de DynamoDB, tanto el campo de datos como los criterios de filtro del campo de datos (dynamodb) deben estar en un formato JSON válido. 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	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.

Filtrado con Kinesis

Supongamos que un productor incluye datos con formato JSON en su flujo de datos de Kinesis. Un registro de ejemplo tendría el siguiente aspecto, con los datos JSON convertidos en una cadena codificada en Base64 en el campo data.


{
    "kinesis": {
        "kinesisSchemaVersion": "1.0",
        "partitionKey": "1",
        "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
        "data": "eyJSZWNvcmROdW1iZXIiOiAiMDAwMSIsICJUaW1lU3RhbXAiOiAieXl5eS1tbS1kZFRoaDptbTpzcyIsICJSZXF1ZXN0Q29kZSI6ICJBQUFBIn0=",
        "approximateArrivalTimestamp": 1545084650.987
        },
    "eventSource": "aws:kinesis",
    "eventVersion": "1.0",
    "eventID": "shardId-000000000006:49590338271490256608559692538361571095921575989136588898",
    "eventName": "aws:kinesis:record",
    "invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
    "awsRegion": "us-east-2",
    "eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
}

Siempre que los datos que el productor incluya en el flujo sean JSON válidos, puede usar el filtrado de eventos para filtrar registros mediante la clave data. Supongamos que un productor incluye registros en su flujo de Kinesis en el siguiente formato JSON.


{
    "record": 12345,
    "order": {
        "type": "buy",
        "stock": "ANYCO",
        "quantity": 1000
        }
}

Para filtrar solo los registros en los que el tipo de pedido sea “comprar”, el objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : { \"order\" : { \"type\" : [ \"buy\" ] } } }"
        }
    ]
}

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


{
    "data": {
        "order": {
            "type": [ "buy" ]
            }
      }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Para filtrar correctamente los eventos de orígenes de Kinesis, tanto el campo de datos como los criterios de filtro del campo de datos deben estar en un formato JSON válido. 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	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.

Filtrado de registros agregados de Kinesis

Con Kinesis, puede agregar varios registros en un solo registro de Kinesis Data Streams para aumentar el rendimiento de sus datos. Lambda solo puede aplicar criterios de filtro a los registros agregados cuando se utiliza la distribución mejorada de Kinesis. El filtrado de registros agregados con Kinesis estándar no es compatible. Al utilizar la distribución mejorada, usted configura un consumidor de rendimiento dedicado de Kinesis para que actúe como desencadenador de la función de Lambda. A continuación, Lambda filtra los registros agregados y solo pasa los registros que cumplen los criterios de filtro.

Para obtener más información sobre la agregación de registros de Kinesis, consulte la sección Agregación de la página de conceptos clave de la Kinesis Producer Library (KPL). Para obtener más información sobre el uso de Lambda con la expansión mejorada de Kinesis, consulte Aumento del rendimiento del procesamiento de transmisiones en tiempo real con la distribución mejorada de Amazon Kinesis Data Streams y AWS Lambda en el blog de informática de AWS.

Filtrado con Amazon MQ

Supongamos que su cola de mensajes de Amazon MQ contiene mensajes en formato JSON válido o como cadenas simples. Un registro de ejemplo tendría el siguiente aspecto, con los datos convertidos en una cadena codificada en Base64 en el campo data.

Tanto para los agentes de Active MQ como los de Rabbit MQ, puede utilizar el filtrado de eventos para filtrar los registros mediante la clave data. Supongamos que su cola de Amazon MQ contiene mensajes en el siguiente formato JSON.


{
    "timeout": 0,
    "IPAddress": "203.0.113.254"
}

Para filtrar solo los registros en los que el campo timeout sea mayor que 0, el objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0] } } ] } }"
        }
    ]
}

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


{
    "data": {
        "timeout": [ { "numeric": [ ">", 0 ] } ]
        }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Con Amazon MQ, también puede filtrar los registros en los que el mensaje sea una cadena simple. Supongamos que desea procesar solo los registros en los que el mensaje comienza por “Resultado:”. El objeto FilterCriteria tendría el siguiente aspecto.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : [ { \"prefix\": \"Result: \" } ] }"
        }
    ]
}

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


{
    "data": [
        {
        "prefix": "Result: "
        }
    ]
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Los mensajes de Amazon MQ deben ser cadenas codificadas en UTF-8, cadenas simples o en formato JSON. Esto se debe a que Lambda decodifica las matrices de bytes de Amazon MQ en UTF-8 antes de aplicar los criterios de filtro. Si los mensajes utilizan otra codificación, como UTF-16 o ASCII, o el formato del mensaje no coincide con el formato de FilterCriteria, Lambda solo procesa los filtros de metadatos. En la siguiente tabla se resume el comportamiento específico:

Formato del mensaje entrante	Formato del patrón de filtro para las propiedades del mensaje	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 filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
JSON válido	Cadena sin formato	Lambda filtra (solo en las demás propiedades de metadatos) 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	JSON válido	Lambda filtra en función de los criterios de filtro.
Cadena no codificada con UTF-8	JSON, cadena sin formato o sin patrón	Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

Filtrado con Amazon MSK y Apache Kafka autoadministrado

Supongamos que un productor escribe mensajes a un tema de su clúster de Amazon MSK o Apache Kafka autoadministrado, ya sea en formato JSON válido o como cadenas simples. Un registro de ejemplo tendría el siguiente aspecto, con el mensaje convertido en una cadena codificada en Base64 en el campo value.


{
    "mytopic-0":[
        {
            "topic":"mytopic",
            "partition":0,
            "offset":15,
            "timestamp":1545084650987,
            "timestampType":"CREATE_TIME",
            "value":"SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
            "headers":[]
        }
    ]
}

Supongamos que su productor de Apache Kafka escribe mensajes a su tema en el siguiente formato JSON.


{
    "device_ID": "AB1234",
    "session":{
        "start_time": "yyyy-mm-ddThh:mm:ss",
        "duration": 162
    }
}

Puede utilizar la clave value para filtrar registros. Supongamos que desea filtrar solo los registros en los que device_ID comience con las letras AB. El objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"value\" : { \"device_ID\" : [ { \"prefix\": \"AB\" } ] } }"
        }
    ]
}

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


{
    "value": {
        "device_ID": [ { "prefix": "AB" } ]
      }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Con Amazon MSK y Apache Kafka autoadministrado, también puede filtrar registros en los que el mensaje sea una cadena simple. Supongamos que desea ignorar los mensajes en los que la cadena es “error”. El objeto FilterCriteria tendría el siguiente aspecto.


{
    "Filters": [
        {
            "Pattern": "{ \"value\" : [ { \"anything-but\": [ \"error\" ] } ] }"
        }
    ]
}

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


{
    "value": [
        {
        "anything-but": [ "error" ]
        }
    ]
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Los mensajes de Amazon MSK y Apache Kafka autoadministrado deben ser cadenas codificadas en UTF-8, cadenas simples o en formato JSON. Esto se debe a que Lambda decodifica las matrices de bytes de Amazon MSK en UTF-8 antes de aplicar los criterios de filtro. Si los mensajes utilizan otra codificación, como UTF-16 o ASCII, o el formato del mensaje no coincide con el formato de FilterCriteria, Lambda solo procesa los filtros de metadatos. En la siguiente tabla se resume el comportamiento específico:

Formato del mensaje entrante	Formato del patrón de filtro para las propiedades del mensaje	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 filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
JSON válido	Cadena sin formato	Lambda filtra (solo en las demás propiedades de metadatos) 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	JSON válido	Lambda filtra en función de los criterios de filtro.
Cadena no codificada con UTF-8	JSON, cadena sin formato o sin patrón	Lambda filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.

Filtrado con Amazon SQS

Supongamos que su cola de Amazon SQS contiene mensajes en el siguiente formato JSON.


{
    "RecordNumber": 0000,
    "TimeStamp": "yyyy-mm-ddThh:mm:ss",
    "RequestCode": "AAAA"
}

Un registro de ejemplo para esta cola tendría el siguiente aspecto.


{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "RecordNumber": 0000,\n "TimeStamp": "yyyy-mm-ddThh:mm:ss",\n "RequestCode": "AAAA"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
        },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-west-2:123456789012:my-queue",
    "awsRegion": "us-west-2"
}

Para filtrar en función del contenido de los mensajes de Amazon SQS, utilice la clave body del registro de mensajes de Amazon SQS. Supongamos que desea procesar solo los registros en los que el RequestCode del mensaje de Amazon SQS sea “BBBB”. El objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"body\" : { \"RequestCode\" : [ \"BBBB\" ] } }"
        }
    ]
}

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


{
    "body": {
        "RequestCode": [ "BBBB" ]
        }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Supongamos que desea que su función procese solo los registros en los que RecordNumber sea un valor superior a 9999. El objeto FilterCriteria sería el siguiente.


{
    "Filters": [
        {
            "Pattern": "{ \"body\" : { \"RecordNumber\" : [ { \"numeric\": [ \">\", 9999 ] } ] } }"
        }
    ]
}

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


{
    "body": {
        "RecordNumber": [
            {
                "numeric": [ ">", 9999 ]
            }
        ]
    }
}

Puede agregar el filtro mediante la consola, la AWS CLI o una plantilla de AWS SAM.

Para Amazon SQS, el cuerpo del mensaje puede ser cualquier cadena. No obstante, esto puede ser problemático si los FilterCriteria esperan que el formato JSON del body sea válido. La situación inversa también es problemática: si el cuerpo del mensaje entrante está en formato JSON, pero los criterios de filtro esperan que el body sea una cadena sin formato, puede producirse un comportamiento no deseado.

Para evitar este problema, asegúrese de que el formato del cuerpo 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 cuerpo 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.

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

Tutorial

Pruebas en la consola