Variáveis de Gatilho

Gatilhos de estado normalmente oferecem estado anterior e novo, entidade, atributo e horário. Isso permite informar “a porta mudou de fechada para aberta” sem consultar o estado atual. O snapshot é importante porque o dispositivo pode mudar novamente antes da ação. Contudo, objetos restaurados após reinício podem ter contextos especiais. from_state pode ser null na criação da entidade. to_state pode conter atributos grandes. A automação precisa testar existência e distinguir transição real de atualização de atributo. Em Home Assistant, mudanças em atributos podem ou não acionar conforme configuração. Para mensagens, use valores amigáveis com fallback. Para decisões críticas, compare também o estado atual quando a ação ocorre, pois o snapshot descreve o evento, não necessariamente a realidade presente.

O objeto pode incluir topic, payload bruto, payload_json, qos e outras informações. Um sensor publica {"temperature":28.4,"unit":"C","ts":...}. A automação extrai os campos. O payload é entrada externa e precisa de validação: tamanho, JSON válido, tipos, limites, unidade e timestamp. Não monte nomes de serviço ou entidades diretamente a partir de strings não controladas. A autenticação do broker e ACLs limitam quem publica. QoS 1 pode entregar duplicatas; event_id ou estado desejado ajuda. Retained messages podem disparar após reconexão e representar dado antigo. Use timestamp e política de frescor. O requisito de implantação é um broker configurado com credenciais, TLS quando aplicável e tópicos bem definidos.

Webhooks podem fornecer método, query, corpo, caminho e metadados autenticados. Cabeçalhos sensíveis devem ser consumidos pela camada de validação e não expostos indiscriminadamente ao template. O corpo JSON precisa de schema. Um event_id sustenta idempotência. Um timestamp assinado limita replay. A automação pode usar device_id e event_type para roteamento, mas deve aplicar allowlist. Retornar erro 4xx para payload inválido evita processamento. Como o emissor pode retentar, a variável de request_id deve ser propagada aos logs. Se a resposta precisa incluir resultado, não bloqueie a conexão por uma ação física longa; persista os dados e responda 202 quando o contrato permitir.

Um gatilho temporal pode expor horário agendado, deslocamento, evento de calendário e atributos. A automação pode calcular atraso entre previsto e real e descartar execução tardia. Em calendários, dados como summary e description são texto externo; não devem ser interpretados como comando sem parsing restrito. Eventos de dia inteiro, fusos e recorrências exigem tratamento. Um texto “desligar alarme” numa agenda compartilhada não deve executar serviço privilegiado apenas por conter frase. Prefira campos estruturados ou calendários dedicados. Se o sistema reinicia e recupera evento, a variável pode refletir horário original. Registre ambos.

Alguns eventos carregam user_id, parent_id, context_id ou origem da execução. Esses campos ajudam a distinguir ação manual, automação, serviço e usuário autenticado. Eles não existem em todos os gatilhos. Um botão físico pode não ter user_id. Uma chamada de API pode ter conta de serviço. Não use ausência como prova de anonimato malicioso nem presença como autorização suficiente. A plataforma de permissões deve decidir. O contexto serve para auditoria, prevenção de loops e personalização. Pode-se evitar que uma automação reaja a mudança produzida por ela mesma, comparando parent_id ou marcadores, mas a semântica varia por motor e versão.