Amazon-EventBridge-Pipes-Eingabetransformation

Amazon EventBridge Pipes unterstützt optionale Eingabe-Transformatoren bei der Weitergabe von Daten an die Anreicherung und das Ziel. Sie können Eingabe-Transformatoren verwenden, um die Nutzlast der JSON-Ereigniseingabe so umzugestalten, dass sie den Anforderungen des Anreicherungs- oder Zielservice gerecht wird. Für Amazon API Gateway und API-Ziele passen Sie das Eingabeereignis auf diese Weise an das RESTful-Modell der API an. Eingabe-Transformatoren werden als InputTemplate-Parameter modelliert. Sie können Freitext, ein JSON-Pfad zur Ereignisnutzlast oder ein JSON-Objekt sein, das Inline-JSON-Pfade zur Ereignisnutzlast enthält. Zur Anreicherung stammt die Ereignisnutzlast aus der Quelle. Bei Zielen ist die Ereignisnutzlast das, was von der Anreicherung zurückgegeben wird, sofern eine solche für die Pipe konfiguriert ist. Zusätzlich zu den servicespezifischen Daten in der Ereignisnutzlast können Sie reservierte Variablen in Ihrer InputTemplate verwenden, um auf Daten für die Pipe zu verweisen.

Verwenden Sie die Notation mit eckigen Klammern, um auf Elemente in einem Array zuzugreifen.

Anmerkung

EventBridge unterstützt nicht die gesamte JSON-Pfadsyntax und wertet sie nicht zur Laufzeit aus. Die unterstützte Syntax umfasst:

• Punktnotation (zum Beispiel $.detail)

• Bindestriche

• Unterstriche

• Alphanumerische Zeichen

• Array-Indizes

• Platzhalter (*)

Im Folgenden finden Sie InputTemplate-Beispielparameter, die auf eine Amazon-SQS-Ereignisnutzlast verweisen:

Statische Zeichenfolge

InputTemplate: "Hello, sender"

JSON-Pfad

InputTemplate: <$.attributes.SenderId>

Dynamische Zeichenfolge

InputTemplate: "Hello, <$.attributes.SenderId>"

Statisches JSON

InputTemplate: >
{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3",
}

Dynamisches JSON

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.key>,
  "d": <aws.pipes.event.ingestion-time>
}

Verwenden der Notation mit eckigen Klammern, um auf ein Element in einem Array zuzugreifen:

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.Records[3]>,
  "d": <aws.pipes.event.ingestion-time>
}

Anmerkung

EventBridge ersetzt Eingabe-Transformatoren zur Laufzeit, um eine gültige JSON-Ausgabe sicherzustellen. Setzen Sie aus diesem Grund Variablen, die auf JSON-Pfadparameter verweisen, in Anführungszeichen, Variablen, die sich auf JSON-Objekte oder -Arrays beziehen, jedoch nicht in Anführungszeichen.

Reservierte Variablen

Eingabevorlagen können die folgenden reservierten Variablen verwenden:

• <aws.pipes.pipe-arn> – Der Amazon-Ressourcenname (ARN) für die Pipe

• <aws.pipes.pipe-name> – Der Name der Pipe

• <aws.pipes.source-arn> – Der ARN der Ereignisquelle der Pipe

• <aws.pipes.enrichment-arn> – Der ARN der Anreicherung der Pipe

• <aws.pipes.target-arn> – Der ARN des Ziels der Pipe

• <aws.pipes.event.ingestion-time> – Der Zeitpunkt, zu dem das Ereignis vom Eingabe-Transformator empfangen wurde Dies ist ein ISO-8601-Zeitstempel. Diese Zeit ist für den Eingabe-Transformator der Anreicherung und den Eingabe-Transformator des Ziels unterschiedlich, je nachdem, wann die Anreicherung die Verarbeitung des Ereignisses abgeschlossen hat.

