Exemples de transformations

Avancé

Vous pouvez transformer vos données CloudEvents en écrivant des expressions de transformation à l'aide du CEL. Pour en savoir plus, consultez Transformer les événements reçus.

Attention : N'incluez pas d'informations sensibles telles que des mots de passe, des secrets ou des informations permettant d'identifier personnellement l'utilisateur dans les expressions de transformation CEL. Ces expressions sont traitées comme des données de configuration de service par Eventarc Advanced et ne bénéficient pas du même niveau de sécurité des données que les charges utiles d'événement.

Voici quelques cas d'utilisation et exemples courants qui vous montrent comment écrire des expressions CEL pour transformer vos données d'événement.

Cas d'utilisation standards

Voici quelques cas d'utilisation standards pour la transformation des données d'événement.

Remarque : Pour simplifier les exemples, les attributs de contexte CloudEvents requis ont été omis.

Normalisation des données

Vous devez aplatir une structure de données imbriquée dans votre message d'événement pour faciliter le traitement par un service en aval.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "orderId": "12345",
    "customer": {
      "firstName": "Alex",
      "lastName": "Taylor",
      "address": {
        "street": "1800 Amphibious Blvd.",
        "city": "Mountain View"
      }
    }
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "orderId": "12345",
    "customerFirstName": "Alex",
    "customerLastName": "Taylor",
    "customerStreet": "1800 Amphibious Blvd.",
    "customerCity": "Mountain View"
  }
}

Solution 1 :

Mettez en forme les données de sortie manuellement. Cela vous permet de lister les noms de champs et de sélectionner uniquement les éléments nécessaires dans le résultat. Il s'agit d'une approche raisonnable lorsque l'entrée est prévisible et que le nombre de champs est faible. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. Exemple :

message.setField("data",
{
  "orderId": message.data.orderId,
  "customerFirstName": message.data.customer.firstName,
  "customerLastName": message.data.customer.lastName,
  "customerStreet": message.data.customer.address.street,
  "customerCity": message.data.customer.address.city,
})

Solution 2 :

Utilisez une fonction dans votre expression. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. La fonction denormalize aplatit les structures profondes en une liste de paires clé/valeur. Les noms de champs sont délimités par un point (.) pour segmenter la hiérarchie de la structure. Exemple :

message.setField("data", message.data.denormalize())

Cela génère la sortie suivante, qui diffère légèrement de la charge utile attendue. Toutefois, les avantages incluent une expression CEL plus courte qui fonctionne sur n'importe quelle entrée et qui inclut automatiquement n'importe quel nombre de champs entrants.

{
  "data": {
    "orderId": "12345",
    "customer.firstName": "Alex",
    "customer.lastName": "Taylor",
    "customer.address.street": "1800 Amphibious Blvd.",
    "customer.address.city": "Mountain View"
  }
}

Masquage des données

Vous devez masquer les données sensibles dans une charge utile d'événement avant de l'envoyer dans un environnement moins sécurisé.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "userId": "user123",
    "email": "[e-mail]",
    "creditCardNumber": "1234-5678-9012-3456"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "userId": "user123",
    "email": "a***@example.com",
    "creditCardNumber": "xxxx-xxxx-xxxx-3456"
  }
}

Solution :

Utilisez une expression pour masquer les informations sensibles, telles que l'adresse e-mail et le numéro de carte de crédit. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. La fonction d'expression régulière extract suit la syntaxe RE2. Exemple :

message
      .setField("data.email",
          re.extract(message.data.email,
                    "(^.).*@(.*)",
                    "\\1***@\\2"))

      .setField("data.creditCardNumber",
          re.extract(message.data.creditCardNumber,
                    "(\\d{4})\\D*$",
                    "xxxx-xxxx-xxxx-\\1"))

Masquage des données

Vous devez supprimer des champs spécifiques d'une charge utile d'événement en fonction de certaines conditions.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "orderId": "12345",
    "customerType": "gold",
    "discountCode": "VIP"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  {
  "orderId": "12345",
  "customerType": "gold"
  }
}

Solution :

Utilisez une expression qui masque le champ discountCode si le champ customerType est défini sur "gold". La fonction removeFields supprime des champs spécifiques d'un événement. Exemple :

message.data.customerType == "gold" ?
      message.removeFields(["data.discountCode"]) :
      message

Convertir des données

Vous devez convertir des données d'un format ou d'un type à un autre.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "orderDate": "2024-10-31T12:00:00Z",
    "totalAmount": "1500"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "orderDate": 1704086400,
    "totalAmount": 1500.00
  }
}

Solution :

Utilisez une expression qui convertit orderDate en code temporel UNIX, et le type totalAmount de string en double (nombre à virgule flottante). La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. Vous pouvez utiliser des fonctions de manipulation de chaînes pour convertir les résultats de chaîne. Exemple :

message
      .setField("data.orderDate", int(timestamp(message.data.orderDate)))
      .setField("data.totalAmount", double(message.data.totalAmount))

Routage conditionnel

Vous devez router les événements vers différentes destinations en fonction des données d'événement.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "eventType": "order.created",
    "orderValue": 200
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "eventType": "order.created",
    "orderValue": 200,
    "routingKey": "highValue"
  }
}

Solution :

Utilisez une expression qui ajoute un champ routingKey avec une valeur "highValue" si orderValue est supérieur à 100, sinon "normal". Le champ routingKey peut être utilisé pour déterminer le chemin de routage. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. Exemple :

message.data.orderValue > 100 ?
      message.setField("data.routingKey", "highValue") :
      message.setField("data.routingKey", "normal")

Gestion des valeurs par défaut

Vous devez vous assurer que certains champs de la charge utile de l'événement ont des valeurs par défaut s'ils ne sont pas présents.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "itemName": "Product A"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "itemName": "Product A",
    "quantity": 1
  }
}

