Usar o Common Expression Language

Common Expression Language (CEL) é uma linguagem de código aberto sem completude de Turing que pode ser usada para avaliar expressões. Cada inscrição no Eventarc Advanced inclui uma expressão condicional escrita em CEL que é usada para avaliar e filtrar mensagens. No Eventarc Advanced, também é possível usar a CEL para fazer o seguinte:

  • Controlar o acesso de publicação aplicando uma expressão condicional CEL a um atributo de contexto de evento

  • Transformar o conteúdo dos dados de eventos escrevendo expressões de transformação usando a CEL

Em geral, uma expressão condicional consiste em uma ou mais instruções que são unidas por operadores lógicos (&&, || ou !). Cada instrução expressa uma regra baseada em atributo que é aplicada aos dados. Geralmente, os operadores são usados para comparar o valor contido em uma variável com um valor literal.

Por exemplo, se o valor de message.type for google.cloud.dataflow.job.v1beta3.statusChanged, a expressão message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" será avaliada como True.

Para ver mais informações, consulte os seguintes tópicos:

Atributos disponíveis

Todos os atributos de contexto de evento podem ser acessados como variáveis por um objeto message predefinido. Essas variáveis são preenchidas com valores com base nos atributos de contexto de evento no tempo de execução. Uma inscrição pode usar uma variável para expressar um determinado atributo. Por exemplo, message.type retorna o valor do type atributo.

Observe o seguinte:

  • Os eventos podem incluir, e as inscrições podem usar, qualquer número de atributos personalizados adicionais do CloudEvents com nomes distintos (também conhecidos como atributos de extensão). No entanto, eles são representados como tipos String em expressões CEL, independentemente do formato real. É possível usar uma expressão CEL para converter os valores em outros tipos.

  • Não é possível avaliar inscrições ou controlar o acesso de publicação com base no conteúdo do payload do evento. message.data e message.data_base64 são variáveis reservadas e não podem ser usadas em expressões. No entanto, a CEL é compatível ao transformar dados de eventos o que permite modificar o conteúdo do payload do evento (por exemplo, para atender ao contrato de API de um destino específico).

Os atributos a seguir podem ser acessados ao avaliar expressões condicionais:

Atributo Tipo de atributo Descrição
message.datacontenttype String O tipo de conteúdo do valor data
message.dataschema URI Identifica o esquema a que os data aderem
message.id String Identifica o evento. Os produtores precisam garantir que source + id seja exclusivo para cada evento distinto
message.source URI-reference Identifica o contexto em que um evento aconteceu
message.specversion String A versão da especificação do CloudEvents que o evento usa
message.subject String Descreve o assunto do evento no contexto do produtor de eventos (identificado por source)
message.time Timestamp Timestamp de quando a ocorrência aconteceu. Pode ser definido para outro horário (como o atual) pelo produtor do CloudEvents. No entanto, todos os produtores da mesma source precisam ser consistentes
message.type String Descreve o tipo de evento relacionado à ocorrência de origem. Consulte os tipos de eventos do Google com suporte no Eventarc

Operadores e funções

É possível usar operadores e funções para criar expressões lógicas complexas.

Os operadores lógicos, como &&, || e !, permitem verificar várias variáveis em uma expressão condicional. Por exemplo, message.time.getFullYear() < 2020 && message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" une duas instruções e exige que ambas sejam True para produzir um resultado geral de True.

Os operadores de manipulação de strings, como x.contains('y'), correspondem a strings ou substrings definidas e permitem desenvolver regras para corresponder a mensagens sem listar todas as combinações possíveis.

O Eventarc Advanced também oferece suporte a funções de extensão, como merge e flatten, que podem ser usadas para transformar dados e simplificar a modificação de eventos recebidos de um barramento.

Consulte a lista de operadores e funções predefinidos da CEL e macros predefinidas da CEL.

Operadores lógicos

A tabela a seguir descreve os operadores lógicos com suporte no Eventarc Advanced.

