Filtrage du contenu dans les modèles EventBridge d'événements Amazon

Amazon EventBridge prend en charge le filtrage déclaratif du contenu à l'aide de modèles d'événements. Grâce au filtrage de contenu, vous pouvez écrire des modèles d’événements complexes qui ne correspondent à des événements que sous des conditions très spécifiques. Par exemple, vous pouvez créer un modèle d’événement correspondant à un événement lorsque :

• Un champ de l’événement se situe dans une plage numérique spécifique.

• L’événement provient d’une adresse IP spécifique.

• Un champ spécifique n’existe pas dans le code JSON de l’événement.

Important

Dans EventBridge, il est possible de créer des règles pouvant entraîner des higher-than-expected frais et des ralentissements. Par exemple, vous pouvez créer par inadvertance une règle qui entraîne une boucle infinie, dans laquelle une règle est déclenchée de manière récursive sans fin. Supposons que vous avez créé une règle permettant de détecter que les listes ACL ont été modifiées sur un compartiment Amazon S3 et de déclencher un logiciel pour les modifier afin qu’elles aient l’état souhaité. Si la règle n'est pas correctement écrite, la modification suivante des listes de contrôle d'accès (ACL) déclenche à nouveau la règle, créant ainsi une boucle infinie.

Pour obtenir des conseils sur la façon d’écrire des règles et des modèles d’événements précis afin de réduire au maximum ces résultats inattendus, consultez Bonnes pratiques lors de la définition de règles Amazon EventBridge et Bonnes pratiques lors de la définition des modèles EventBridge d'événements Amazon.

Correspondance de préfixe

Vous pouvez mettre en correspondance un événement en fonction du préfixe d’une valeur dans la source de l’événement. Vous pouvez utiliser la correspondance de préfixes pour les valeurs de chaîne.

Par exemple, le modèle d’événement suivant correspond à tout événement où le champ "time" commence par "2017-10-02", tel que "time": "2017-10-02T18:43:48Z".

{
  "time": [ { "prefix": "2017-10-02" } ]
}

Correspondance des préfixes sans tenir compte des majuscules

Vous pouvez également faire correspondre une valeur de préfixe quelle que soit la majuscule des caractères par lesquels une valeur commence, equals-ignore-case en conjonction avec prefix.

Par exemple, le modèle d'événement suivant correspond à tout événement où le service champ commence par la chaîne de caractèresEventB, mais également EVENTBeventb, ou à toute autre majuscule de ces caractères.

{
  "detail": {"service" : [{ "prefix": { "equals-ignore-case": "EventB" }}]}
}

Correspondance de suffixes

Vous pouvez mettre en correspondance un événement en fonction du suffixe d’une valeur dans la source de l’événement. Vous pouvez utiliser la correspondance de suffixes pour les valeurs de chaîne.

Par exemple, le modèle d’événement suivant correspond à tout événement où le champ "FileName" se termine par l’extension de fichier .png.

{
  "FileName": [ { "suffix": ".png" } ]
}

Suffixe correspondant tout en ignorant les majuscules

Vous pouvez également faire correspondre la valeur d'un suffixe quelle que soit la majuscule des caractères par lesquels une valeur se termine, equals-ignore-case en utilisant conjointement avec suffix.

Par exemple, le modèle d'événement suivant correspondrait à tout événement où le FileName champ se terminait par la chaîne de caractères.png, mais également à .PNG toute autre mise en majuscules de ces caractères.

{
  "detail": {"FileName" : [{ "suffix": { "equals-ignore-case": ".png" }}]}
}

Correspondance de type « anything-but » (tout-sauf)

Tout sauf la correspondance correspond à tout sauf à ce qui est spécifié dans la règle.

Vous pouvez utiliser la correspondance anything-but avec des chaînes et des valeurs numériques, y compris des listes contenant uniquement des chaînes ou des nombres.

Le modèle d’événement suivant montre la correspondance anything-but avec des chaînes et des nombres.

