Empfangene Ereignisse transformieren

Sie können Ihre Ereignisdaten transformieren, indem Sie Transformationsausdrücke mit CEL schreiben. Beispielsweise lassen sich Ereignisnutzlasten ändern, um dem API-Vertrag eines bestimmten Ziels zu entsprechen.

Ereignisse werden immer im CloudEvents-Format mit einer HTTP-Anfrage im Binärinhaltsmodus gesendet, sofern Sie keine Nachrichtenbindung angeben.

Eingabe- und Ausgabedatenformate festlegen

Zusätzlich zum Schreiben eines Transformationsausdrucks in CEL können Sie optional das Datenformat der eingehenden Ereignisdaten angeben. So kann Eventarc Advanced die Nutzlast des Ereignisses parsen. Sie können die Daten auch von einem Format in ein anderes konvertieren.

Die folgenden Formate werden unterstützt: Avro, JSON und Protobuf. Weitere Informationen finden Sie unter Empfangene Ereignisse formatieren.

Transformationsausdrücke

Beim Transformieren von Ereignissen kann in einem CEL-Ausdruck über ein vordefiniertes message-Objekt auf alle Ereignisattribute als Variablen zugegriffen werden. Diese Variablen werden zur Laufzeit anhand der Ereignisdaten mit Werten gefüllt. Beispiel:

• message.id gibt das Attribut id des Ereignisses zurück.
• message.data gibt eine CEL-Wertdarstellung der Ereignisnutzlast zurück.
• message.data.some-key gibt den Inhalt eines Felds namens some-key aus der Ereignisnutzlast zurück.

Felder in message.data werden immer als String-Typen dargestellt. Werte werden aus dem ursprünglichen Ereignis mithilfe des Schemas zugeordnet, das beim Festlegen des Eingabedatenformats angegeben wurde.

Der Transformationsausdruck sollte ein vollständiges Ereignis mit den Attributen des Ereigniskontexts und der Ereignisdaten-Nutzlast enthalten. Ausdrücke werden in JSON geschrieben, aber vordefinierte CEL-Funktionen, Makros und Operatoren sowie reguläre Ausdrücke mit RE2 werden unterstützt. Eventarc Advanced unterstützt auch bestimmte Erweiterungsfunktionen, mit denen die Ereignisdaten transformiert werden können.

Im Folgenden finden Sie zwei Beispiele für die Verwendung von CEL-Ausdrücken zum Transformieren Ihrer Ereignisdaten. Weitere Anwendungsfälle und Beispiele finden Sie unter Transformationsbeispiele.

  // Input:
  // {
  //   "data":
  //   {
  //     "email_address": "charlie@altostrat.com",
  //     "phone_number": "8005550100",
  //   }
  // }
  // Output:
  // {
  //    "data":
  //    {
  //      "email_domain": "altostrat.com",
  //      "phone_number": "(800) 555-0100",
  //      "area_code": "800",
  //      "local_number": "5550100",
  //    }
  // }

  {
    "data":
    {
      "email_domain": re.capture(
                        message.data.email_address,
                        "\\S+@(\\S+)"),

      "phone_number": re.extract(
                        message.data.phone_number,
                        "^(\\d{3})(\\d{3})(\\d{4})", "(\\1) \\2-\\3"
                      ),

    }.merge ( re.captureN(message.data.phone_number,
                        "^(?P\d{3})[\w\-)(]*(?P\d{7})"
                      )
    )
  }

  // Input:
  // {
  //   "data":
  //   {
  //        "product_ids": [1, 2, 3]
  //   }
  // }
  // Output:
  // {
  //    "data":
  //    {
  //             "products": [
  //                {
  //                   "name": "apple",
  //                   "price": 70
  //                },
  //                {
  //                    "name": "orange",
  //                    "price":  80
  //                },
  //                {
  //                    "name": "Product(3)",
  //                    "price": 0
  //                },
  //                {
  //                     "name": "apple",
  //                     "price": 70
  //                }
  //            ]
  //    }
  // }

  {
    "data":
    {
      "products":  message.data.product_ids.map(product_id,
              product_id == 1?
              {
                "name": "apple",
                "price": 70
              } :
              product_id == 2?
              {
                "name": "orange",
                "price":  80
              } :
              // Default:
              {
                "name": "Product(" + string(product_id) + ")",
                "price": 0
              }
          )
    }
  }

Pipeline zum Transformieren von Ereignissen konfigurieren

Sie können eine Pipeline zum Transformieren von Ereignisdaten in der Google Cloud -Konsole oder mit der gcloud CLI konfigurieren.

Pro Pipeline wird nur eine Vermittlung unterstützt.

Erweiterungsfunktionen

Eventarc Advanced unterstützt die folgenden Erweiterungsfunktionen, mit denen die über einen Bus empfangenen Ereignisdaten transformiert werden können.

// Input:
// {
//   "data": 
//   {
//        "credit_card_number": "XXXX-XXXX-XXXX-XXXX"
//   }
// }
// Output:
// {
//    "data":
//    {
//        "credit_card_number": "XXXX-XXXX-XXXX-XXXX",
//        "card_type": "credit"
//    }
// }
{
  "data": message.data.merge(
    {
      "card_type": "credit"
    }
  )
}

