Filtrado de eventos de las canalizaciones de Amazon EventBridge

Con las canalizaciones de EventBridge puede filtrar los eventos de un origen determinado y procesar solo un subconjunto de ellos. Este filtrado funciona del mismo modo que el filtrado en un bus de eventos de EventBridge o en una asignación de orígenes de eventos de Lambda, mediante patrones de eventos. Para obtener más información acerca de patrones de eventos, consulte Patrones de eventos de Amazon EventBridge.

Un objeto FilterCriteria de criterios de filtro es una estructura que consta de una lista de filtros (Filters). Cada filtro es una estructura que define un patrón de filtrado (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 ]}
}

Las partes principales de un objeto FilterCriteria son las propiedades de metadatos y las propiedades de datos.

• Las propiedades de metadatos son los campos del objeto de eventos. En el ejemplo, FilterCriteria.Metadata1 hace referencia a una propiedad de metadatos.

• Las propiedades de datos son los campos del cuerpo del evento. En el ejemplo, FilterCriteria.Data1 hace referencia a una propiedad de datos.

Por ejemplo, supongamos que su flujo de Kinesis contiene un evento como este:

{
  "kinesisSchemaVersion": "1.0",
  "partitionKey": "1",
  "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
  "data": {"City": "Seattle",
    "State": "WA",
    "Temperature": "46",
    "Month": "December"
  },
  "approximateArrivalTimestamp": 1545084650.987
}

Cuando el evento fluya por la canalización, tendrá el siguiente aspecto con el campo data codificado en base64:

{
  "kinesisSchemaVersion": "1.0",
  "partitionKey": "1",
  "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
  "data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
  "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"
}

Las propiedades de metadatos del evento de Kinesis son cualquier campo fuera del objeto data, como partitionKey o sequenceNumber.

Las propiedades de datos del evento de Kinesis son cualquier campo dentro del objeto data, como City o Temperature.

Al filtrar para obtener coincidencias con este evento, puede usar filtros en los campos decodificados. Por ejemplo, para filtrar en partitionKey y City, usaría el siguiente filtro:

{
  "partitionKey": [
    "1"
  ],
  "data": {
    "City": [
      "Seattle"
    ]
  }
}

Al crear filtros de eventos, las canalizaciones de EventBridge pueden acceder al contenido del evento. Este contenido tiene un objeto JSON oculto, como el campo body de Amazon SQS, o codificado en base64, como el campo data de Kinesis. Si los datos son un objeto JSON válido, las plantillas de entrada o las rutas JSON de los parámetros de destino pueden hacer referencia al contenido directamente. Por ejemplo, si un origen de eventos de Kinesis es un objeto JSON válido, puede hacer referencia a una variable mediante <$.data.someKey>.

Al crear patrones de eventos, puede filtrar en función de los campos enviados por la API de origen y no de los campos agregados por la operación de sondeo. Los siguientes campos no se pueden usar en los patrones de eventos:

• awsRegion

• eventSource

• eventSourceARN

• eventVersion

• eventID

• eventName

• invokeIdentityArn

• eventSourceKey

Campos de mensaje y datos

Cada origen de canalizaciones de EventBridge contiene un campo que contiene el mensaje o los datos principales. Los denominamos campos mensaje o campos datos. Estos campos son especiales porque su contenido puede tener un objeto JSON oculto o estar codificado en base64, pero cuando son objetos JSON válidos, se pueden filtrar con patrones JSON como si el cuerpo no estuviera oculto. El contenido de estos campos también se puede utilizar sin problemas en los transformadores de entrada.

Filtrado correcto de mensajes de Amazon SQS

Si un mensaje de Amazon SQS no cumple los criterios de filtro, EventBridge 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 problemático: si el body del mensaje entrante está en un formato JSON válido 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 body de los FilterCriteria coincida con el formato esperado del body de los mensajes que recibe de la cola. Antes de filtrar los mensajes, EventBridge evalúa automáticamente el formato del body del mensaje entrante y del patrón de filtro del body. Si no coincide, EventBridge descarta 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	EventBridge filtra en función de los criterios de filtro.
Cadena sin formato	Sin patrón de filtro para las propiedades de datos	EventBridge filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
Cadena sin formato	JSON válido	EventBridge descarta el mensaje.
JSON válido	Cadena sin formato	EventBridge descarta el mensaje.
JSON válido	Sin patrón de filtro para las propiedades de datos	EventBridge filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
JSON válido	JSON válido	EventBridge filtra en función de los criterios de filtro.

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

Filtrado correcto de 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, EventBridge 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	EventBridge filtra en función de los criterios de filtro.
JSON válido	Sin patrón de filtro para las propiedades de datos	EventBridge filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
JSON válido	No JSON	EventBridge genera una excepción al crear o actualizar la canalización. El formato JSON del patrón de filtro de las propiedades de datos debe ser válido.
No JSON	JSON válido	EventBridge descarta el registro.
No JSON	Sin patrón de filtro para las propiedades de datos	EventBridge filtra (solo en las demás propiedades de metadatos) en función de los criterios de filtro.
No JSON	No JSON	EventBridge genera una excepción al crear o actualizar la canalización. El formato JSON del patrón de filtro de las propiedades de datos debe ser válido.

Filtrado correcto de mensajes de Amazon Managed Streaming para Apache Kafka, Apache Kafka autoadministrado y Amazon MQ

En el caso de los orígenes de Amazon MQ, el campo de mensaje es data. En el caso de los orígenes de Apache Kafka (Amazon MSK y Apache Kafka autoadministrado), hay dos campos de mensaje: key y value.

EventBridge descarta los mensajes que no coincidan con todos los campos incluidos en el filtro. En Apache Kafka, EventBridge compila los desplazamientos de los mensajes coincidentes y no coincidentes después de invocar correctamente la función. En el caso de Amazon MQ, EventBridge reconoce los mensajes coincidentes después de invocar correctamente la función, y los no coincidentes al filtrarlos.

Los mensajes de Apache Kafka y Amazon MQ deben ser cadenas codificadas en UTF-8, cadenas simples o en formato JSON. Esto se debe a que EventBridge decodifica las matrices de bytes de Apache Kafka y 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, EventBridge solo procesa los filtros de metadatos. En la siguiente tabla se resume el comportamiento específico:

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

Diferencias entre Lambda ESM y canalizaciones de EventBridge

Al filtrar eventos, Lambda ESM y las canalizaciones de EventBridge funcionan generalmente de la misma manera. La principal diferencia es que el campo eventSourceKey no está presente en las cargas de ESM.

Uso de operadores de comparación en filtros de canalizaciones

Los operadores de comparación permiten crear patrones de eventos que coincidan con los valores de campo de los eventos.

Para obtener una lista completa de los operadores de comparación compatibles con el uso en filtros de canalizaciones, consulte Operadores de comparación.