Безопасное управление реле

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

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

Рекомендуемый поток

Отправляйте все изменения реле одного устройства в одном массиве relays. Один пакет становится одной командой устройства и позволяет избежать последовательных передач, которые устройство может обработать ненадёжно.

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

1. Используйте Список определений типов устройств (на английском), чтобы подтвердить device.relay.set, количество реле и допустимые действия.
2. Постройте желаемый массив реле. Используйте один элемент для управления одним каналом и несколько уникальных индексов для скоординированного изменения.
3. Сгенерируйте новый Idempotency-Key, принадлежащий вызывающей стороне, для этого намерения операции.
4. Вызовите Выполнение команды реле (на английском) с правом доступа device:control.
5. Прочитайте data.command.id и data.command.status. Если статус SENT, используйте Получение результата команды (на английском) до достижения финального статуса или своего ограниченного срока опроса.
6. Используйте data.state, когда подтверждение устройства его включает. Не запускайте ещё одно обновление только для заполнения необязательного поля.
7. Если результат TIMEOUT, прочитайте текущее состояние устройства перед тем, как решить, безопасна ли другая операция.

Жизненный цикл команды

Результат	Значение	Действие клиента
HTTP 202 + COMMAND_ACCEPTED	Платформа приняла запрос; это не отдельный статус команды	Прочитайте data.command.status и сохраните ID команды
SENT	Команда всё ещё ожидает подтверждения	Запросите результат с ограниченным опросом
SUCCESS	Устройство подтвердило выполнение	Примените возвращённое состояние, если оно присутствует
FAILED	Платформа подтвердила, что команда не завершилась успешно	Остановите автоматические повторные попытки и обработайте сбой
TIMEOUT	Окончательное подтверждение не поступило в течение окна ожидания	Не предполагайте, выполнило устройство команду или нет; сначала прочитайте текущее состояние

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

• Выполнение команды реле (на английском)
• Получение результата команды (на английском)
• Получение состояния устройства (на английском)
• Лимиты запросов и идемпотентность (на английском)
• Управление реле через WebSocket (на английском)

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

• Если результат HTTP неизвестен из-за сбоя сети, повторите тот же самый запрос с тем же Idempotency-Key.
• После 429 RATE_LIMITED дождитесь Retry-After, затем повторите ту же операцию с исходным ключом.
• Никогда не используйте ключ повторно для другого устройства, другого массива реле или другого действия; это вернёт IDEMPOTENCY_CONFLICT.
• После TIMEOUT сначала обновите состояние. Если оно всё ещё неизвестно, потребуйте бизнес-решения, прежде чем отправлять другую физическую операцию.
• Повторение JOG или других действий с оборудованием может вызвать реальные побочные эффекты, даже если предыдущий ответ был потерян. Соответственно проектируйте подтверждения и меры безопасности для оператора.

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

• Храните вместе ключ идемпотентности, ID команды, запрошенный массив реле, статус и requestId для аудита и восстановления.
• Сериализуйте или координируйте в своём приложении операции, направленные на одно и то же устройство.
• Используйте ограниченный опрос результатов и соблюдайте лимиты запросов.
• Проверяйте целевой канал и физическую безопасность перед тем, как разрешить управление из интерфейса или правила автоматизации.

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

• Событие изменения состояния устройства (на английском)
• Ошибки ресурсов и команд (на английском)
• Панель мониторинга устройств