For the complete documentation index, see llms.txt. This page is also available as Markdown.

Referência CEL

Referência de sintaxe CEL para regras do Kilo IoT — Common Expression Language usada em gateways, scripts e alarmes.

O Motor de Regras usa CEL (Common Expression Language) para expressões dentro do editor visual de workflows — condições de gateway, cálculos de Tarefas de Script, mensagens de alarme, pesquisas de enriquecimento e definições de entrada/saída. O CEL é uma linguagem de expressões rápida e segura, originalmente criada pelo Google para avaliar condições em políticas de segurança e sistemas de infraestrutura. A especificação completa da linguagem está disponível no GitHub.

O CEL não é uma linguagem de programação de uso geral. Ele avalia expressões e devolve resultados. Não pode aceder ao sistema de ficheiros, fazer chamadas de rede, criar ciclos nem modificar o estado externo. Isto torna-o seguro para executar expressões definidas pelo utilizador sem risco para a plataforma ou para outras regras.

A maioria das regras do Kilo usa apenas algumas expressões curtas. A estrutura do workflow continua visual e baseada em BPMN; o CEL é a camada de precisão que torna esses workflows úteis em cenários reais de produção.


Dados disponíveis

Cada expressão no Motor de Regras tem acesso às variáveis do processo através do vars objeto. Os dados disponíveis dependem de onde na regra a expressão é executada.

Os campos em vars podem ser acedidos com notação de ponto ou notação de colchetes:

vars.temperature        // notação de ponto — funciona para identificadores simples
vars["sensor_id"]       // notação de colchetes — funciona para qualquer nome
vars["my-sensor"]       // notação de colchetes obrigatória — hífen no nome

A notação de ponto é conveniente para a maioria dos nomes de campos. A notação de colchetes é obrigatória quando um nome de campo contém hífens, espaços ou outros caracteres especiais, ou quando o nome do campo é calculado dinamicamente a partir de outra expressão.

Disponível após o Evento de Início

O que o Evento de Início fornece depende da sua origem de início, por isso verifique que tipo de regra está a escrever antes de procurar uma variável.

Origem de início: leitura do sensor

Variável
Tipo
Descrição

vars.value

Varia consoante o sensor

A leitura do sensor que disparou a regra. Pode ser um número (temperatura, humidade), string (estado da porta) ou booleano (movimento detetado).

vars.sensor_id

string

O identificador exclusivo do sensor que disparou a regra.

vars.timestamp

timestamp

O momento em que a leitura do sensor foi registada.

Origem de início: condição de gatilho

Variável
Tipo
Descrição

vars.device_name

string

O nome do dispositivo que satisfez a condição. Numa gatilho que monitoriza vários dispositivos, isto identifica o que disparou.

vars.subject_kind

string

O tipo de recurso monitorizado. Atualmente isto é dispositivo.

vars.subject_id

string

O identificador do dispositivo monitorizado que satisfez a condição.

vars.sensor_id

string

O identificador do sensor usado para associar a execução e qualquer alarme ao dispositivo monitorizado.

vars.detector_id

string

O identificador do gatilho que iniciou a regra.

vars.timestamp

int

O tempo do sinal de gatilho em segundos Unix.

vars.value não existe numa regra iniciada por gatilho. Um gatilho reporta uma transição de condição em vez de entregar à regra um evento de sensor normalizado. Isto é verdade tanto para gatilhos imediatos como para gatilhos de duração. Uma expressão que se refira a vars.value falhará em todos os sinais de gatilho — verifique isto primeiro ao converter uma regra existente de Leitura do sensor.

Disponível após Tarefas de Script

Se uma Tarefa de Script devolver um mapa, cada chave é mesclada em vars. Por exemplo, após uma Tarefa de Script com a expressão {"level": "crítico", "delta": 15.2}, os nós a jusante podem aceder a vars.level e vars.delta.

As saídas de Tarefa de Script, Gateway, Definir Alarme, Enriquecimento e Evento de Início também podem publicar valores nomeados em vars depois de esse nó ser executado.

Disponível após Enriquecimento

Depois de um nó de Enriquecimento armazenar dados sob um nome de variável (por exemplo, outdoor_temp), os dados enriquecidos ficam acessíveis como um objeto aninhado:

Variável
Tipo
Descrição

vars.outdoor_temp.value

Varia

A leitura mais recente do sensor enriquecido.

vars.outdoor_temp.sensor_id

string

O identificador do sensor enriquecido.

vars.outdoor_temp.type

string

O tipo de dados do sensor enriquecido.

