Utiliser Common Expression Language

Le CEL (Common Expression Language) est un langage Open Source non Turing-complet qui peut être utilisé pour évaluer des expressions. Chaque inscription à Eventarc Advanced inclut une expression de condition écrite en CEL qui est utilisée pour évaluer et filtrer les messages. Vous pouvez également transformer le contenu de vos données d'événement en écrivant des expressions de transformation à l'aide du CEL.

En général, une expression de condition se compose d'une ou plusieurs instructions qui sont combinées par des opérateurs logiques (&&, || ou !). Chaque instruction exprime une règle basée sur des attributs qui est appliquée aux données. Le plus souvent, les opérateurs sont utilisés pour comparer la valeur contenue dans une variable avec une valeur littérale.

Par exemple, si la valeur de message.type est google.cloud.dataflow.job.v1beta3.statusChanged, l'expression message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" renvoie True.

Pour en savoir plus, consultez les ressources suivantes :

Attributs disponibles

Vous pouvez accéder à tous les attributs de contexte d'événement en tant que variables via un objet message prédéfini. Ces variables sont renseignées avec des valeurs basées sur les attributs de contexte d'événement lors de l'exécution. Une inscription peut utiliser une variable pour exprimer un attribut donné. Par exemple, message.type renvoie la valeur de l'attribut type.

Veuillez noter les points suivants :

  • Les événements peuvent inclure et les inscriptions peuvent utiliser un nombre quelconque d'attributs CloudEvents personnalisés supplémentaires avec des noms distincts (également appelés attributs d'extension). Toutefois, elles sont représentées sous forme de types String dans les expressions CEL, quel que soit leur format réel. Vous pouvez utiliser une expression CEL pour caster leurs valeurs dans d'autres types.

  • Vous ne pouvez pas évaluer les inscriptions en fonction du contenu de la charge utile de l'événement. message.data et message.data_base64 sont des variables réservées et ne peuvent pas être utilisées dans des expressions. Toutefois, le CEL est compatible avec la transformation des données d'événement, ce qui vous permet de modifier le contenu de la charge utile de l'événement (par exemple, pour respecter le contrat d'API d'une destination spécifique).

Les attributs suivants sont accessibles lors de l'évaluation des expressions de condition pour une inscription :

Attribut Type d'attribut Description
message.datacontenttype String Type de contenu de la valeur data
message.dataschema URI Identifie le schéma auquel data adhère.
message.id String Identifie l'événement. Les producteurs doivent s'assurer que source + id est unique pour chaque événement distinct.
message.source URI-reference Identifie le contexte dans lequel un événement s'est produit
message.specversion String Version de la spécification CloudEvents utilisée par l'événement
message.subject String Décrit l'objet de l'événement dans le contexte du producteur d'événement (identifié par source)
message.time Timestamp Code temporel de l'événement. Il peut être défini sur une autre heure (par exemple, l'heure actuelle) par le producteur CloudEvents. Toutefois, tous les producteurs pour le même source doivent être cohérents.
message.type String Décrit le type d'événement lié à l'occurrence d'origine.

Opérateurs et fonctions

Vous pouvez utiliser des opérateurs et des fonctions pour créer des expressions logiques complexes.

Les opérateurs logiques, tels que &&, ||, et !, vous permettent de vérifier plusieurs variables dans une expression conditionnelle. Par exemple, message.time.getFullYear() < 2020 && message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" combine deux instructions et requiert que les deux instructions soient True pour produire un résultat global de True.

Les opérateurs de manipulation de chaînes, tels que x.contains('y'), correspondent aux chaînes ou sous-chaînes que vous définissez, et vous permettent de développer des règles pour faire correspondre les messages sans lister toutes les combinaisons possibles.

Eventarc Advanced est également compatible avec les fonctions d'extension, telles que merge et flatten, qui peuvent être utilisées pour transformer des données et simplifier la modification des événements reçus d'un bus.

Consultez la liste des opérateurs et fonctions CEL prédéfinis et des macros CEL prédéfinies.

Opérateurs logiques

Le tableau suivant décrit les opérateurs logiques compatibles avec Eventarc Advanced.

Expression Description
x == "my_string" Renvoie True si x est égal à l'argument littéral de chaîne constante.
x == R"my_string\n" Renvoie True si x est égal au littéral de chaîne brute donné qui n'interprète pas les séquences d'échappement. Les littéraux de chaîne brute sont pratiques pour exprimer des chaînes qui doivent elles-mêmes utiliser des séquences d'échappement, telles que des expressions régulières ou du texte de programme.
x == y Renvoie True si la valeur de x est égale à y.
x != y Renvoie True si la valeur de x n'est pas égale à y.
x && y Renvoie True si x et y sont tous les deux True.
x || y Renvoie True si x, y ou les deux sont True.
!x Renvoie True si la valeur booléenne x est False, ou renvoie False si la valeur booléenne x est True.
m['k'] Si la clé k est présente, renvoie la valeur à la clé k dans le mappage chaîne à chaîne m. Si la clé k n'est pas présente, une erreur est renvoyée, ce qui empêche la règle en cours d'évaluation de correspondre.