// Input:
//{
//"data": 
//   {
//        "products": [
//          {
//            "number": 021774,
//            "type": "perishable",
//            "price": 2.00
//          },
//          {
//            "number": 95602,
//            "type": "diy",
//            "price": 120.00
//          },
//          {
//            "number": 568302,
//            "type": "toys",
//            "price": 12.00
//          }
//        ]
//   }
//}
//
// Output:
//{
//"data":
//    {
//        "products": {
//            "0.number": 021774,
//            "0.type": "perishable",
//            "0.price": 2.00,
//            "1.number": 95602,
//            "1.type": "diy",
//            "1.price": 120.00,
//            "2.number": 568302,
//            "2.type": "toys",
//            "2.price": 12.00
//          }
//   }
//}
//
//
message.setField("data.products", message.data.products.denormalize())

// Input:
// {
//   "data": 
//   {
//     "payment": {
//       "card_number": "XXXX-XXXX-XXXX-XXXX",
//       "card_type": "credit",
//     }
//   }
// }
// Output:
// {
//   "data":
//   {
//     "payment": {
//       "card_type": "credit"
//     }
//   }
// }
message.removeFields(["data.payment.card_number"])

Nachrichtenbindung definieren

Standardmäßig werden Ereignisse immer im CloudEvents-Format mit einer HTTP-Anfrage im Binärinhaltsmodus an ein Ziel gesendet. Sie können dieses Verhalten überschreiben, indem Sie eine Nachrichtenbindung definieren und eine neue HTTP-Anfrage erstellen.

Alle HTTP-Header, die durch andere Richtlinien oder Steuerelemente eingeführt werden (z. B. OAuth- oder OIDC-Tokens), werden beibehalten und mit den Headern zusammengeführt, die sich aus dem Bindungsausdruck ergeben.

Sie können eine Nachrichtenbindung definieren, wenn Sie eine Pipeline in derGoogle Cloud -Konsole oder mit der gcloud CLI konfigurieren.

Auf eingehende Nachrichten zugreifen

Sie können mit einem CEL-Ausdruck auf eine eingehende CloudEvents-Nachricht zugreifen:

• Verwenden Sie den Wert message.data, um auf das Feld data der eingehenden Nachricht zuzugreifen.
• Verwenden Sie die message.key-Werte (wobei key der Name des Attributs ist), um auf die Attribute der eingehenden Nachricht zuzugreifen.

• Verwenden Sie eine headers-Variable, um auf alle Header zuzugreifen, die der HTTP-Anfrage durch vorherige Vermittlungen in der Verarbeitungskette hinzugefügt wurden. Diese Variable definiert eine Zuordnung von Schlüssel/Wert-Paaren, die den zusätzlichen HTTP-Headern und nicht den ursprünglichen Headern der ersten eingehenden Anfrage entsprechen.

  Mit dem folgenden CEL-Ausdruck kann beispielsweise eine HTTP-Anfrage nur mit Headern erstellt werden, indem den Headern, die in vorherigen Pipeline-Mediationen hinzugefügt wurden, ein zusätzlicher Header hinzugefügt wird:

  {"headers": headers.merge({"new-header-key": "new-header-value"})}

HTTP-Anfragen erstellen

Das Ergebnis des CEL-Ausdrucks muss eine Zuordnung von Schlüssel/Wert-Paaren sein, deren Felder headers und body zum Erstellen der HTTP-Anfrage verwendet werden.

Für headers-Felder:

• Wenn aufgrund des CEL-Ausdrucks eine headers-Zuordnung vorhanden ist, werden ihre Schlüssel-Wert-Paare direkt den HTTP-Anfrageheadern zugeordnet und ihre Werte werden mithilfe der kanonischen Stringcodierung des entsprechenden Datentyps erstellt.
• Wenn kein headers-Feld vorhanden ist, enthält die resultierende HTTP-Anfrage keine Header.

Für body-Felder:

• Wenn aufgrund des CEL-Ausdrucks ein body-Feld vorhanden ist, wird sein Wert direkt dem HTTP-Anfragetext zugeordnet.
• Wenn der Feldwert body vom Typ bytes oder string ist, wird er unverändert als HTTP-Anfragetext verwendet. Andernfalls wird er in einen JSON-String konvertiert.
• Wenn das Feld body nicht vorhanden ist, ist der resultierende HTTP-Anfragetext der Text der endgültigen CloudEvents-HTTP-Nachrichtenbindung im Binärinhaltsmodus.

Alle anderen Felder, die sich aus dem CEL-Ausdruck ergeben, werden ignoriert.

Erweiterungsfunktionen

Eventarc Advanced unterstützt die folgenden Erweiterungsfunktionen, mit denen die Ereignisdaten transformiert werden können, wenn eine Nachrichtenbindung angegeben wird.

gcloud beta eventarc pipelines create my-pipeline \
    --location=us-central1 \
    --input-payload-format-json='{}' \
    --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment,http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/avro"}), "body": message.data.toDestinationPayloadFormat()"}',output_payload_format_avro_schema_definition='{"schema_definition": "{"type":"record","name":"myrecord","fields":[{"name":"name","type":"string"},{"name":"account_late","type":"boolean"}]}"}'

Nächste Schritte

• Empfangene Ereignisse formatieren
• Transformationsbeispiele