Utiliser Common Expression Language

Le Common Expression Language (CEL) 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 permet d'évaluer et de 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 contient 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 s'applique 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

Tous les attributs de contexte d'événement peuvent être accessibles 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 un nombre illimité d'attributs CloudEvents personnalisés supplémentaires avec des noms distincts (également appelés attributs d'extension). Les inscriptions peuvent également les utiliser. Toutefois, ils sont représentés sous la 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 vers 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, 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 conditionnelles 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 est conforme
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 de l'événement (identifié par source).
message.time Timestamp Code temporel de l'occurrence. Il peut être défini sur un autre code temporel (par exemple, l'heure actuelle) par le producteur CloudEvents. Toutefois, tous les producteurs du même source doivent être cohérents.
message.type String Décrit le type d'événement associé à 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 True.

Les opérateurs de manipulation de chaîne, 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 des messages sans lister toutes les combinaisons possibles.

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

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

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 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 entraîne une non-correspondance de la règle en cours d'évaluation.

Opérateurs de manipulation de chaîne

Le tableau suivant décrit les opérateurs de manipulation de chaîne 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 <=. Cette méthode ne fonctionne que pour les valeurs pouvant ê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 entiers avec des opérateurs arithmétiques standards tels que > et <=. Cela ne fonctionne que pour les valeurs pouvant ê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 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 format 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 séparées de l'entrée par le séparateur y. Accepte un argument facultatif qui limite le nombre de sous-chaînes à générer. 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 où 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 sans nom ou nommé dans la chaîne target, puis 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) et l'index et la chaîne du groupe (pour les groupes non nommés) à partir de la chaîne target, puis renvoie une mappe 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 format 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 qui précède 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 la section Transformer les événements reçus.

Étape suivante