> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md).
# Gatilhos
Defina uma condição guardada que inicia uma regra do Kilo imediatamente ou após um atraso para um ou vários dispositivos.
A **gatilho** é uma condição guardada que pode iniciar uma regra. Indica ao Kilo que dados do dispositivo deve vigiar, que comparação deve tornar-se verdadeira e qual o dispositivo selecionado que fez com que a condição fosse satisfeita.
Um gatilho não é apenas um temporizador e não é um grupo de dispositivos reutilizável. A temporização e a seleção de dispositivos são duas partes independentes do mesmo gatilho:
* **Temporização** decide se o Kilo inicia a regra imediatamente ou espera que a condição permaneça verdadeira.
* **Dispositivos** decidem se a condição é avaliada para um dispositivo ou separadamente para vários dispositivos.
Por exemplo, um gatilho pode monitorizar a `door_open` métrica em 50 portas de câmaras frigoríficas. Pode iniciar uma regra partilhada assim que qualquer porta se abre, ou apenas depois de essa porta específica ter permanecido aberta durante 20 minutos. Cada porta mantém o seu próprio estado e contagem decrescente.
## Quando usar um gatilho
Cada **Evento de início** tem duas fontes de início:
| Comportamento necessário | Fonte de início | Definição adicional |
| ------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------ |
| Executar sempre que um sensor reportar | **Leitura do sensor** | Selecione um dispositivo e um sensor no Evento de Início. |
| Executar quando uma condição se tornar verdadeira | **Condição do gatilho** | Defina o gatilho para **Imediatamente**. |
| Ignorar condições de curta duração | **Condição do gatilho** | Defina o gatilho para **Apenas se durar** e introduza uma duração. |
| Aplicar a mesma condição e resposta a vários dispositivos | **Condição do gatilho** | Selecione esses dispositivos dentro do gatilho. |
| Permitir que qualquer uma das fontes seja executada apenas durante horários definidos | Manter a fonte escolhida | Ativar **Ativar agendamento** no Evento de Início. |
Use **Leitura do sensor** quando a regra precisar de todos os eventos de sensor normalizados e do respetivo `vars.value`. Use **Condição do gatilho** quando o Kilo tiver de decidir se uma condição guardada foi satisfeita antes de a regra começar.
## Como funciona um gatilho
O gatilho e a regra têm responsabilidades separadas:
1. O gatilho monitoriza métricas normalizadas e avalia a sua condição.
2. A sua temporização e o comportamento de limpeza determinam quando a condição fica ativa e regressa ao normal.
3. Quando o gatilho se torna ativo, identifica o dispositivo monitorizado e sinaliza todas as regras implementadas que usam esse gatilho.
4. A regra executa a resposta operacional, como gerar um alarme, enriquecer dados ou enviar um comando.
Guardar um gatilho, portanto, não executa uma ação por si só. Tem de o ligar a uma regra e, depois, construir e implementar essa regra.
## De um gatilho para uma regra em execução
Um gatilho é uma **fonte de início**guardada, e não um nó que arrasta para a área de desenho da regra. Criar o gatilho e associá-lo a uma regra acontecem em dois separadores diferentes:
1. Abra **Motor de Regras → Gatilhos**, clique em **Adicionar gatilho**, configure a condição, a temporização e os dispositivos, e clique em **Criar gatilho**.
2. Volte ao **Regras** separador. O **Adicionar regra** botão está disponível aí, não no separador Gatilhos.
3. Clique em **Adicionar regra**, ou edite uma regra existente que deve responder ao gatilho.
4. Encontre o **Evento de início** já colocado na área de desenho. Selecione-o e clique no lápis por baixo do nó para abrir as suas propriedades.
5. Defina **Fonte de início** para **Condição do gatilho**, e depois escolha o gatilho que guardou.
6. Clique em **Guardar** na parte inferior do painel Evento de Início. Isto aplica a seleção ao diagrama.
7. Adicione os nós de alarme, comando, enriquecimento ou outros que definem a resposta. Depois clique em **Guardar** no editor de regras.
8. Clique em **Compilar** e implemente o artefacto resultante. Só uma regra implementada pode responder quando o gatilho se torna ativo.
Criar um gatilho não cria uma regra, não adiciona um nó à área de desenho nem seleciona o gatilho automaticamente. O gatilho decide **quando e para que dispositivo** uma regra inicia; os nós após o Evento de Início decidem **o que a regra faz**.
## Criar um gatilho
1. Abra **Motor de Regras → Gatilhos**.
2. Clique em **Adicionar gatilho**.
3. Introduza um **Nome** que descreve a situação, como `Porta da câmara frigorífica deixada aberta`.
4. Sob **O que deve iniciar a regra?**, clique em **Adicionar chave normalizada** e escolha a métrica a avaliar.
5. Escolha um **É** operador e introduza a comparação **Valor**.
6. Sob **Quando deve iniciar?**, escolha **Imediatamente** ou **Apenas se durar**.
7. Configurar **Comportamento de limpeza** se o regresso ao normal precisar da sua própria condição ou atraso.
8. Sob **Dispositivos**, selecione o dispositivo ou dispositivos cujos dados o gatilho usará.
9. Rever **Como este gatilho será executado**, e depois clique em **Criar gatilho**.
O formulário suporta até 10 chaves normalizadas entre as condições de início e de limpeza opcionais, até 500 dispositivos selecionados e uma duração de 10 segundos a 30 dias.
Para o comportamento completo da temporização, consulte [Temporização do gatilho](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers/trigger-timing.md). Para seleção de dispositivos, leituras partilhadas e avaliação por dispositivo, consulte [Um Gatilho para Vários Dispositivos](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers/multiple-devices.md).
## Construir a condição
Para cada chave normalizada, escolha a comparação que o Kilo deve fazer:
* As métricas numéricas oferecem **igual a**, **é maior que**, e **é menor que**.
* As métricas de texto e booleanas oferecem **igual a**.
* **Adicionar verificação em ‹métrica›** adiciona outra comparação para a mesma métrica.
* **Adicionar chave normalizada** inclui outra métrica na condição.
Use **E** quando todas as verificações têm de ser verdadeiras e **OU** quando qualquer verificação pode ser verdadeira. Um segundo controlo E/OU combina diferentes chaves normalizadas. Estes controlos combinam leituras de um dispositivo monitorizado; não combinam os estados de diferentes dispositivos monitorizados.
## Onde os gatilhos podem ser usados
No editor de regras atual, o Evento de Início é o único local onde seleciona um gatilho guardado. Os gatilhos não estão disponíveis em gateways, Definir Alarme, Executar Comando, Enriquecimento ou outros nós a jusante.
Um gatilho guardado pode ser selecionado por várias regras. Quando se torna ativo, todas as regras implementadas que o usam podem executar-se. Cada regra individual continua a ter exatamente um Evento de Início e uma fonte de início.
Um Evento de Início usa **Leitura do sensor** ou **Condição do gatilho**, nunca ambos. **Ativar agendamento** é uma restrição opcional na fonte selecionada e não outra fonte de início.
O seletor de gatilhos carrega atualmente apenas a sua primeira página. Se o gatilho necessário não estiver listado, ainda não pode ser selecionado a partir desse campo.
## Dados disponíveis para a regra
Uma regra iniciada por gatilho recebe informação sobre o sinal da condição e o dispositivo monitorizado:
| Variável | Valor |
| ------------------- | -------------------------------------------------------- |
| `vars.device_name` | Nome do dispositivo monitorizado que satisfez a condição |
| `vars.subject_kind` | Tipo de recurso monitorizado; atualmente `dispositivo` |
| `vars.subject_id` | ID do dispositivo monitorizado |
| `vars.sensor_id` | ID do sensor associado à execução e a qualquer alarme |
| `vars.detector_id` | ID do gatilho |
| `vars.timestamp` | carimbo de data/hora Unix do sinal do gatilho |
`vars.value` não está disponível porque o sinal representa a transição da condição do gatilho e não um único evento de sensor normalizado. Atualize as expressões que requerem `vars.value` antes de alterar uma regra existente de **Leitura do sensor** para **Condição do gatilho**.
Para identificar o dispositivo afetado num alarme, inclua `vars.device_name` na sua **Mensagem de Motivação**:
```cel
"Porta deixada aberta: " + vars.device_name
```
O nome do dispositivo não é inserido automaticamente.
## Editar ou eliminar um gatilho
Editar uma condição pode reiniciar contagens decrescentes ativas. O Kilo apresenta um aviso antes de guardar uma alteração que repõe o estado do gatilho.
Eliminar um gatilho não pode ser desfeito. Isso interrompe a monitorização futura e impede que regras ligadas iniciem a partir dele. Reveja as regras que usam o gatilho e quaisquer alarmes pendentes antes de o eliminar.
## Resolução de problemas
| Problema | O que verificar |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Está em falta um dispositivo | Confirme que os seus dados recebidos estão mapeados para uma chave normalizada usada pelo gatilho. |
| Um sensor não consegue fornecer uma métrica | Confirme que o sensor tem um mapeamento de origem. Se vários sensores responderem à mesma métrica, selecione o sensor pretendido. |
| O gatilho não será guardado | Verifique a duração e reveja **Como este gatilho será executado** uma métrica em falta ou partilhada de forma ambígua. |
| Uma expressão CEL falha | Remova `vars.value` de um caminho iniciado por gatilho e use as variáveis listadas acima. |
| Um alarme não identifica o dispositivo | Adicione `vars.device_name` à mensagem do alarme. |
## Ver também
* [Criar Regras](/kilo-docs-pt/kilo-iot-server/rules-engine/creating-rules.md) — escolha a fonte correta do Evento de Início
* [Temporização do gatilho](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers/trigger-timing.md) — imediato, duração, limpeza e agendamentos
* [Um Gatilho para Vários Dispositivos](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers/multiple-devices.md) — seleção de participantes e leituras partilhadas
* [Referência CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) — escreva expressões para cada contexto de início
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
