Filterung von Ereignissen in Amazon EventBridge Pipes

Mit EventBridge Pipes können Sie die Ereignisse einer bestimmten Quelle filtern und nur eine Teilmenge davon verarbeiten. Diese Filterung funktioniert genauso wie die Filterung auf einer EventBridge Eventbus- oder Lambda-Ereignisquellenzuordnung, indem sie Ereignismuster verwendet. Weitere Informationen zu Ereignismustern finden Sie unter EventBridge Amazon-Ereignismuster.

Ein Filterkriterienobjekt FilterCriteria ist eine Struktur, die aus einer Liste von Filtern (Filters) besteht. Jeder Filter ist eine Struktur, die ein Filtermuster (Pattern) definiert. A Pattern ist eine Zeichenkettendarstellung einer JSON Filterregel. Ein FilterCriteria-Objekt sieht z. B. folgendermaßen aus:

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

Der besseren Übersichtlichkeit halber ist hier der Wert des Filters einfach Pattern erweitertJSON:

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

Die Hauptbestandteile eines FilterCriteria-Objekts sind Metadateneigenschaften und Dateneigenschaften.

• Metadateneigenschaften sind die Felder des Ereignisobjekts. Im Beispiel bezieht sich FilterCriteria.Metadata1 auf eine Metadateneigenschaft.

• Dateneigenschaften sind die Felder des Ereignistexts. Im Beispiel bezieht sich FilterCriteria.Data1 auf eine Dateneigenschaft.

Nehmen wir zum Beispiel an, Ihr Kinesis-Stream enthält ein Ereignis wie das folgende:

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

Wenn das Ereignis durch Ihre Pipe fließt, sieht es wie folgt aus, wobei das data-Feld base64-kodiert ist:

{
  "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"
}

Bei den Metadateneigenschaften des Kinesis-Ereignisses handelt es sich um beliebige Felder außerhalb des data-Objekts, z. B. partitionKey oder sequenceNumber.

Bei den Dateneigenschaften des Kinesis-Ereignisses handelt es sich um die Felder innerhalb des data-Objekts, z. B. City oder Temperature.

Wenn Sie filtern, um dieses Ereignis abzugleichen, können Sie Filter für die dekodierten Felder verwenden. Um beispielsweise nach partitionKey und City zu filtern, würden Sie den folgenden Filter verwenden:

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

Wenn Sie Ereignisfilter erstellen, kann EventBridge Pipes auf Veranstaltungsinhalte zugreifen. Dieser Inhalt ist entweder JSON -Escape-Code, wie das SQS body Amazon-Feld, oder Base64-kodiert, wie das Kinesis-Feld. data Wenn Ihre Daten gültig sindJSON, können Ihre Eingabevorlagen oder JSON Pfade für Zielparameter direkt auf den Inhalt verweisen. Wenn beispielsweise eine Kinesis-Ereignisquelle gültig istJSON, können Sie mithilfe <$.data.someKey> von auf eine Variable verweisen.

Beim Erstellen von Ereignismustern können Sie nach den von der Quelle gesendeten Feldern filtern und nicht nach FeldernAPI, die durch den Abfragevorgang hinzugefügt wurden. Die folgenden Felder können nicht in Ereignismustern verwendet werden:

• awsRegion

• eventSource

• eventSourceARN

• eventVersion

• eventID

• eventName

• invokeIdentityArn

• eventSourceKey

Nachrichten- und Datenfelder

Jede EventBridge Pipe-Quelle enthält ein Feld, das die Kernbotschaft oder die Kerndaten enthält. Wir bezeichnen diese als Nachrichtenfelder oder Datenfelder. Diese Felder sind besonders, weil sie entweder JSON -Escape-Zeichen oder Base64-kodiert sein können. Wenn sie jedoch gültig sind, können JSON sie mit JSON Mustern gefiltert werden, als ob der Text nicht maskiert wäre. Der Inhalt dieser Felder kann auch problemlos in Eingabe-Transformatoren verwendet werden.

SQSAmazon-Nachrichten richtig filtern

Wenn eine SQS Amazon-Nachricht Ihre Filterkriterien nicht erfüllt, EventBridge wird die Nachricht automatisch aus der Warteschlange entfernt. Sie müssen diese Nachrichten in Amazon nicht manuell löschenSQS.

