Filtrage des événements dans Amazon EventBridge Pipes

Avec EventBridge Pipes, vous pouvez filtrer les événements d'une source donnée et n'en traiter qu'un sous-ensemble. Ce filtrage fonctionne de la même manière que le filtrage sur un bus d' EventBridge événements ou le mappage d'une source d'événements Lambda, en utilisant des modèles d'événements. Pour plus d’informations sur les modèles d’événements, consultez Modèles d' EventBridge événements Amazon.

Un objet FilterCriteria de critères de filtre est une structure composée d’une liste de filtres (Filters). Chaque filtre est une structure qui définit un modèle de filtrage (Pattern). A Pattern est une représentation sous forme de chaîne d'une règle de JSON filtre. Un objet FilterCriteria ressemble à l'exemple suivant :

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

Pour plus de clarté, voici la valeur du filtre Pattern développé en clair JSON :

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

Les parties principales d’un objet FilterCriteria sont les propriétés de métadonnées et les propriétés de données.

• Les Propriétés des métadonnées sont les champs de l'objet événement. Dans l’exemple, FilterCriteria.Metadata1 fait référence à une propriété de métadonnées.

• Les Propriétés de données sont les champs du corps de l'événement. Dans l’exemple, FilterCriteria.Data1 fait référence à une propriété de données.

Supposons que votre flux Kinesis contienne l’événement suivant :

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

Lorsque l’événement passe par votre canal, il ressemble à ce qui suit avec le champ data codé 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"
}

Les propriétés de métadonnées de l’événement Kinesis correspondent à n’importe quel champ externe à l’objet data, tel que partitionKey ou sequenceNumber.

Les propriétés de données de l’événement Kinesis correspondent aux champs internes à l’objet data, tels que City ou Temperature.

Lorsque vous utilisez un filtre pour mettre en correspondance cet événement, vous pouvez utiliser des filtres sur les champs décodés. Par exemple, pour filtrer sur partitionKey et City, vous devez utiliser le filtre suivant :

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

Lorsque vous créez des filtres d'événements, EventBridge Pipes peut accéder au contenu des événements. Ce contenu est soit JSON échappé, comme le SQS body champ Amazon, soit codé en base64, tel que le champ Kinesis. data Si vos données sont validesJSON, vos modèles ou JSON chemins d'entrée pour les paramètres cibles peuvent référencer directement le contenu. Par exemple, si une source d'événement Kinesis est valideJSON, vous pouvez référencer une variable à l'aide de. <$.data.someKey>

Lorsque vous créez des modèles d'événements, vous pouvez filtrer en fonction des champs envoyés par la sourceAPI, et non des champs ajoutés par l'opération de sondage. Les champs suivants ne peuvent pas être utilisés dans les modèles d’événements :

• awsRegion

• eventSource

• eventSourceARN

• eventVersion

• eventID

• eventName

• invokeIdentityArn

• eventSourceKey

Champs de message et de données

Chaque source EventBridge Pipe contient un champ qui contient le message ou les données de base. Nous les appelons champs de message ou champs de données. Ces champs sont spéciaux car ils peuvent être JSON échappés ou codés en base64, mais lorsqu'ils sont valides, JSON ils peuvent être filtrés avec JSON des motifs comme si le corps n'avait pas été échappé. Le contenu de ces champs peut également être utilisé de façon transparente dans les transformateurs d’entrée.

Filtrer correctement les SQS messages Amazon

Si un SQS message Amazon ne répond pas à vos critères de filtrage, il est EventBridge automatiquement supprimé de la file d'attente. Il n'est pas nécessaire de supprimer ces messages manuellement sur AmazonSQS.

Pour AmazonSQS, le message body peut être une chaîne quelconque. Cependant, cela peut être problématique si vous vous FilterCriteria attendez body à être dans un JSON format valide. Le scénario inverse est également vrai : si le message entrant body est dans un JSON format valide, mais que vos critères de filtrage s'attendent body à être une chaîne simple, cela entraîne un comportement inattendu.

Pour éviter ce problème, assurez-vous que le format de body dans FilterCriteria correspond au format attendu de body dans les messages que vous recevez de votre file d’attente. Avant de filtrer vos messages, évalue EventBridge automatiquement le format du message entrant body et de votre modèle de filtre pourbody. S'il y a une incompatibilité, EventBridge supprime le message. Le tableau suivant résume cette évaluation :