Opérateurs de manipulation de chaînes

Le tableau suivant décrit les opérateurs de manipulation de chaînes compatibles avec Eventarc Advanced.

Expression Description
double(x) Convertit le résultat de chaîne de x en type double. La chaîne convertie peut être utilisée pour comparer des nombres à virgule flottante avec des opérateurs arithmétiques standards tels que > et <=. Cela ne fonctionne que pour les valeurs qui peuvent être des nombres à virgule flottante.
int(x) Convertit le résultat de chaîne de x en type int. La chaîne convertie peut être utilisée pour comparer des nombres entiers avec des opérateurs arithmétiques standards tels que > et <=. Cela ne fonctionne que pour les valeurs qui peuvent être des entiers.
x + y Renvoie la chaîne concaténée xy.
x.contains(y) Renvoie True si la chaîne x contient la sous-chaîne y.
x.endsWith(y) Renvoie True si la chaîne x se termine par la sous-chaîne y.
x.join() Renvoie une nouvelle chaîne dans laquelle les éléments d'une liste de chaînes sont concaténés. Accepte un séparateur facultatif qui est placé entre les éléments de la chaîne résultante. Par exemple, l'expression suivante renvoie 'hello world' :

['hello', 'world'].join(' ')
x.lowerAscii() Renvoie une nouvelle chaîne dans laquelle tous les caractères ASCII sont en minuscules.
x.matches(y)

Renvoie True si la chaîne x correspond au modèle RE2 y spécifié.

Le modèle RE2 est compilé à l'aide de l'option RE2::Latin1 qui désactive les fonctionnalités Unicode.
x.replace(y,z) Renvoie une nouvelle chaîne dans laquelle les occurrences de la sous-chaîne y sont remplacées par la sous-chaîne z. Accepte un argument facultatif qui limite le nombre de remplacements à effectuer. Par exemple, l'expression suivante renvoie 'wello hello' :

'hello hello'.replace('he', 'we', 1)
x.split(y) Renvoie une liste de chaînes divisées à partir de l'entrée par le séparateur y. Accepte un argument facultatif qui limite le nombre de sous-chaînes à produire. Par exemple, l'expression suivante renvoie ['hello', 'hello hello'] :

'hello hello hello'.split(' ', 2)
x.startsWith(y) Renvoie True si la chaîne x commence par la sous-chaîne y.
x.upperAscii() Renvoie une nouvelle chaîne dans laquelle tous les caractères ASCII sont en majuscules.

Fonctions d'expression régulière

Le tableau suivant décrit les fonctions d'expression régulière compatibles avec Eventarc Advanced.

Expression Description
re.capture(target,regex)

Utilise regex pour capturer la première valeur de groupe nommée ou non nommée dans la chaîne target et renvoie une chaîne. Par exemple, l'expression suivante renvoie "o" :

re.capture("hello", R"hell(o)")
re.captureN(target,regex) Utilise regex pour capturer le nom et la chaîne du groupe (pour les groupes nommés), ainsi que l'index et la chaîne du groupe (pour les groupes sans nom) à partir de la chaîne target, et renvoie une carte de paires clé/valeur. Par exemple, l'expression suivante renvoie {"1": "user", "Username": "testuser", "Domain": "testdomain"} :

re.captureN("The user testuser belongs to testdomain", R"The (user|domain) (?P.*) belongs to (?P.*)")

re.extract(target,regex,rewrite) Utilise regex pour extraire les valeurs de groupe correspondantes de la chaîne target et renvoie une chaîne des valeurs extraites, mise en forme en fonction de l'argument rewrite. Par exemple, l'expression suivante renvoie "example.com" :

re.extract("alex@example.com", "(^.*@)(.*)", "\\2")
x.matches(regex)

Renvoie True si la chaîne x correspond au modèle RE2 regex spécifié.

Le modèle RE2 est compilé à l'aide de l'option RE2::Latin1 qui désactive les fonctionnalités Unicode.

Les expressions régulières suivent la syntaxe RE2. Notez que le R précédant les expressions régulières indique une chaîne brute qui ne nécessite pas d'échappement.

Fonctions d'extension

Eventarc Advanced est compatible avec certaines fonctions d'extension qui peuvent être utilisées pour transformer les données d'événement reçues via un bus. Pour en savoir plus et obtenir des exemples, consultez Transformer les événements reçus.

Étapes suivantes