Für Amazon SQS body kann die Nachricht eine beliebige Zeichenfolge sein. Dies kann jedoch problematisch sein, wenn Sie FilterCriteria erwartenbody, dass es sich um ein gültiges JSON Format handelt. Das umgekehrte Szenario ist auch der Fall: Wenn die eingehende Nachricht body ein gültiges JSON Format hat, Ihre Filterkriterien aber erwarten, dass es sich body um eine einfache Zeichenfolge handelt, führt dies zu unbeabsichtigtem Verhalten.

Stellen Sie zur Vermeidung dieses Problems sicher, dass das Format von body in Ihren FilterCriteria dem erwarteten Format von body in Nachrichten entspricht, die Sie aus Ihrer Warteschlange erhalten. Vor dem Filtern Ihrer Nachrichten EventBridge werden automatisch das Format der eingehenden Nachricht body und Ihr Filtermuster für ausgewertet. body Wenn es eine Nichtübereinstimmung gibt, wird die EventBridge Nachricht gelöscht. In der folgenden Tabelle ist diese Auswertung zusammengefasst:

body-Format der eingehenden Nachricht	body-Format des Filtermusters	Resultierende Aktion
Einfache Zeichenfolge	Einfache Zeichenfolge	EventBridge filtert auf der Grundlage Ihrer Filterkriterien.
Einfache Zeichenfolge	Kein Filtermuster für Dateneigenschaften	EventBridge filtert (nur für die anderen Metadateneigenschaften) basierend auf Ihren Filterkriterien.
Einfache Zeichenfolge	Gültig JSON	EventBridge löscht die Nachricht.
Gültig JSON	Einfache Zeichenfolge	EventBridge löscht die Nachricht.
Gültig JSON	Kein Filtermuster für Dateneigenschaften	EventBridge Filter (nur für die anderen Metadateneigenschaften), die auf Ihren Filterkriterien basieren.
Gültig JSON	Gültig JSON	EventBridge Filter, die auf Ihren Filterkriterien basieren.

Wenn Sie dies nicht body als Teil Ihrer angebenFilterCriteria, EventBridge überspringt Sie diese Prüfung.

Ordnungsgemäßes Filtern von Kinesis- und DynamoDB-Nachrichten

Nachdem Ihre Filterkriterien einen Kinesis- oder DynamoDB-Datensatz verarbeitet haben, geht der Streams-Iterator über diesen Datensatz hinaus. Wenn der Datensatz Ihre Filterkriterien nicht erfüllt, müssen Sie den Datensatz nicht manuell aus Ihrer Ereignisquelle löschen. Nach Ablauf der Aufbewahrungsfrist löschen Kinesis und DynamoDB diese alten Datensätze automatisch. Wenn Sie möchten, dass Datensätze früher gelöscht werden, lesen Sie Ändern des Zeitraums der Datenaufbewahrung.

Um Ereignisse aus Stream-Ereignisquellen ordnungsgemäß zu filtern, müssen sowohl das Datenfeld als auch Ihre Filterkriterien für das Datenfeld ein gültiges Format haben. JSON (Bei Kinesis ist das Datenfeld data. Bei DynamoDB ist das Datenfeld dynamodb.) Wenn eines der Felder kein gültiges JSON Format hat, wird die EventBridge Nachricht gelöscht oder es wird eine Ausnahme ausgelöst. In der folgenden Tabelle ist das Verhalten zusammengefasst:

Format der eingehenden Daten (data oder dynamodb)	Filtermusterformat für Dateneigenschaften	Resultierende Aktion
Gültig JSON	Gültig JSON	EventBridge Filter, die auf Ihren Filterkriterien basieren.
Gültig JSON	Kein Filtermuster für Dateneigenschaften	EventBridge Filter (nur für die anderen Metadateneigenschaften), die auf Ihren Filterkriterien basieren.
Gültig JSON	Nicht- JSON	EventBridge löst zum Zeitpunkt der Pipe oder Aktualisierung eine Ausnahme aus. Das Filtermuster für Dateneigenschaften muss ein gültiges JSON Format haben.
Nicht- JSON	Gültig JSON	EventBridge lässt den Rekord fallen.
Nicht- JSON	Kein Filtermuster für Dateneigenschaften	EventBridge filtert (nur für die anderen Metadateneigenschaften) auf der Grundlage Ihrer Filterkriterien.
Nicht- JSON	Nicht- JSON	EventBridge löst bei der Erstellung oder Aktualisierung der Pipe eine Ausnahme aus. Das Filtermuster für Dateneigenschaften muss ein gültiges JSON Format haben.

