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 nomeA 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
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
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.valuenã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 avars.valuefalhará 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:
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.
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:
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
==
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
&&
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
+
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
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
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
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.
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
varsatual. 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 originalvarse 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