{
  "detail": {
    "state": [ { "anything-but": "initializing" } ]
  }
}

{
  "detail": {
    "x-limit": [ { "anything-but": 123 } ]
  }
}

Le modèle d’événement suivant montre la correspondance anything-but avec une liste de chaînes.

{
  "detail": {
    "state": [ { "anything-but": [ "stopped", "overloaded" ] } ]
  }
}

Le modèle d’événement suivant montre la correspondance anything-but avec une liste de nombres.

{
  "detail": {
    "x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
  }
}

Tout sauf correspondre tout en ignorant le cas

Vous pouvez également l'utiliser equals-ignore-case en conjonction avecanything-but, pour faire correspondre les valeurs des chaînes indépendamment de la structure des caractères.

Le modèle d'événement suivant correspond aux state champs qui ne contiennent pas la chaîne « initialization », « INITIALIZING », « Initializing » ou toute autre majuscule de ces caractères.

{
  "detail": {"state" : [{ "anything-but": { "equals-ignore-case": "initializing" }}]}
}

Vous pouvez également utiliser equals-ignore-case en conjonction avec anything-but pour comparer à une liste de valeurs :

{
  "detail": {"state" : [{ "anything-but": { "equals-ignore-case": ["initializing", "stopped"] }}]}
}

Tout sauf la correspondance sur les préfixes

Vous pouvez l'utiliser prefix conjointement avec anything-but pour faire correspondre des valeurs de chaîne qui ne commencent pas par la valeur spécifiée. Cela inclut des valeurs uniques ou une liste de valeurs.

Le modèle d'événement suivant montre tout sauf une correspondance qui correspond à tout événement dont le champ ne contient pas le préfixe"init". "state"

{
  "detail": {
    "state": [ { "anything-but": { "prefix": "init" } } ]
  }
}

Le modèle d'événement suivant montre tout sauf la correspondance utilisée avec une liste de valeurs de préfixes. Ce modèle d'événement correspond à tout événement qui ne possède ni le préfixe "init" ni "stop" le "state" champ.

{
"detail": {
  "state" : [{ "anything-but": { "prefix": ["init", "stop"] } } ] }
  }
}

Tout sauf la correspondance sur les suffixes

Vous pouvez l'utiliser suffix conjointement avec anything-but pour faire correspondre des valeurs de chaîne qui ne se terminent pas par la valeur spécifiée. Cela inclut des valeurs uniques ou une liste de valeurs.

Le modèle d'événement suivant correspond à toutes les valeurs du FileName champ qui ne se terminent pas par.txt.

{
  "detail": {
    "FileName": [ { "anything-but": { "suffix": ".txt" } } ]
  }
}

Le modèle d'événement suivant montre tout sauf la correspondance utilisée avec une liste de valeurs de suffixe. Ce modèle d'événement correspond à toutes les valeurs du FileName champ qui ne se terminent pas par .txt ou.rtf.

{
  "detail": {
    "FileName": [ { "anything-but": { "suffix": [".txt", ".rtf"] } } ]
  }
}

Tout sauf la correspondance à l'aide de caractères génériques

Vous pouvez utiliser le caractère générique (*) dans les valeurs que vous spécifiez pour tout sauf pour la correspondance. Cela inclut des valeurs uniques ou une liste de valeurs.

Le modèle d'événement suivant correspond à toutes les valeurs du FileName champ qui ne contiennent pas/lib/.

{
"detail": {
  "FilePath" : [{ "anything-but": { "wildcard": "*/lib/*" }}]
  }
}

Le modèle d'événement suivant montre tout sauf la correspondance utilisée avec une liste de valeurs, y compris des caractères génériques. Ce modèle d'événement correspond à toutes les valeurs du FileName champ qui ne contiennent aucun /lib/ ou/bin/.

{
"detail": {
  "FilePath" : [{ "anything-but": { "wildcard": ["*/lib/*", "*/bin/*"] }}]
  }
}

Pour plus d’informations, consultez Correspondance à l’aide de caractères génériques.