• <aws.pipes.event> – Das Ereignis, wie es vom Eingabe-Transformator empfangen wurde

  Bei einem Eingabe-Transformator der Anreicherung ist dies das Ereignis aus der Quelle. Dies enthält die ursprüngliche Nutzlast aus der Quelle sowie zusätzliche servicespezifische Metadaten. Weitere servicespezifische Beispiele finden Sie in den Themen unter Amazon EventBridge Pipes-Quellen.

  Bei einem Eingabe-Transformator des Ziels ist dies das Ereignis, das von der Anreicherung zurückgegeben wird, sofern eine solche konfiguriert ist, ohne zusätzliche Metadaten. Daher kann es sich bei einer Nutzlast, die durch eine Anreicherung zurückgegeben wurde, um Nicht-JSON handeln. Wenn für die Pipe keine Anreicherung konfiguriert ist, ist dies das Ereignis aus der Quelle mit Metadaten.

• <aws.pipes.event.json> – Das Gleiche wie aws.pipes.event, aber die Variable hat nur dann einen Wert, wenn die ursprüngliche Nutzlast, entweder aus der Quelle oder von der Anreicherung zurückgegeben, JSON ist. Wenn die Pipe ein codiertes Feld hat, z. B. das Amazon-SQS-Feld body oder die Kinesis-data, werden diese Felder decodiert und in gültiges JSON umgewandelt. Da sie nicht maskiert ist, kann die Variable nur als Wert für ein JSON-Feld verwendet werden. Weitere Informationen finden Sie unter Implizites Textdatenparsen.

Beispiel für die Eingabetransformation

Im Folgenden finden Sie ein Beispiel für ein Amazon-EC2-Ereignis, das wir als Beispielereignis verwenden können.

{
  "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-0123456789",
    "state": "RUNNING"
  }
}
		

Lassen Sie uns den folgenden JSON als unseren Transformator verwenden.

{
  "instance" : <$.detail.instance-id>,
  "state": <$.detail.state>,
  "pipeArn" : <aws.pipes.pipe-arn>,
  "pipeName" : <aws.pipes.pipe-name>,
  "originalEvent" : <aws.pipes.event.json>
}

Die resultierende Ausgabe sieht wie folgt aus:

{
  "instance" : "i-0123456789",
  "state": "RUNNING",
  "pipeArn" : "arn:aws:pipe:us-east-1:123456789012:pipe/example",
  "pipeName" : "example",
  "originalEvent" : {
    ... // commented for brevity
  }
}

Implizites Textdatenparsen

Die folgenden Felder in der eingehenden Nutzlast können JSON-maskiert, wie das Amazon-SQS-Objekt body, oder base64-kodiert sein, wie das Kinesis-Objekt data. Sowohl für die Filterung als auch für die Eingabetransformation wandelt EventBridge diese Felder in gültiges JSON um, sodass Unterwerte direkt referenziert werden können. Zum Beispiel <$.data.someKey> für Kinesis.

Damit das Ziel die ursprüngliche Nutzlast ohne zusätzliche Metadaten erhält, verwenden Sie einen Eingabe-Transformator mit diesen Textdaten, die für die Quelle spezifisch sind. Zum Beispiel <$.body> für Amazon SQS oder <$.data> für Kinesis. Wenn die ursprüngliche Nutzlast eine gültige JSON-Zeichenfolge ist (zum Beispiel {"key": "value"}), führt die Verwendung des Eingabe-Transformators mit quellspezifischen Textdaten dazu, dass die Anführungszeichen innerhalb der ursprünglichen Quellnutzlast entfernt werden. Zum Beispiel wird {"key": "value"} zu "{key: value}", wenn es an das Ziel übermittelt wird. Wenn das Ziel gültige JSON-Nutzlasten benötigt (z. B. EventBridge Lambda oder Step Functions), führt dies zu einer fehlgeschlagenen Übermittlung. Damit das Ziel die ursprünglichen Quelldaten empfängt, ohne ungültiges JSON zu generieren, umschließen Sie den Dateneingabe-Transformator des Quelltextes in JSON. Zum Beispiel {"data": <$.data>}.