Ordnungsgemäßes Filtern der Nachrichten von Amazon Managed Streaming for Apache Kafka, von selbstverwaltetem Apache Kafka und von Amazon MQ

Für Amazon-MQ-Quellen lautet das Nachrichtenfeld data. Für Apache Kafka-Quellen (Amazon MSK und selbstverwaltetes Apache Kafka) gibt es zwei Nachrichtenfelder: key und. value

EventBridge verwirft Nachrichten, die nicht allen im Filter enthaltenen Feldern entsprechen. Übergibt bei Apache Kafka nach erfolgreichem Aufruf der Funktion Offsets für übereinstimmende und nicht übereinstimmende Nachrichten. EventBridge EventBridge Bestätigt für Amazon MQ übereinstimmende Nachrichten nach erfolgreichem Aufruf der Funktion und bestätigt nicht zugeordnete Nachrichten, wenn sie gefiltert werden.

Apache Kafka- und Amazon MQ MQ-Nachrichten müssen aus UTF -8-codierten Zeichenfolgen bestehen, entweder als einfache Zeichenketten oder im Format. JSON Das liegt daran, dass Apache Kafka- und Amazon MQ-Byte-Arrays in UTF -8 EventBridge dekodiert werden, bevor Filterkriterien angewendet werden. Wenn Ihre Nachrichten eine andere Kodierung verwenden, z. B. UTF -16 oderASCII, oder wenn das Nachrichtenformat nicht dem Format entspricht, werden nur Metadatenfilter FilterCriteria verarbeitet. EventBridge In der folgenden Tabelle ist das Verhalten zusammengefasst:

Format eingehender Nachrichten (data oder key und value)	Filtermusterformat für Nachrichteneigenschaften	Resultierende Aktion
Einfache Zeichenfolge	Einfache Zeichenfolge	EventBridge filtert auf der Grundlage Ihrer Filterkriterien.
Einfache Zeichenfolge	Kein Filtermuster für Dateneigenschaften	EventBridge filtert (nur für die anderen Metadateneigenschaften) basierend auf Ihren Filterkriterien.
Einfache Zeichenfolge	Gültig JSON	EventBridge Filter (nur für die anderen Metadateneigenschaften), die auf Ihren Filterkriterien basieren.
Gültig JSON	Einfache Zeichenfolge	EventBridge Filter (nur für die anderen Metadateneigenschaften), die auf Ihren Filterkriterien basieren.
Gültig JSON	Kein Filtermuster für Dateneigenschaften	EventBridge Filter (nur für die anderen Metadateneigenschaften), die auf Ihren Filterkriterien basieren.
Gültig JSON	Gültig JSON	EventBridge Filter, die auf Ihren Filterkriterien basieren.
Nicht UTF -8-kodierte Zeichenfolge	JSON, einfache Zeichenfolge oder kein Muster	EventBridge filtert (nur für die anderen Metadateneigenschaften) auf der Grundlage Ihrer Filterkriterien.

Unterschiede zwischen Lambda ESM und EventBridge Pipes

Beim Filtern von Ereignissen funktionieren Lambda ESM und EventBridge Pipes im Allgemeinen auf die gleiche Weise. Der Hauptunterschied besteht darin, dass das eventSourceKey Feld in ESM Payloads nicht vorhanden ist.

Verwendung von Vergleichsoperatoren in Rohrfiltern

Mit Vergleichsoperatoren können Sie Ereignismuster erstellen, die mit Feldwerten in Ereignissen übereinstimmen.

Eine vollständige Liste der Vergleichsoperatoren, die für die Verwendung in Rohrfiltern unterstützt werden, finden Sie unterVergleichsoperatoren.