vars.outdoor_temp.timestamp_ms

int

Carimbo de data/hora da leitura em milissegundos.

Variáveis personalizadas

As expressões de entrada e saída em Eventos de Início, Gateways Exclusivos, Tarefas de Script, nós Definir Alarme e nós de Enriquecimento permitem-lhe nomear um valor calculado. Escolha entre elas conforme a distância que o valor precisa de percorrer:

  • Saídas adicionam o nome ao contexto do workflow. Fica acessível como vars.<name> em qualquer nó executado depois.

  • Entradas ficam no nó em que as definiu. São calculadas antes de esse nó ser executado e as suas próprias expressões podem usá-las — as entradas de um gateway ficam disponíveis para as condições de fluxo desse gateway — mas os nós posteriores não as podem ler.

Se um valor calculado num nó for necessário mais adiante na regra, torne-o uma saída. Veja Referência de Nós para um exemplo.


Sistema de tipos

O CEL suporta os seguintes tipos. Cada valor numa expressão é resolvido para um destes.

Tipo
Descrição
Exemplo

bool

Booleano verdadeiro ou falso

verdadeiro, vars.value > 30

int

Inteiro com sinal

42, -7

uint

Inteiro sem sinal

42u

double

Número de ponto flutuante

30.5, -0.7

string

Texto

"crítico", "Alerta de temperatura"

bytes

Sequência de bytes

b"\x00\xff"

list

Coleção ordenada

[1, 2, 3], ["a", "b"]

map

Pares chave-valor

{"level": "alto", "count": 5}

null_type

Valor nulo

null

timestamp

Um momento no tempo

vars.timestamp

duration

Um intervalo de tempo

duration("5m")

Conversões de tipos

Use funções de conversão incorporadas para converter entre tipos:

Função
Descrição
Exemplo

int()

Converter para inteiro

int(vars.value)

uint()

Converter para inteiro sem sinal

uint(42)

double()

Converter para double

double(vars.value)

string()

Converter para string

string(vars.value)

type()

Devolve o tipo de um valor

type(vars.value)

A conversão para string é particularmente importante quando se constroem mensagens de motivação de alarme, uma vez que o CEL exige conversão explícita de números para strings para concatenar.


Operadores

Operadores de comparação

Operador
Significado
Exemplo

==

Igual a

vars.value == 0

!=

Diferente de

vars.status != "offline"

>

Maior que

vars.value > 30.0

>=

Maior ou igual a

vars.value >= 100

<

Menor que

vars.value < 5

<=

Menor ou igual a

vars.value <= 25.0

Operadores lógicos

Operador
Significado
Exemplo

&&

AND lógico

vars.value > 30 && vars.value < 50

||

OR lógico

vars.value < 0 || vars.value > 100

!

NOT lógico

!has(vars.humidity)

Operadores aritméticos

Operador
Significado
Exemplo

+

Adição

vars.value + 10

-

Subtração

vars.value - vars.outdoor_temp.value

*

Multiplicação

vars.value * 1.8 + 32

/

Divisão

vars.value / 100.0

%

Módulo

vars.value % 10

Operador ternário

O operador ternário ? : devolve um de dois valores com base numa condição:

As expressões ternárias podem ser aninhadas para classificação em vários níveis:

Operadores e funções de strings

Operação
Sintaxe
Exemplo

Concatenação

+

"Temp.: " + string(vars.value)

Comprimento

size()

vars.name.size() > 0

Contém

contains()

vars.status.contains("error")

Começa com

startsWith()

vars.zone.startsWith("warehouse")

Termina com

endsWith()

vars.device_id.endsWith("-prod")

Correspondência regex

matches()

vars.device_id.matches("^WH-[0-9]+$")

Funções de coleção

Função
Descrição
Exemplo

x na lista

Verificação de pertença

vars.zone in ["A", "B", "C"]

chave no mapa

A chave existe no mapa

"humidity" in vars

list.exists(x, expr)

Verdadeiro se qualquer elemento satisfizer a expressão

[10, 25, 40].exists(t, t > 30)

list.all(x, expr)

Verdadeiro se todos os elementos satisfizerem a expressão

[10, 25, 40].all(t, t > 0)

list.filter(x, expr)

Devolve os elementos que satisfazem a expressão

[10, 25, 40].filter(t, t > 20) → [25, 40]

list.map(x, expr)

Transforma cada elemento

[1, 2, 3].map(x, x * 10) → [10, 20, 30]

list.exists_one(x, expr)

Verdadeiro se exatamente um elemento satisfizer