Implizites Textparsen kann auch verwendet werden, um Werte für die meisten Pipe-Ziel- oder Anreicherungsparameter dynamisch aufzufüllen. Weitere Informationen finden Sie unter Dynamische Pfadparameter.

Anmerkung

Wenn es sich bei der ursprünglichen Nutzlast um gültiges JSON handelt, enthält dieses Feld das nicht maskierte, nicht base64-kodierte JSON. Wenn es sich bei der Nutzlast jedoch nicht um gültiges JSON handelt, base64-codiert EventBridge für die unten aufgeführten Felder, mit Ausnahme von Amazon SQS.

• Aktives MQ – data

• Kinesis – data

• Amazon MSK – key und value

• Rabbit MQ – data

• Selbstverwaltetes Apache Kafka – key und value

• Amazon SQS – body

Häufige Probleme beim Transformieren von Eingaben

Dies sind einige häufige Probleme beim Transformieren von Eingaben in EventBridge-Pipes:

• Für Zeichenfolgen sind Anführungszeichen erforderlich.

• Beim Erstellen des JSON-Pfads für Ihre Vorlage erfolgt keine Validierung.

• Wenn Sie eine Variable angeben, die einem JSON-Pfad entspricht, der im Ereignis nicht vorhanden ist, wird diese Variable nicht erstellt und nicht in der Ausgabe angezeigt.

• JSON-Eigenschaften wie aws.pipes.event.json können nur als Wert eines JSON-Felds verwendet werden, nicht inline in anderen Zeichenfolgen.

• EventBridge maskiert Werte, die vom Eingabepfad extrahiert werden, nicht, wenn die Eingabevorlage für ein Ziel gefüllt wird.

• Wenn ein JSON-Pfad auf ein JSON-Objekt oder ein JSON-Array verweist, die Variable jedoch in einer Zeichenfolge referenziert wird, entfernt EventBridge alle internen Anführungszeichen, um sicherzustellen, dass eine gültige Zeichenfolge vorliegt. Zum Beispiel würde "Body is <$.body>" dazu führen, dass EventBridge Anführungszeichen aus dem Objekt entfernt.

  Wenn Sie also ein JSON-Objekt ausgeben möchten, das auf einer einzelnen JSON-Pfadvariablen basiert, müssen Sie es als Schlüssel platzieren. In diesem Beispiel {"body": <$.body>}.

• Für Variablen, die Zeichenfolgen darstellen, sind keine Anführungszeichen erforderlich. Sie sind zulässig, aber EventBridge Pipes fügt Werten für Zeichenfolgenvariablen während der Transformation automatisch Anführungszeichen hinzu, um sicherzustellen, dass die Transformationsausgabe gültiges JSON ist. EventBridge Pipes fügt Variablen, die JSON-Objekte oder -Arrays darstellen, keine Anführungszeichen hinzu. Fügen Sie für Variablen, die JSON-Objekte oder -Arrays darstellen, keine Anführungszeichen hinzu.

  Die folgende Eingabevorlage enthält beispielsweise Variablen, die sowohl Zeichenfolgen als auch JSON-Objekte darstellen:

  {
    "pipeArn" : <aws.pipes.pipe-arn>,
    "pipeName" : <aws.pipes.pipe-name>,
    "originalEvent" : <aws.pipes.event.json>
  }

  Das Ergebnis ist gültiges JSON mit den richtigen Anführungszeichen:

  {
    "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example",
    "pipeName" : "example",
    "originalEvent" : {
      ... // commented for brevity
    }
  }

• Bei Lambda- oder Step-Functions-Anreicherungen oder -Zielen werden Stapel als JSON-Arrays an das Ziel übermittelt, auch wenn die Stapelgröße 1 ist. Eingabe-Transformatoren werden jedoch weiterhin auf einzelne Datensätze im JSON-Array angewendet, nicht auf das gesamte Array. Weitere Informationen finden Sie unter Stapelverarbeitung und Gleichzeitigkeit von Amazon EventBridge Pipes.