A Common Expression Language (CEL) é uma
linguagem de código aberto sem completude de Turing que implementa semântica comum para
avaliação de expressões. As extensões de serviço usam um subconjunto de condições da CEL para tomar decisões de avaliação em cadeia com base nos dados de atributos. Em
geral, uma expressão condicional consiste em uma ou mais instruções unidas por operadores lógicos (&&, || ou !).
Atributos
Para qualquer solicitação de conexão, o proxy extrai atributos, que são um conjunto de informações contextuais. Os atributos têm um tipo fixo (como string ou int) e podem estar ausentes ou presentes, dependendo do contexto.
Os atributos são expostos ao tempo de execução da CEL durante o processamento da condição de correspondência.
Não é possível enviar atributos para um serviço de extensão.
Atributos de solicitação
Os seguintes atributos podem ser extraídos das solicitações:
| Atributo | Tipo de atributo | Descrição |
|---|---|---|
request.headers |
map{string,string} | Um mapa com cada string dos cabeçalhos de solicitação HTTP. Se um cabeçalho contiver vários valores, o valor nesse mapa será uma string separada por vírgula de todos os valores do cabeçalho. As chaves deste mapa estão em minúsculas. |
request.method |
string | O método de solicitação HTTP, como GET ou POST. |
request.host |
string | Equivalente de conveniência a request.headers['host'].
|
request.path |
string | O caminho do URL HTTP solicitado. |
request.query |
string | A consulta de URL de HTTP no formato
Nenhuma decodificação é executada. |
request.scheme |
string | O esquema de URL HTTP, como HTTP ou HTTPS. Os valores deste atributo estão em minúsculas. |
request.backend_service_name |
string | O serviço de back-end para onde a solicitação é encaminhada. Não aplicável a extensões de borda. |
request.backend_service_project_number |
int | Ao usar a VPC compartilhada, o número do projeto do serviço de back-end para onde a solicitação é encaminhada. Não aplicável a extensões de borda. |
Atributos de conexão
Os seguintes atributos podem ser extraídos das conexões:
| Atributo | Tipo de atributo | Descrição |
|---|---|---|
source.ip |
string | O endereço IP de origem da solicitação. |
source.port |
int | A porta de conexão do cliente downstream. |
connection.sni |
string | O nome do servidor solicitado da conexão TLS de downstream. |
connection.tls_version |
string | A versão TLS da conexão TLS de downstream. Valores válidos:
TLSv1, TLSv1.1, TLSv1.2 e
TLSv1.3.
|
connection.sha256_peer_certificate_digest |
string | O hash SHA256 codificado em hexadecimal do certificado de mesmo nível na conexão TLS de downstream, se houver. |
Operadores
As extensões de serviço são compatíveis com vários operadores que podem ser usados
para criar condições de correspondência complexas com base em instruções de expressão simples.
As extensões de serviço são compatíveis com operadores lógicos, como &&, || e !, e operadores de manipulação de strings, como x.contains('y').
Os operadores de manipulação de strings correspondem a strings ou substrings definidas por você. Por exemplo, request.host.endsWith('.example.com') será avaliado como true se a solicitação HTTP tiver sido feita para um domínio que termina com example.com.
Com os operadores lógicos, é possível verificar várias variáveis em uma expressão condicional. Por exemplo, request.method == 'GET' && request.host.matches('.example.com') une duas instruções e exige que ambas sejam true para produzir um resultado geral de true.
Operadores lógicos
A tabela a seguir descreve os operadores lógicos compatíveis com as extensões de serviço.
| Expressão de exemplo | Descrição |
|---|---|
x == "foo" |
Retorna true se x for igual ao argumento literal de string constante. |
x == R"fo'o" |
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 o código precisa usar para caracteres de sequência de escape. |
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, vai retornar o valor na chave k no mapa string a string m. Se a chave k não estiver presente, vai retornar um erro que fará 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 compatíveis com as extensões de serviço.
| Expressão | Descrição |
|---|---|
x.contains(y) |
Retorna true se a string x contiver a
substring y. |
x.startsWith(y) |
Retorna true se a string x começar com a
substring y. |
x.endsWith(y) |
Retorna true se a string x terminar com a
substring y. |
x.matches(y) |
Retorna As extensões de serviço usam a opção RE2::Latin1 ao compilar o padrão RE2, o que desativa os recursos Unicode. As extensões do Edge permitem usar apenas uma expressão regular por expressão CEL. |
x.lower() |
Retorna o valor em minúsculas da string x. |
x.upper() |
Retorna o valor em maiúsculas da string x. |
int(x) |
Converte o resultado da string de x em um tipo int. É possível usar a string convertida para comparação de números inteiros usando operadores aritméticos padrão, como maior que (>) e menor ou igual a (≤). Isso funciona apenas para valores que podem ser números inteiros. |
Exemplos de expressões
Combine todas as solicitações para hospedar example.com com o serviço de back-end bs1 em 123
como destino final:
request.host == "example.com" && request.backend_service_name == "bs1" && request.backend_service_project_number == 123
Combine todas as solicitações do caminho */inventory com um cabeçalho HTTP Hello:
request.path.endsWith("/inventory") && request.headers["Hello"] != ""
Limitações
As limitações a seguir se aplicam a expressões CEL quando especificadas para extensões de serviço:
- Número máximo de expressões por extensão: 1 para extensões de borda e 5 para outras extensões
- Número máximo de caracteres por expressão regular: 100
- Número máximo de caracteres por expressão CEL: 500