Correspondance numérique

La correspondance numérique fonctionne avec des valeurs qui sont des nombres JSON. Elle est limitée aux valeurs comprises entre -5.0e9 et +5.0e9 inclus, avec une précision à 15 chiffres (six chiffres à droite de la virgule décimale).

L’exemple suivant illustre la correspondance numérique pour un modèle d’événement qui ne correspond qu’aux événements dont tous les champs sont vrais.

{
  "detail": {
    "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
    "d-count": [ { "numeric": [ "<", 10 ] } ],
    "x-limit": [ { "numeric": [ "=", 3.018e2 ] } ]
  }
}

Correspondance d'adresses IP

Vous pouvez utiliser la correspondance d’adresses IP pour les adresses IPv4 et IPv6. Le modèle d’événement suivant illustre la correspondance d’adresses IP à des adresses IP qui commencent par 10.0.0 et se terminent par un nombre compris entre 0 et 255.

{
  "detail": {
    "sourceIPAddress": [ { "cidr": "10.0.0.0/24" } ]
  }
}

Correspondance exists

La correspondance exists fonctionne sur la présence ou l’absence d’un champ dans le code JSON de l’événement.

La correspondance de type « exists » ne fonctionne que sur des nœuds terminaux. Elle ne fonctionne pas sur des nœuds intermédiaires.

Le modèle d’événement suivant correspond à n’importe quel événement comportant un champ detail.state.

{
  "detail": {
    "state": [ { "exists": true  } ]
  }
}

Le modèle d’événement précédent correspond à l’événement suivant.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2015-11-11T21:29:54Z",
  "region": "us-east-1",
  "resources": ["arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"],
  "detail": {
    "instance-id": "i-abcd1111",
    "state": "pending"
  }
}

Le modèle d’événement précédent ne correspond PAS à l’événement suivant, car il ne comporte aucun champ detail.state.

{
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
  "detail": {
    "c-count" : {
       "c1" : 100
    }
  }
}

quals-ignore-caseCorrespondance E

La quals-ignore-case correspondance E fonctionne sur les valeurs de chaîne, quel que soit le cas.

Le modèle d’événement suivant correspond à n’importe quel événement comportant un champ detail-type qui correspond à la chaîne spécifiée, quelle que soit sa casse.

{
  "detail-type": [ { "equals-ignore-case": "ec2 instance state-change notification" } ]
}

Le modèle d’événement précédent correspond à l’événement suivant.

{
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
  "detail": {
    "c-count" : {
       "c1" : 100
    }
  }
}

Correspondance à l’aide de caractères génériques

Vous pouvez utiliser le caractère générique (*) pour mettre en correspondance des valeurs de chaîne dans les modèles d’événements.

Note

Actuellement, le caractère générique n’est pris en charge que dans les règles de bus d’événements.

Considérations relatives à l’utilisation de caractères génériques dans vos modèles d’événements :

• Vous pouvez spécifier n’importe quel nombre de caractères génériques dans une valeur de chaîne donnée ; toutefois, les caractères génériques consécutifs ne sont pas pris en charge.

• EventBridge prend en charge l'utilisation de la barre oblique inverse (\) pour spécifier les caractères littéraux * et \ dans les filtres génériques :

  • La chaîne \* représente le caractère littéral *

  • La chaîne \\ représente le caractère littéral \

  L’utilisation de la barre oblique inversée pour mettre en échappement d’autres caractères n’est pas prise en charge.

Complexité des caractères génériques et des modèles d’événements

La complexité d’une règle utilisant des caractères génériques est limitée. Si une règle est trop complexe, EventBridge renvoie un InvalidEventPatternException lorsque vous essayez de créer la règle. Si votre règle génère une telle erreur, envisagez de suivre les conseils ci-dessous pour réduire la complexité du modèle d’événement :

