Automações
Identificador de Gatilho (Trigger ID)
O escopo do Trigger ID cobre a identificação do gatilho que iniciou uma automação; não substitui o payload do evento nem a identidade do dispositivo. Em plataformas como Home Assistant, um ID textual pode distinguir abertura de porta, horário e webhook dentro da mesma regra. A consequência prática é reduzir automações duplicadas e centralizar decisões. O identificador precisa ser único, estável e documentado, porque renomeações quebram condições, traces e caminhos dependentes.
⚙ Definição Técnica
Identificador de gatilho, ou Trigger ID, é um rótulo lógico atribuído a cada entrada de uma automação para indicar qual gatilho efetivamente produziu a execução. Ele cobre a identificação da origem dentro da definição da regra. Não substitui os dados do evento, o identificador físico do dispositivo, o user_id, o payload MQTT nem o contexto de segurança. O valor costuma ser uma string curta, como porta_aberta, horario_noturno ou webhook_energia, e fica disponível para condições, choose, templates, logs e traces. A implementação deve preservar unicidade, estabilidade semântica e legibilidade. Em plataformas que permitem múltiplos gatilhos na mesma automação, o ID reduz duplicação e organiza caminhos. Em contrapartida, um ID mal escolhido cria acoplamento silencioso: se o rótulo muda e as referências não são atualizadas, o fluxo deixa de corresponder sem alterar os gatilhos físicos.
Tipos comuns de gatilhos
ID por origem de evento
Cada gatilho recebe um rótulo que descreve a fonte: porta_frente, janela_cozinha, sensor_fumaca ou camera_portao. O benefício é permitir uma única automação tratar várias entidades semelhantes e escolher ações específicas. O ID deve representar uma origem lógica estável, não um nome de marketing ou um endereço temporário. Se o sensor for substituído, a automação pode continuar usando porta_frente. Isso reduz impacto de migração. O payload ainda precisa carregar o estado e o contexto. Um erro comum é usar apenas o ID e presumir que a porta está aberta; a execução pode ter vindo de restauração, evento atrasado ou mudança inversa. O fluxo deve validar o estado atual antes de agir quando a consequência é relevante.
ID por tipo de condição operacional
Gatilhos diferentes podem representar o mesmo equipamento em condições distintas, como temperatura_alta, temperatura_normal e sensor_indisponivel. O ID documenta a semântica do evento e facilita choose. Essa abordagem é útil quando o motor oferece gatilhos numéricos, disponibilidade e tempo. A nomenclatura deve evitar ambiguidade. high e low são menos claros que temperatura_acima_limite e temperatura_abaixo_retorno. Limites precisam ficar em helpers ou configuração, não embutidos no nome. Se o valor muda, o ID continua válido. O trace deve registrar valor medido e limiar. O identificador explica a classe do evento, mas não substitui os parâmetros usados para gerá-lo.
ID por canal de acionamento
Uma mesma função pode ser iniciada por botão físico, aplicativo, voz, automação temporal ou webhook. IDs como botao_local, app_usuario, assistente_voz e api_externa permitem aplicar políticas diferentes. Um comando local pode executar imediatamente; um webhook pode exigir validação extra; uma solicitação de voz pode pedir confirmação. O canal precisa ser derivado de um gatilho autenticado. Não confie em um campo fornecido pelo próprio payload para declarar origem. Em webhooks, a identidade vem da assinatura ou credencial. Em eventos de plataforma, use context.user_id ou metadados confiáveis. O ID deve indicar o caminho configurado, não uma alegação externa.
ID por fase de ciclo
Automação de equipamento pode possuir gatilhos inicio, verificacao, timeout e encerramento. O ID ajuda a implementar máquina de estados simples. Por exemplo, uma irrigação inicia por agenda, verifica fluxo após 30 s, encerra por duração e reage a falha de pressão. Cada gatilho entra no mesmo fluxo, que consulta o estado atual e decide. A regra precisa ser idempotente porque os eventos podem chegar fora de ordem. Um timeout antigo não deve desligar um novo ciclo. Inclua run_id, timestamp ou timer associado. O Trigger ID informa a fase pretendida; a validade depende do contexto da execução.
ID por prioridade ou criticidade
Gatilhos de informação, alerta e emergência podem compartilhar uma automação de notificação, com IDs nivel_info, nivel_alerta e nivel_critico. O fluxo escolhe canal, persistência, volume e escalonamento. O ID não deve ser a única fonte da severidade quando o evento vem de sistema externo; valide dados e origem. Em segurança, uma classificação incorreta pode silenciar aviso. A taxonomia precisa ser documentada e limitada. Três ou quatro níveis são mais operáveis que dezenas. Métricas devem contabilizar eventos por ID para detectar fontes ruidosas. A consequência prática é um sistema de resposta coerente sem duplicar regras.
Considerações de Implementação
Renomear o ID sem atualizar referências quebra a lógica
O rótulo é usado por condições, templates, choose, scripts e testes. Algumas plataformas não realizam refatoração automática. A automação continua carregando, mas nenhum caminho corresponde ao valor novo ou antigo. Antes de renomear, pesquise referências no YAML, editor e blueprints. Use controle de versão. Teste cada gatilho e confira trace.trigger.id. Para instalações grandes, adote convenção de nomes: domínio, objeto e evento, como porta_frente_aberta. Evite espaços, acentos e textos traduzíveis quando o valor é usado em código. O nome exibido ao usuário pode ser diferente do identificador interno.
IDs duplicados eliminam a capacidade de distinguir origens
Se dois gatilhos recebem o mesmo ID, isso pode ser intencional para agrupá-los, mas precisa ser declarado. Caso contrário, o fluxo perde informação. Uma condição baseada no ID não saberá qual entidade disparou. O payload ou trigger.entity_id pode ainda diferenciar, porém a lógica fica menos clara. Use IDs únicos por padrão e agrupe somente quando as ações e políticas são realmente iguais. Testes devem incluir todos os gatilhos. Um ID ausente também precisa de fallback explícito. Não trate string vazia como origem válida.
Trigger ID organiza, mas não carrega todos os dados necessários
O identificador normalmente é uma string. O objeto trigger pode conter entidade, estado anterior, estado novo, horário, payload, evento e contexto. A ação deve usar cada dado pelo motivo correto. O ID escolhe o caminho. O estado confirma a realidade. O contexto identifica usuário. O timestamp avalia frescor. Misturar funções cria risco. Em uma automação de porta, ID porta_frente escolhe a mensagem, mas o estado atual decide se é abertura ou fechamento. Se a entrega ocorreu atrasada, a notificação pode ser descartada. O desenho deve separar roteamento e validação.
A nomenclatura funciona como contrato interno
IDs estáveis permitem testes, dashboards e métricas. Mudanças precisam ser tratadas como alteração de interface. Documente significado, gatilhos associados e caminhos. Em blueprints, use IDs previsíveis e evite depender de nomes de entidades fornecidos pelo usuário. Em configuração gerada, valide unicidade. O trace deve preservar o valor. Para auditoria, registre ID junto ao run_id. Essa disciplina aumenta custo inicial pequeno e reduz MTTR, porque um incidente pode ser localizado pelo rótulo sem reconstruir toda a cadeia.