Construir um painel de monitoramento de dispositivos
Caso de uso
Use este padrão para um painel em nível de conta que mostre a conectividade e o estado de periféricos dos dispositivos, mantendo o tráfego HTTP previsível.
- Use as listas de dispositivos via REST para a renderização inicial, paginação e sincronização em segundo plano.
- Use uma consulta de dispositivo único quando o usuário atualizar explicitamente uma visualização de detalhe ou quando uma operação precisar de confirmação.
- Use eventos WebSocket para as mudanças contínuas de conexão, relés e entradas digitais.
Não faça sondagem contínua de todos os dispositivos via HTTP.
Arquitetura recomendada
Mantenha um registro de estado por deviceId. Use stateUpdatedAt ao mesclar o estado em tempo de execução, para que dados antigos não substituam dados mais novos. Os eventos de conexão atualizam a conectividade; changes em device.state.changed identifica os relés ou entradas digitais afetados, enquanto peripherals é um bloco de estado completo, não um patch incremental. Leia os valores analógicos e de sensor quando o usuário atualizar ou quando o fluxo de negócio exigir; não sonde todos os dispositivos com alta frequência.
Implementação passo a passo
- Obtenha um access token com
device:read. - Chame Listar dispositivos (em inglês), siga a paginação e armazene o
deviceType,status, periféricos estateUpdatedAtde cada dispositivo. - Consulte Listar definições de tipo de dispositivo (em inglês) e associe cada
deviceTypeà sua definição de capacidades. Faça cache dessas definições em vez de solicitá-las a cada renderização. - Crie um ticket de WebSocket (em inglês) de uso único, estabeleça a conexão e inicie o fluxo de heartbeat documentado.
- Aplique os eventos
device.connection.online,device.connection.offlineedevice.state.changedao registro de dispositivo correspondente. - Quando um usuário solicitar explicitamente dados atualizados de um dispositivo, chame Consultar dispositivo (em inglês) ou envie
device.state.get(em inglês). - Após uma desconexão ou reinício do processo, reconecte com um ticket novo e reconstrua a base REST antes de voltar a confiar na visualização ao vivo. Atualize individualmente apenas os dispositivos críticos para o negócio.
Interfaces e eventos principais
| Finalidade | Referência |
|---|---|
| Lista inicial e paginação | Listar dispositivos (em inglês) |
| Interface orientada por capacidades | Listar definições de tipo de dispositivo (em inglês) |
| Atualização explícita de um dispositivo | Consultar dispositivo (em inglês) |
| Autenticação WebSocket | Criar WebSocket Ticket (em inglês) |
| Mudanças de conectividade | Eventos de conexão de dispositivo (em inglês) |
| Mudanças de estado de periféricos | Evento de mudança de estado do dispositivo (em inglês) |
Falhas e recuperação
- Se o WebSocket for perdido, marque o canal ao vivo como indisponível, reconecte com backoff exponencial e jitter, e crie um
wsTicketnovo a cada tentativa. - Os eventos perdidos enquanto você estava desconectado não são reproduzidos. Reconstrua a base de estado via REST após reconectar.
- Se um evento e uma consulta competirem, mantenha o estado com o
stateUpdatedAtmais recente. - Após um
429 RATE_LIMITED, aguarde oRetry-After. Não passe a sondar por dispositivo para compensar um WebSocket desconectado. - Um dispositivo
OFFLINEpode conter seu último estado de periféricos sincronizado. Mostre a conectividade e a atualidade do estado separadamente.
Considerações para produção
- Armazene um estado normalizado por
deviceId; identifique as leituras de sensor porindex + type. - Torne a aplicação de eventos idempotente. Os eventos de conexão trazem
occurredAt, e os de estado trazemstateUpdatedAt; ignore atualizações mais antigas do que o registro atual. - Persista com rapidez os eventos críticos para o negócio, porque o WebSocket não tem reprodução de histórico.
- Monitore as tentativas de reconexão, o atraso de eventos, as falhas de sincronização REST e os valores de
requestId, sem registrar credenciais ou tokens.