Solution :

Utilisez une expression qui ajoute un champ quantity avec une valeur par défaut de 1 si le champ n'existe pas déjà. La macro has permet de vérifier si un champ est disponible. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. Exemple :

has(message.data.quantity)  ?
    message :
    message.setField("data.quantity", 1)

Manipulation de chaînes

Vous devez extraire ou modifier des parties d'un champ de chaîne dans les données d'événement.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "customerEmail": "[e-mail]"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "customerEmail": "[e-mail]",
    "emailDomain": "example.com"
  }
}

Solution :

Utilisez une expression qui extrait le nom de domaine ("example.com") du champ customerEmail et le stocke dans un nouveau champ emailDomain. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. La fonction d'expression régulière extract suit la syntaxe RE2. Exemple :

message
  .setField("data.emailDomain",
re.extract(message.data.customerEmail, "(^.*@)(.*)", "\\2"))

Opérations de liste et de mappage

Vous devez travailler avec des listes ou des cartes dans les données d'événement.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "productIds": [
      "product123",
      "product456"
    ]
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "productIds": [
      "product123",
      "product456"
    ],
    "productFound": true
  }
}

Solution :

Utilisez une expression qui vérifie si "product456" existe dans la liste productIds et stocke le résultat (true ou false) dans un nouveau champ productFound. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. La macro exists teste si un prédicat est valable pour tous les éléments d'une liste et combine les résultats avec l'opérateur "or". Exemple :

message.setField("data.productFound",
        message.data.productIds.exists(id, id == "product123"))

Gestion des exceptions

Vous devez gérer correctement les erreurs potentielles ou les données inattendues dans la charge utile de l'événement.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "quantity": "abc"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "quantity": 0,
    "error": "Invalid quantity"
  }
}

Solution :

Utilisez une expression qui tente de convertir le champ quantity en entier. Si la conversion échoue, définissez le champ quantity sur 0 et ajoutez un champ error avec la valeur "Quantité non valide".

• La macro has teste si un champ est disponible.
• La fonction type renvoie le type d'une valeur.
• La fonction d'expression régulière matches suit la syntaxe RE2.
• La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée.

Exemple :

// Check if data.quantity exists
has(message.data.quantity) &&
// Check if data.quantity is a string
type(message.data.quantity) == string &&
// Check if string consists of digits
message.data.quantity.matches(r'^-?[0-9]+$') ?
  // If data.quantity is valid, use message
  message :
  // If data.quantity is invalid, set to 0 and generate error
  message
    .setField("data.quantity", 0)
    .setField("data.error", "Invalid quantity")

Cas d'utilisation complexes

Voici quelques cas d'utilisation complexes lors de la transformation des données d'événement.

Remarque : Pour simplifier les exemples, les attributs de contexte CloudEvents requis ont été omis.

Transformation des données

Vous devez effectuer plusieurs transformations sur des données d'événement imbriquées.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "orderId": "12345",
    "customer": {
      "firstName": "Alex",
      "lastName": "Taylor",
      "email": "[e-mail]",
      "address": {
        "street": "1800 Amphibious Blvd.",
        "city": "Mountain View",
        "state": "CA"
      }
    },
    "items": [
      {
        "itemId": "item1",
        "price": 10.00,
        "quantity": 2
      },
      {
        "itemId": "item2",
        "price": 5.00,
        "quantity": 1
      }
    ]
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "orderId": "12345",
    "customer.firstName": "Alex",
    "customer.lastName": "Taylor",
    "customer.email": "a***@example.com",
    "customer.address.city": "Mountain View",
    "customer.address.state": "CA"
  }
}

Solution :

Utilisez une expression qui extrait la ville et l'état de l'adresse, et qui masque l'adresse e-mail.

• La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée.
• La fonction toMap convertit une liste de mappages CEL en un seul mappage CEL.
• La fonction d'expression régulière extract suit la syntaxe RE2.
• La fonction removeFields supprime des champs spécifiques d'un événement.
• La fonction denormalize aplatit les structures profondes en une liste de paires clé/valeur. Les noms de champs sont délimités par un point (.) pour segmenter la hiérarchie de la structure.

Exemple :

message
.setField("data",
  message.data.setField("customer.address",
    message.data.customer.address.map(key, key == "city" || key == "state",
          { key: message.data.customer.address[key] }).toMap())
  .setField("customer.email",
        re.extract(message.data.customer.email, "(^..?).*@(.*)", "\\1***@\\2"))
  .removeFields(["items"])
  .denormalize()
)

Mise en forme et routage des données

Vous devez mettre en forme les données d'événement, ajouter des informations sur le produit, puis acheminer le message d'événement.

Scénario :

Compte tenu des données CloudEvents suivantes :

{
  "data": {
    "productId": "p123",
    "productName": "Example Product",
    "category": "electronics"
  }
}

Vous souhaitez écrire une expression CEL qui génère le résultat suivant :

{
  "data": {
    "productId": "electronics-p123",
    "productName": "EXAMPLE PRODUCT",
    "category": "electronics",
    "routingKey": "electronics"
  }
}

Solution :

Utilisez une expression qui met en majuscules le nom du produit, ajoute un préfixe à l'ID du produit en fonction de sa catégorie et inclut une clé de routage pour le traitement en aval. La fonction setField ajoute ou remplace un champ de l'événement par une clé donnée. La fonction upperAscii renvoie une chaîne avec tous les caractères ASCII convertis en majuscules correspondantes. Exemple :

message
.setField("data.productId",
message.data.category + "-" + message.data.productId)
.setField("data.productName", message.data.productName.upperAscii())
.setField("data.routingKey", message.data.category)