Automações
Iteração For Each
Quando uma automação precisa aplicar a mesma sequência a uma coleção variável, a iteração For Each percorre cada item e expõe o elemento atual à ação. Em Home Assistant, repeat.for_each pode iterar listas de entidades, áreas ou objetos; Node-RED usa divisão e junção de mensagens. A estrutura reduz duplicação, mas falha quando a coleção contém tipos inesperados, itens removidos ou chamadas lentas. A interoperabilidade depende do formato dos dados e da capacidade do serviço de aceitar lotes.
⚙ Definição Técnica
Iteração For Each é uma estrutura de repetição orientada a coleção. O motor recebe uma lista, conjunto, mapa ou sequência e executa o mesmo bloco para cada elemento, disponibilizando uma variável com o item atual e, conforme a plataforma, índice, posição, primeiro e último. Aplica-se quando a quantidade de alvos é dinâmica ou quando a mesma lógica seria duplicada. O comportamento pode ser sequencial ou paralelo. Em Home Assistant, repeat.for_each percorre uma lista e expõe repeat.item; em Node-RED, Split transforma um array em mensagens individuais e Join reconstrói; linguagens de script oferecem for…of, foreach ou equivalentes. O recurso depende do formato dos dados. Coleções vazias, itens nulos, tipos mistos e alterações durante a execução precisam de política. Para interoperabilidade, serviços devem aceitar identificadores compatíveis ou oferecer operação em lote.
Tipos comuns de gatilhos
Iteração sequencial sobre entidades
Uma lista de entity_id é percorrida e cada dispositivo recebe ação. Exemplo: fechar dez persianas uma a uma. O modo sequencial evita sobrecarregar o gateway e preserva ordem. Se cada ação leva 2 s, o total pode chegar a 20 s. O critério de escolha depende do protocolo. KNX pode lidar com telegramas rápidos; uma API de nuvem pode limitar taxa; motores de persiana não devem iniciar todos se o circuito tem restrição. A coleção precisa conter entidades válidas. Se uma foi removida, trate erro e continue conforme política. Um alias por item e logs com índice ajudam. Para grupos nativos, enviar um único comando pode ser mais eficiente e sincronizado que iterar.
Iteração sobre objetos estruturados
Cada item pode ser um dicionário com entity, brightness, delay e mensagem. A automação usa campos específicos. Isso permite tabelas declarativas. A validação é essencial: campos obrigatórios, tipos, unidade e limites. Um item com brilho 500 não deve quebrar ou exceder faixa. Defaults precisam ser seguros. Estruturas grandes podem vir de YAML, JSON ou API. Versione o schema. Se o item contém serviço a chamar, use allowlist. Não execute nomes arbitrários fornecidos externamente. A vantagem é separar dados e lógica; a limitação é que erros no conteúdo aparecem em tempo de execução se não houver validação prévia.
Iteração sobre áreas, dispositivos ou grupos descobertos
A coleção é gerada dinamicamente por consulta: todas as luzes de uma área, dispositivos com bateria abaixo de 20% ou entidades com determinada label. Isso reduz manutenção manual. A consulta pode retornar mais itens após novas instalações. O risco é escopo excessivo. Uma label mal aplicada inclui equipamento que não deveria receber ação. Antes de executar comandos destrutivos, filtre domínio e capacidade. A ordem pode não ser estável entre execuções. Se importa, ordene por identificador ou prioridade. Consultas globais em grandes instalações consomem CPU. Materializar grupos pode ser mais previsível.
Iteração paralela por item
Cada elemento é processado simultaneamente para reduzir tempo. Dez notificações ou chamadas independentes podem concluir quase juntas. O motor precisa suportar tarefas paralelas; um For Each comum pode ser sequencial. Em Home Assistant, pode-se combinar scripts paralelos, mas a semântica precisa ser clara. O limite de concorrência evita saturar API e rádio. Se os itens compartilham recurso, mantenha serial. Resultados chegam fora de ordem. Use ID do item. Erros precisam ser agregados. Uma operação pode concluir para oito itens e falhar em dois. O relatório deve listar sucesso e falha, não apenas status global. Para dispositivos de uma mesma malha, disparo em grupo pode ser melhor.
Iteração com pausa, filtro e condição por item
O bloco pode verificar condição antes de cada ação, inserir delay ou encerrar antecipadamente. Exemplo: percorrer quartos, pular os ocupados e desligar luzes com 200 ms entre comandos. A pausa reduz pico, mas aumenta tempo. A condição deve ler estado atual ou snapshot conforme necessidade. Se a coleção muda, o iterador pode usar cópia inicial. Alterar a lista durante o laço é arriscado. Break e continue variam por plataforma. Quando não existem, use choose para pular. Se a lógica possui muitos ramos, talvez um script por item seja mais legível.
Considerações de Implementação
Coleção vazia, nula ou de tipo incorreto precisa de tratamento
Uma consulta pode retornar none, string ou dicionário quando o laço espera lista. Iterar uma string pode percorrer caracteres. O template deve validar sequence e excluir textos quando necessário. Coleção vazia normalmente resulta em zero execuções, não erro. Para ações críticas, isso pode indicar falha de descoberta e deve gerar alerta. Diferencie “nenhum alvo válido” de “fonte indisponível”. Defaults como [] evitam exceção, mas também podem esconder problema. Registre contagem e origem. Testes devem incluir 0, 1, muitos itens e elementos inválidos.
Falha em um item precisa de política explícita
O laço pode interromper no primeiro erro, continuar e registrar, repetir o item ou enviar para fila de falhas. A escolha depende da independência. Ao desligar luzes, continuar é adequado. Ao executar etapas de migração, parar pode evitar inconsistência. O motor nem sempre oferece try/catch por item. Scripts encapsulados podem retornar resultado. Para retentativa, idempotência é necessária. O relatório final deve indicar itens concluídos e falhos. Sem isso, uma execução “erro” não revela se 99 de 100 ações ocorreram.
Operação em lote pode ser superior ao laço
APIs, protocolos e grupos nativos reduzem overhead. Um comando de grupo Zigbee pode acionar várias lâmpadas quase simultaneamente. Uma Batch API envia múltiplas operações em uma requisição. O laço gera N chamadas, N autenticações ou N pacotes. Prefira lote quando a semântica, erro e limite são adequados. O laço oferece personalização por item e controle fino. O critério é custo, sincronismo, observabilidade e capacidade do destino. Teste o comportamento de falha parcial. Um lote pode aceitar parte e rejeitar parte.
O item atual deve ser tratado como variável local
Em execuções paralelas, compartilhar uma variável mutável entre itens causa mistura. Cada iteração precisa de contexto próprio. Em templates, capture repeat.item antes de chamar script assíncrono se a plataforma reutiliza escopo. Nomes claros evitam. Não dependa de índice para identidade se a lista pode ser reordenada. Use entity_id ou ID estável. O índice é útil para atraso progressivo e apresentação. Logs devem incluir ambos. Essa disciplina evita mensagens atribuídas ao dispositivo errado.