[10, 25, 40].exists_one(t, t > 30) → verdadeiro

Variáveis intermédias com cel.bind

Use cel.bind() para definir uma variável temporária dentro de uma expressão, evitando computação redundante:

O primeiro argumento nomeia a variável, o segundo calcula o seu valor e o terceiro é a expressão que a usa.

Verificação de existência

Função
Descrição
Exemplo

has()

Devolve verdadeiro se o campo existir

has(vars.humidity)

Use has() antes de aceder a uma variável que pode não existir. Depois de um nó de Enriquecimento com um Evento de Erro de Fronteira, por exemplo, os dados enriquecidos só ficam disponíveis se o enriquecimento tiver sido bem-sucedido.


Padrões de expressão comuns

Verificação de limiar

O padrão mais simples e mais comum. Usado nas condições de gateway para ramificar com base num único valor.

Devolve verdadeiro se a leitura do sensor exceder 30. Funciona em condições de Gateway Exclusivo para encaminhar o fluxo.

Verificação de intervalo

Testa se uma leitura se encontra dentro de uma faixa aceitável.

Útil para conformidade HVAC, monitorização da cadeia de frio ou qualquer cenário em que os limites superior e inferior sejam importantes.

Verificação de múltiplas condições

Combine verificações em várias variáveis. Este padrão aparece frequentemente após o enriquecimento, quando estão disponíveis dados de mais do que um sensor.

Use sempre has() antes de referenciar variáveis que venham de fontes opcionais (enriquecimento, tarefas de script anteriores com saídas condicionais).

Classificação de severidade (Tarefa de Script)

Devolva um mapa a partir de uma Tarefa de Script para classificar uma leitura em categorias. Cada chave torna-se uma variável de processo separada.

Depois desta Tarefa de Script, vars.level fica disponível para condições de gateway ou mensagens de alarme.

Mensagem de alarme dinâmica (Definir Alarme)

Crie uma string legível que inclua dados do sensor em tempo real. O campo de mensagem de motivação num nó Definir Alarme usa este padrão.

Lembre-se de usar string() para converter valores numéricos — o CEL não converte implicitamente números em strings durante a concatenação.

Verificação de dados enriquecidos (após Enriquecimento)

Referencie um valor obtido por um nó de Enriquecimento. O nome de variável usado na configuração de Enriquecimento torna-se a chave em vars.

Valores derivados calculados (Tarefa de Script)

Calcule novos valores a partir de várias entradas e armazene-os para uso posterior.

Depois desta Tarefa de Script, o gateway pode verificar vars.needs_alarm diretamente, e a mensagem de alarme pode referenciar vars.delta para contexto.

Combinar classificação com valores calculados

Uma única Tarefa de Script pode executar vários cálculos ao mesmo tempo.


Onde o CEL é usado

As expressões CEL aparecem em vários pontos do Motor de Regras. O contexto determina o que a expressão deve devolver.

Local
Tipo de retorno esperado
Objetivo

Evento de Início — Entradas

Qualquer

Crie valores auxiliares locais quando o evento do sensor entra na regra.

Evento de Início — Saídas

Qualquer

Publique valores nomeados no contexto partilhado do workflow.

Tarefa de Script — Script

Qualquer (mapa preferido)

Transforme ou classifique dados. As chaves do mapa são mescladas nas variáveis de processo.

Tarefa de Script — Entradas

Qualquer

Crie valores auxiliares locais antes de o script ser executado.

Tarefa de Script — Saídas

Qualquer

Publique valores nomeados adicionais depois de a tarefa ser executada.

Gateway Exclusivo — Condição

bool

Encaminhe a execução. Deve devolver verdadeiro ou falso.

Gateway Exclusivo — Entradas

Qualquer

Prepare valores locais usados pelas condições de ramificação.

Gateway Exclusivo — Saídas

Qualquer

Publique valores depois da decisão de encaminhamento.

Definir Alarme — Mensagem de motivação

string

Descreva por que o alarme foi disparado. Mostrado aos intervenientes.

Definir Alarme — Entradas

Qualquer

Prepare valores antes de a ação de alarme ser executada.

Definir Alarme — Saídas

Qualquer

Publique valores depois de o nó de alarme ser executado.

Enriquecimento — ID do sensor

string

Identifique de que sensor obter dados.

Enriquecimento — Entradas

Qualquer

Prepare valores antes de a consulta ser executada.

Enriquecimento — Saídas

Qualquer

Publique valores depois de o resultado do enriquecimento estar disponível.

