Панель мониторинга устройств

Сценарий использования

Используйте этот шаблон для панели мониторинга на уровне учётной записи, которая показывает подключение устройств и состояние периферии, сохраняя при этом предсказуемый HTTP-трафик.

• Используйте списки устройств через REST для первоначального отображения, пагинации и фоновой синхронизации.
• Используйте запрос одного устройства, когда пользователь явно обновляет детальный вид или когда операции требуется подтверждение.
• Используйте события WebSocket для непрерывных изменений подключения, реле и цифровых входов.

Не опрашивайте непрерывно каждое устройство через HTTP.

Рекомендуемая архитектура

Храните одну запись состояния для каждого deviceId. Используйте stateUpdatedAt при слиянии состояния во время выполнения, чтобы старые данные не заменяли более новые. События подключения обновляют состояние связи; changes в device.state.changed указывает затронутые реле или цифровые входы, тогда как peripherals — это полный блок состояния, а не инкрементальный патч. Читайте значения датчиков и аналоговые значения, когда пользователь обновляет данные или когда этого требует бизнес-процесс; не опрашивайте все устройства с высокой частотой.

Пошаговая реализация

1. Получите access token с правом доступа device:read.
2. Вызовите Список устройств (на английском), следуйте пагинации и сохраните deviceType, status, периферию и stateUpdatedAt каждого устройства.
3. Запросите Список определений типов устройств (на английском) и свяжите каждый deviceType с определением его возможностей. Кэшируйте эти определения вместо того, чтобы запрашивать их при каждом отображении.
4. Создайте одноразовый тикет WebSocket (на английском), установите соединение и запустите документированный процесс heartbeat.
5. Применяйте события device.connection.online, device.connection.offline и device.state.changed к соответствующей записи устройства.
6. Когда пользователь явно запрашивает актуальные данные для одного устройства, вызовите Получение устройства (на английском) или отправьте device.state.get (на английском).
7. После разрыва соединения или перезапуска процесса переподключитесь с новым тикетом и восстановите базовое состояние через REST, прежде чем снова доверять живому представлению. Обновляйте индивидуально только критичные для бизнеса устройства.

Ключевые интерфейсы и события

Назначение	Ссылка
Первоначальный список и пагинация	Список устройств (на английском)
Интерфейс на основе возможностей	Список определений типов устройств (на английском)
Явное обновление одного устройства	Получение устройства (на английском)
Аутентификация WebSocket	Создание WebSocket Ticket (на английском)
Изменения подключения	События подключения устройства (на английском)
Изменения состояния периферии	Событие изменения состояния устройства (на английском)

Сбои и восстановление

• При потере WebSocket пометьте живой канал как недоступный, переподключайтесь с экспоненциальной задержкой и jitter, создавая новый wsTicket при каждой попытке.
• События, пропущенные во время отключения, не воспроизводятся повторно. Восстановите базовое состояние через REST после переподключения.
• Если событие и запрос конфликтуют, сохраняйте состояние с более новым stateUpdatedAt.
• После 429 RATE_LIMITED дождитесь Retry-After. Не переходите на опрос по устройствам, чтобы компенсировать отключённый WebSocket.
• Устройство в статусе OFFLINE может содержать последнее синхронизированное состояние периферии. Отображайте состояние подключения и актуальность данных отдельно.

Соображения для продакшна

• Храните нормализованное состояние для каждого deviceId; идентифицируйте показания датчиков по index + type.
• Сделайте применение событий идемпотентным. События подключения предоставляют occurredAt, а события состояния — stateUpdatedAt; игнорируйте более старые обновления, уже отражённые в текущей записи.
• Незамедлительно сохраняйте критичные для бизнеса события, поскольку у WebSocket нет воспроизведения истории.
• Отслеживайте попытки переподключения, задержку событий, сбои синхронизации REST и значения requestId, не логируя учётные данные или токены.

Следующие шаги

• Мониторинг отключений и событий питания
• REST API или WebSocket
• Heartbeat и переподключение (на английском)