• Réduisez le nombre de caractères génériques utilisés

  N’utilisez des caractères génériques que lorsque vous devez véritablement comparer plusieurs valeurs possibles. Prenons l’exemple de modèle d’événement suivant, où vous souhaitez comparer des bus d’événements dans la même région :

  {
  "EventBusArn": [ { "wildcard": "*:*:*:*:*:event-bus/*" } ]
  }

  Dans le cas ci-dessus, de nombreuses sections de l’ARN seront directement basées sur la région dans laquelle résident vos bus d’événements. Ainsi, si vous utilisez la région us-east-1, voici exemple de modèle moins complexe qui correspond toujours aux valeurs souhaitées :

  {
  "EventBusArn": [ { "wildcard": "arn:aws:events:us-east-1:*:event-bus/*" } ]
  }

• Réduisez les séquences de caractères qui se répètent, après un caractère générique

  Le fait que la même séquence de caractères apparaisse plusieurs fois après l’utilisation d’un caractère générique augmente la complexité du traitement du modèle d’événement. Recréez votre modèle d’événement afin de réduire au maximum les séquences répétées. Prenons l’exemple suivant, qui met en correspondance le nom de fichier doc.txt pour n’importe quel utilisateur :

  {
  "FileName": [ { "wildcard": "/Users/*/dir/dir/dir/dir/dir/doc.txt" } ]
  }

  Si vous saviez que le fichier doc.txt n’apparaîtrait que dans le chemin spécifié, vous pourriez réduire la séquence de caractères répétée comme suit :

  {
  "FileName": [ { "wildcard": "/Users/*/doc.txt" } ]
  }

Exemple complexe avec correspondance multiple

Vous pouvez combiner plusieurs règles de correspondance dans un modèle d'événement plus complexe. Par exemple, le modèle d’événement suivant combine anything-but et numeric.

{
  "time": [ { "prefix": "2017-10-02" } ],
  "detail": {
    "state": [ { "anything-but": "initializing" } ],
    "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
    "d-count": [ { "numeric": [ "<", 10 ] } ],
    "x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
  }
}

Note

Lorsque vous créez des modèles d’événements, si vous incluez une clé plusieurs fois, la dernière référence sera celle utilisée pour évaluer les événements. Par exemple, pour le modèle suivant :

{
  "detail": {
    "location": [ { "prefix": "us-" } ],
    "location": [ { "anything-but": "us-east" } ]
  }
}

Seul { "anything-but": "us-east" } sera pris en compte lors de l’évaluation de location.

Exemple complexe avec correspondance $or

Vous pouvez également créer des modèles d’événements complexes qui vérifient si l’une des valeurs de champs correspond, dans plusieurs champs. Utilisez $or pour créer un modèle d’événement qui correspond si l’une des valeurs de plusieurs champs correspond.

Notez que vous pouvez inclure d’autres types de filtres, tels que la correspondance numérique et les tableaux, dans votre correspondance de modèles pour les champs individuels de votre construction $or.

Le modèle d’événement suivant correspond si l’une des conditions suivantes est remplie :

• Le champ c-count est supérieur à 0 ou inférieur ou égal à 5.

• Le champ d-count est inférieur à 10.

• Le champ x-limit est égal à 3.018e2.

{
  "detail": {
    "$or": [
      { "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ] },
      { "d-count": [ { "numeric": [ "<", 10 ] } ] },
      { "x-limit": [ { "numeric": [ "=", 3.018e2 ] } ] }
    ]
  }
}

Note

Les API qui acceptent un modèle d’événement (telles que PutRule, CreateArchive, UpdateArchive et TestEventPattern) lanceront InvalidEventPatternException si l’utilisation de $or génère plus de 1 000 combinaisons de règles.

Pour déterminer le nombre de combinaisons de règles dans un modèle d’événement, multipliez le nombre total d’arguments de chaque tableau $or dans le modèle d’événement. Par exemple, le modèle ci-dessus contient un seul tableau $or avec trois arguments, de sorte que le nombre total de combinaisons de règles est également de trois. Si vous ajoutiez un autre tableau $or avec deux arguments, le nombre total de combinaisons de règles serait alors de six.