Transformer les événements reçus

Vous pouvez transformer vos données d'événement en écrivant des expressions de transformation à l'aide du CEL. Par exemple, vous pouvez modifier les charges utiles d'événements pour respecter le contrat d'API spécifique d'une destination.

Notez que les événements sont toujours envoyés au format CloudEvents à l'aide d'une requête HTTP en mode "contenu binaire", sauf si vous spécifiez une liaison de message.

Définir les formats de données d'entrée et de sortie

En plus d'écrire une expression de transformation au format CEL, vous pouvez éventuellement spécifier le format de données des données d'événement entrantes. Cela permet à Eventarc Advanced de savoir comment analyser la charge utile de l'événement. Vous pouvez également convertir les données d'un format à un autre.

Les formats suivants sont acceptés : Avro, JSON et Protobuf. Pour en savoir plus, consultez Mettre en forme les événements reçus.

Expressions de transformation

Lorsque vous transformez des événements, vous pouvez accéder à tous les attributs d'événement dans une expression CEL en tant que variables via un objet message prédéfini. Ces variables sont renseignées avec des valeurs basées sur les données d'événement lors de l'exécution. Exemple :

• message.id renvoie l'attribut id de l'événement.
• message.data renvoie une représentation de la charge utile de l'événement sous forme de valeur CEL.
• message.data.some-key renvoie le contenu d'un champ nommé some-key à partir de la charge utile de l'événement.

Les champs de message.data sont toujours représentés sous forme de types String et les valeurs sont mappées à partir de l'événement d'origine à l'aide du schéma spécifié lors de la définition du format des données d'entrée.

L'expression de transformation doit exprimer un événement complet qui inclut les attributs de contexte d'événement et la charge utile des données d'événement. Les expressions sont écrites en JSON, mais les fonctions, macros et opérateurs CEL prédéfinis, ainsi que les expressions régulières utilisant RE2 sont acceptés. Eventarc Advanced est également compatible avec certaines fonctions d'extension qui peuvent être utilisées pour transformer les données d'événement.

Vous trouverez ci-dessous deux exemples d'utilisation d'expressions CEL pour transformer vos données d'événement. Pour découvrir d'autres cas d'utilisation et exemples, consultez Exemples de transformations.

  // 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
              }
          )
    }
  }

Configurer un pipeline pour transformer des événements

Vous pouvez configurer un pipeline pour transformer les données d'événement dans la console Google Cloud ou à l'aide de gcloud CLI.

Notez qu'une seule médiation par pipeline est acceptée.

Fonctions d'extension

Eventarc Advanced est compatible avec les fonctions d'extension suivantes, qui peuvent être utilisées pour transformer les données d'événement reçues via un bus.

// 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"])

Définir une liaison de message

Par défaut, les événements sont toujours envoyés à une destination au format CloudEvents à l'aide d'une requête HTTP en mode "contenu binaire". Vous pouvez modifier ce comportement en définissant une liaison de message et en construisant une nouvelle requête HTTP.

Tous les en-têtes HTTP introduits par d'autres règles ou contrôles (par exemple, les jetons OAuth ou OIDC) sont conservés et fusionnés avec les en-têtes résultant de l'expression de liaison.

Vous pouvez définir une liaison de message lorsque vous configurez un pipeline dans la consoleGoogle Cloud ou à l'aide de gcloud CLI.

Accéder aux messages entrants

Vous pouvez utiliser une expression CEL pour accéder à un message CloudEvents entrant comme suit :

• Utilisez la valeur message.data pour accéder au champ data du message entrant.
• Utilisez les valeurs message.key (où key est le nom de l'attribut) pour accéder aux attributs du message entrant.

• Utilisez une variable headers pour accéder à tous les en-têtes ajoutés à la requête HTTP par les médiations précédentes de la chaîne de traitement. Cette variable définit un mappage de paires clé-valeur correspondant aux en-têtes HTTP supplémentaires et non aux en-têtes d'origine de la requête entrante initiale.

  Par exemple, l'expression CEL suivante peut être utilisée pour construire une requête HTTP avec en-têtes uniquement en ajoutant un en-tête supplémentaire à ceux ajoutés dans les médiations de pipeline précédentes :

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

Créer des requêtes HTTP

Le résultat de l'expression CEL doit être un mappage de paires clé/valeur dont les champs headers et body sont utilisés pour construire la requête HTTP comme suit.

Pour les champs headers :

• Si une carte headers existe à la suite de l'expression CEL, ses paires clé-valeur sont directement mappées aux en-têtes de requête HTTP, et ses valeurs sont construites à l'aide de l'encodage de chaîne canonique du type de données correspondant.
• Si un champ headers n'existe pas, la requête HTTP résultante ne contiendra aucun en-tête.

Pour les champs body :

• Si un champ body existe à la suite de l'expression CEL, sa valeur est directement mappée au corps de la requête HTTP.
• Si la valeur du champ body est de type bytes ou string, elle est utilisée telle quelle comme corps de la requête HTTP. Sinon, elle est convertie en chaîne JSON.
• Si le champ body n'existe pas, le corps de la requête HTTP résultant est le corps de la liaison du message HTTP CloudEvents final en mode contenu binaire.

Tous les autres champs résultant de l'expression CEL sont ignorés.

Fonctions d'extension

Eventarc Advanced est compatible avec les fonctions d'extension suivantes, qui peuvent être utilisées pour transformer les données d'événement lors de la spécification d'une liaison de message.

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"}]}"}'

Étapes suivantes

• Mettre en forme les événements reçus
• Exemples de transformations