Format du body du message entrant	Format du body du modèle de filtre	Action obtenue.
Chaîne de texte brut	Chaîne de texte brut	EventBridge filtres en fonction de vos critères de filtrage.
Chaîne de texte brut	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Chaîne de texte brut	Valide JSON	EventBridge laisse tomber le message.
Valide JSON	Chaîne de texte brut	EventBridge laisse tomber le message.
Valide JSON	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Valide JSON	Valide JSON	EventBridge filtres en fonction de vos critères de filtrage.

Si vous ne l'incluez body pas dans votreFilterCriteria, EventBridge ignore cette vérification.

Filtrage correct des messages Kinesis et DynamoDB

Une fois que vos critères de filtre traitent un enregistrement Kinesis ou DynamoDB, l’itérateur des flux passe au-delà de cet enregistrement. Si l’enregistrement ne répond pas à vos critères de filtre, vous n’avez pas besoin de supprimer manuellement l’enregistrement de la source de votre événement. Après la période de conservation, Kinesis et DynamoDB suppriment automatiquement ces anciens enregistrements. Si vous souhaitez que les enregistrements soient supprimés plus tôt, consultez Modification de la période de conservation des données.

Pour filtrer correctement les événements provenant des sources d'événements de flux, le champ de données et vos critères de filtre pour le champ de données doivent être au JSON format valide. (Pour Kinesis, le champ de données est data. Pour DynamoDB, le champ de données estdynamodb.) Si le JSON format de l'un des champs n'est pas valide, EventBridge supprime le message ou génère une exception. Le tableau suivant résume le comportement spécifique :

Format des données entrantes (data ou dynamodb)	Pas de modèle de filtre pour les propriétés des données	Action obtenue.
Valide JSON	Valide JSON	EventBridge filtres en fonction de vos critères de filtrage.
Valide JSON	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Valide JSON	Non JSON	EventBridge lance une exception au moment du canal ou de la mise à jour. Le modèle de filtre pour les propriétés des données doit être dans un JSON format valide.
Non JSON	Valide JSON	EventBridge fait tomber le record.
Non JSON	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Non JSON	Non JSON	EventBridge lance une exception au moment de la création ou de la mise à jour du canal. Le modèle de filtre pour les propriétés des données doit être dans un JSON format valide.

Filtrage approprié des messages Amazon Managed Streaming for Apache Kafka, Apache Kafka autogéré et Amazon MQ

Pour les sources Amazon MQ, le champ de message est data. Pour les sources Apache Kafka (Amazon MSK et Apache Kafka autogéré), il existe deux champs de message : key et. value

EventBridge supprime les messages qui ne correspondent pas à tous les champs inclus dans le filtre. Pour Apache Kafka, EventBridge valide les décalages pour les messages correspondants et non correspondants après avoir invoqué la fonction avec succès. Pour Amazon MQ, EventBridge accuse réception des messages correspondants après avoir correctement invoqué la fonction et accuse réception des messages non correspondants lors du filtrage de ceux-ci.

Les messages Apache Kafka et Amazon MQ doivent UTF être des chaînes codées en -8, soit des chaînes simples, soit au format. JSON En effet, il EventBridge décode les tableaux d'octets d'Apache Kafka et d'Amazon MQ UTF en -8 avant d'appliquer les critères de filtrage. Si vos messages utilisent un autre encodage, tel que UTF -16 ouASCII, ou si le format du message ne correspond pas au FilterCriteria format, EventBridge traite uniquement les filtres de métadonnées. Le tableau suivant résume le comportement spécifique :

Format du message entrant (data ou key et value)	Modèle de filtre de format pour les propriétés des messages	Action obtenue.
Chaîne de texte brut	Chaîne de texte brut	EventBridge filtres en fonction de vos critères de filtrage.
Chaîne de texte brut	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Chaîne de texte brut	Valide JSON	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Valide JSON	Chaîne de texte brut	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Valide JSON	Pas de modèle de filtre pour les propriétés des données	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.
Valide JSON	Valide JSON	EventBridge filtres en fonction de vos critères de filtrage.
Chaîne non codée en UTF -8	JSON, chaîne simple ou sans motif	EventBridge filtres (sur les autres propriétés de métadonnées uniquement) en fonction de vos critères de filtre.

Différences entre Lambda ESM et Pipes EventBridge

Lors du filtrage des événements, Lambda ESM et EventBridge Pipes fonctionnent généralement de la même manière. La principale différence est que eventSourceKey le champ n'est pas présent dans les ESM charges utiles.

Utilisation d'opérateurs de comparaison dans les filtres de tuyauterie

Les opérateurs de comparaison vous permettent de créer des modèles d'événements qui correspondent aux valeurs des champs des événements.

Pour une liste complète des opérateurs de comparaison pris en charge pour une utilisation dans les filtres de tuyauterie, voirOpérateurs de comparaison.