Âmbito de Entradas e Saídas

As Entradas e Saídas num nó servem objetivos diferentes e têm visibilidades diferentes:

  • Entradas criar local variáveis locais com âmbito apenas para o nó atual. Não modificam o contexto partilhado do workflow. As expressões de entrada são avaliadas em relação ao estado vars atual. Use-as para preparar valores auxiliares ou pré-calcular resultados intermédios antes de a lógica principal do nó ser executada.

  • Saídas escrever valores no partilhado contexto do workflow (vars). As expressões de saída são avaliadas no escopo local do nó — que inclui tanto o original vars e quaisquer variáveis locais definidas pela entrada. Os valores publicados pelas Saídas persistem e são acessíveis a todos os nós subsequentes.

Implicação prática: Se definir uma entrada chamada threshold num Gateway Exclusivo, os nós subsequentes não conseguem ver vars.threshold — ele existe apenas durante a avaliação da condição desse gateway. Para tornar um valor calculado disponível a jusante, defina-o como uma Saída em vez disso.


Segurança e sandboxing

O CEL é isolado por design. As expressões são executadas num ambiente restrito sem acesso a:

  • O sistema de ficheiros

  • Recursos de rede

  • Relógios do sistema (exceto através das variáveis de carimbo de data/hora fornecidas)

  • Serviços externos

  • Estado mutável fora da própria avaliação da expressão

Uma expressão não pode criar ciclos infinitos, alocar memória ilimitada ou afetar outras regras. Se uma expressão falhar (erro de tipo, divisão por zero, referência a uma variável em falta sem has() proteção), o nó que a contém lança um erro. Anexe um Boundary Error Event para tratar estas falhas de forma elegante.


Funções da plataforma

Além da biblioteca CEL padrão, o Rules Engine fornece duas funções específicas da plataforma.

error(message)

Recebe um argumento de string e produz sempre um valor de erro. Quando uma expressão de Script Task é avaliada como erro, o motor verifica se existe um Boundary Error Event anexado. Se existir, a execução segue pelo caminho de erro. Se não, o erro interrompe a regra.

Use error() para falha condicional deliberada — situações em que uma condição específica dos dados deve acionar o caminho de tratamento de erro em vez de continuar a execução normal.

Neste exemplo, temperaturas acima de 200 falham deliberadamente a Script Task. Se um Boundary Error Event estiver anexado, o caminho de erro é executado (talvez acionando um alarme de emergência). Abaixo de 200, a Script Task produz {"status": "ok"} como normal.

random()

Devolve um número de vírgula flutuante pseudoaleatório no intervalo [0.0, 1.0). Útil para amostragem probabilística, encaminhamento baseado em percentagens ou geração de identificadores aleatórios.


Dicas práticas

Mantenha as expressões focadas. Uma única expressão deve fazer apenas uma coisa. Se precisar classificar uma leitura, calcular um delta e construir uma mensagem, use várias Script Tasks em vez de uma expressão complexa. Isso torna a regra mais fácil de ler, depurar e manter.

Dê prioridade à estrutura visual. Use o canvas para mostrar o workflow e depois use o CEL nos campos relevantes. Um diagrama BPMN legível com algumas expressões claras é mais fácil de auditar do que uma regra que esconde lógica demais dentro de uma única expressão gigante.

Use has() antes dos campos opcionais. Qualquer variável que venha de enriquecimento, tarefas de script condicionais ou entradas opcionais pode não existir. Aceda-lhe sem has() e a expressão lança um erro.

Converta os tipos explicitamente. O CEL não realiza conversão implícita de tipos. Ao construir mensagens de alarme, converta números com string(). Ao realizar operações aritméticas, certifique-se de que ambos os operandos são do mesmo tipo numérico — misturar int e double pode produzir resultados inesperados.

Use mapas para saídas com vários valores. Devolver um mapa a partir de uma Script Task é a forma padrão de disponibilizar vários valores calculados a jusante. Cada chave torna-se uma variável de processo independente.

Teste as expressões contra casos extremos. Considere o que acontece quando um sensor reporta zero, um valor negativo ou um número inesperadamente grande. As condições do gateway devem lidar com toda a gama de entradas possíveis sem encaminhar para um ramo não pretendido.

Nomeie as variáveis de forma descritiva. Ao definir nomes de variáveis de Enrichment ou chaves de saída da Script Task, use nomes que descrevam os dados — outdoor_temp, humidity_reading, severity_level — e não x, val2, ou tmp. Os seus colegas irão lê-los ao rever ou modificar a regra.

Última atualização