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. Dans Eventarc Advanced, vous pouvez également utiliser le CEL pour effectuer les opérations suivantes :

  • Contrôler l'accès à la publication en appliquant une expression de condition CEL à un attribut de contexte d'événement

  • 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 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" est évaluée sur True.

Pour en savoir plus, consultez les ressources suivantes :

Attributs disponibles

Tous les attributs de contexte d'événement sont 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'type attribut.

Veuillez noter les points suivants :

  • CloudEvents Toutefois, ils sont représentés en tant que types String dans les expressions CEL, quel que soit leur format réel. Vous pouvez utiliser une expression CEL pour convertir leurs valeurs en d'autres types.

  • Vous ne pouvez pas évaluer les inscriptions ni contrôler l'accès à la publication 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 les expressions. Toutefois, le CEL est compatible lors de 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 :

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énements (identifié par source)
message.time Timestamp Timestamp du moment où l'occurrence s'est produite. Peut être défini sur une autre heure (par exemple, l'heure actuelle) par le producteur CloudEvents. Toutefois, tous les producteurs de la même source doivent être cohérents.
message.type String Décrit le type d'événement lié à l'occurrence d'origine. Consultez les types d'événements Google compatibles avec Eventarc.

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" joint deux instructions et nécessite que les deux soient True pour produire un résultat global de True.

Les opérateurs de manipulation de chaînes, tels que x.contains('y'), mettent en correspondance les chaînes ou les sous-chaînes que vous définissez, et vous permettent de développer des règles pour mettre en correspondance les messages sans répertorier 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 prédéfinis du CEL et des macros prédéfinies du 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 x est égal à y.
x != y Renvoie True si x n'est pas égal à y.
x && y Renvoie True si x et y sont 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, renvoie une erreur 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 valeur 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 valeur 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 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 spécifié y.

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 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, 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), ainsi que l'index et la chaîne du groupe (pour les groupes non nommés) à partir de la chaîne target, puis renvoie un mappage 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 target chaîne, puis renvoie une chaîne des valeurs extraites mises 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 spécifié regex.

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 Transformer les événements reçus.

Étape suivante