Expressão Descrição
x == "my_string" Retorna True se x for igual ao argumento literal de string constante.
x == R"my_string\n" Retorna True se x for igual à literal de string bruta fornecida que não interpreta sequências de escape. As literais de string bruta são convenientes para expressar strings que precisam usar sequências de escape, como expressões regulares ou texto de programa.
x == y Retorna True se x for igual a y.
x != y Retorna True se x não for igual a y.
x && y Retorna True se x e y forem True.
x || y Retorna True se x, y ou ambos forem True.
!x Retorna True se o valor booleano x for False, ou retorna False se o valor booleano x for True.
m['k'] Se a chave k estiver presente, retorna o valor na chave k no mapa string a string m. Se a chave k não estiver presente, retorna um erro que faz com que a regra em avaliação não corresponda.

Operadores de manipulação de strings

A tabela a seguir descreve os operadores de manipulação de strings com suporte no Eventarc Advanced.

Expressão Descrição
double(x) Converte o resultado da string de x em um tipo double. O valor convertido pode ser usado para comparar números de usar pontos flutuantes com operadores aritméticos padrão, como > e <=. Isso funciona apenas para valores que podem usar pontos flutuantes.
int(x) Converte o resultado da string de x em um tipo int. O valor convertido pode ser usado para comparar números inteiros com operadores aritméticos padrão, como > e <=. Isso funciona apenas para valores que podem ser números inteiros.
x + y Retorna a string concatenada xy.
x.contains(y) Retorna True se a string x contiver a substring y.
x.endsWith(y) Retorna True se a string x terminar com a substring y.
x.join() Retorna uma nova string em que os elementos de uma lista de strings são concatenados. Aceita um separador opcional que é colocado entre os elementos na string resultante. Por exemplo, a expressão a seguir retorna 'hello world':

['hello', 'world'].join(' ')
x.lowerAscii() Retorna uma nova string em que todos os caracteres ASCII estão em letras minúsculas.
x.matches(y)

Retorna True se a string x corresponder ao padrão RE2 especificado y.

O padrão RE2 é compilado usando a opção RE2::Latin1 que desativa os recursos Unicode.
x.replace(y,z) Retorna uma nova string em que as ocorrências da substring y são substituídas pela substring z. Aceita um argumento opcional que limita o número de substituições a serem feitas. Por exemplo, a expressão a seguir retorna 'wello hello':

'hello hello'.replace('he', 'we', 1)
x.split(y) Retorna uma lista de strings divididas da entrada pelo separador y. Aceita um argumento opcional que limita o número de substrings a serem produzidas. Por exemplo, a expressão a seguir retorna ['hello', 'hello hello']:

'hello hello hello'.split(' ', 2)
x.startsWith(y) Retorna True se a string x começar com a substring y.
x.upperAscii() Retorna uma nova string em que todos os caracteres ASCII estão em letras maiúsculas.

Funções de expressão regular

A tabela a seguir descreve as funções de expressão regular com suporte no Eventarc Advanced.

Expressão Descrição
re.capture(target,regex)

Usa regex para capturar o primeiro valor de grupo não nomeado ou nomeado em target e retorna uma string. Por exemplo, a expressão a seguir retorna "o":

re.capture("hello", R"hell(o)")
re.captureN(target,regex) Usa regex para capturar o nome e a string do grupo (para grupos nomeados) e o índice e a string do grupo (para grupos não nomeados) da target string e retorna um mapa de pares de chave e valor. Por exemplo, a expressão a seguir retorna {"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) Usa regex para extrair valores de grupo correspondentes da target string e retorna uma string dos valores extraídos formatada com base no rewrite argumento. Por exemplo, a expressão a seguir retorna "example.com":

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

Retorna True se a string x corresponder ao padrão regex RE2 especificado .

O padrão RE2 é compilado usando a opção RE2::Latin1 que desativa os recursos Unicode.

As expressões regulares seguem a sintaxe RE2. Observe que o R que precede as expressões regulares indica uma string bruta que não exige escape.

Funções da extensão

O Eventarc Advanced oferece suporte a determinadas funções de extensão que podem ser usadas para transformar os dados de eventos recebidos por um barramento. Para mais informações e exemplos, consulte Transformar eventos recebidos.

A seguir