Передача данных устройств в ваш SaaS

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

Используйте этот шаблон, когда возможности устройств WLTE — это часть вашего собственного продукта (многоарендный SaaS, внутренняя операционная система или подобное). Ваши конечные пользователи взаимодействуют с вашим продуктом и вашей собственной системой учётных записей — они никогда напрямую не соприкасаются с учётными данными WLTE.

• Одна учётная запись WLTE и один API Client обеспечивают всё ваше развёртывание, а не отдельные учётные данные для каждого конечного клиента.
• Устройства в рамках учётной записи WLTE плоские; понятия арендатора (tenant) не существует. То, какие устройства принадлежат какому клиенту, — это сопоставление, которое вы создаёте и поддерживаете сами.
• Живые события должны непрерывно поступать в ваш собственный конвейер данных (база данных, очередь сообщений, собственный WebSocket или webhook), а не так, чтобы каждая страница каждого конечного клиента держала собственное соединение с WLTE.

Никогда не передавайте clientId, clientSecret или access token конечному клиенту. Не предполагайте, что устройства в рамках одной учётной записи изолированы по арендаторам — это не так.

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

Только ваш бэкенд хранит учётные данные WLTE. Поддерживайте сопоставление deviceId → tenantId, обслуживайте всех арендаторов через одно соединение WebSocket и распределяйте данные через остальную часть вашей системы.

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

1. Спроектируйте и поддерживайте сопоставление deviceId → tenantId (или собственный идентификатор клиента/объекта). Учётные записи WLTE не различают арендаторов — эта таблица является центральной структурой данных всей интеграции.
2. Получите access token от вашего единственного API Client, хранимого на сервере: device:read для использования только для чтения, плюс device:control или device:config, если вы отправляете команды.
3. Вызовите Список устройств (на английском) и Список определений типов устройств (на английском), чтобы построить начальное базовое состояние, затем разделите его на представления по арендаторам, используя вашу таблицу сопоставления.
4. Создайте одноразовый тикет WebSocket (на английском) и установите одно соединение — а не по одному на каждого арендатора — для получения событий подключения, событий изменения состояния и событий питания (на английском).
5. При каждом событии сначала находите арендатора по deviceId, затем записывайте в собственное хранилище или очередь, чтобы ваш API/WebSocket/webhook мог доставить это клиентам данного арендатора.
6. Когда конечный клиент отправляет запрос на управление, сначала авторизуйте его в своей собственной системе прав доступа (права вашего продукта для каждого арендатора, а не область доступа WLTE), затем пусть ваш бэкенд проксирует запрос в WLTE с ключом идемпотентности.
7. Сохраняйте результаты команд и события самостоятельно там, где вам нужно долгосрочное хранение или запись для биллинга — WLTE не воспроизводит историю событий повторно, а записи команд хранятся лишь недолго.

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

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

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

• Лимиты запросов считаются на уровне API Client. Несколько арендаторов, использующих одну учётную запись, разделяют один бюджет лимита запросов — высокая частота запросов одного арендатора может исчерпать квоту всей учётной записи, поэтому ограничивайте частоту и ставьте в очередь на своём собственном уровне, а не передавайте частоту запросов конечных клиентов напрямую в WLTE.
• При потере восходящего соединения WebSocket переподключайте это единственное серверное соединение, а не переподключайтесь для каждого арендатора; помечайте нисходящие данные как потенциально устаревшие во время переподключения.
• События, пропущенные во время отключения, не воспроизводятся повторно. Восстановите базовое состояние через REST после переподключения, затем возобновите обновления, управляемые событиями.
• Записи команд и ключи идемпотентности хранятся на стороне WLTE примерно 48 часов. Сохраняйте результаты команд и финальный статус самостоятельно, если вам нужно более длинное окно аудита или биллинга.
• При 429 RATE_LIMITED дождитесь Retry-After. Не реализуйте отдельный независимый цикл повторных попыток для каждого арендатора в своём сервисе.

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

• Конечные клиенты никогда, ни при каких обстоятельствах не должны видеть или получать clientId, clientSecret или access token WLTE — каждый вызов WLTE должен проходить через ваш бэкенд.
• Четыре области доступа WLTE (device:read/device:control/device:config/device:manage) — это грубые права на уровне учётной записи. Они не заменяют вашу собственную детализированную модель прав доступа для каждого клиента — это два отдельных уровня авторизации.
• Относитесь к сопоставлению deviceId → tenantId как к самой важной таблице в вашей системе; поддерживайте её синхронизацию всякий раз, когда устройства добавляются или удаляются из учётной записи, или когда клиенты добавляют или удаляют объекты, чтобы избежать попадания данных не к тому арендатору.
• Планируйте бюджет лимита запросов заранее: количество арендаторов увеличивает объём ваших запросов линейно, но лимит запросов учётной записи не растёт вместе с ним.
• См. Области авторизации (на английском) для доступных комбинаций областей доступа и Лимиты запросов и повторные попытки (на английском) для измерений лимитов запросов.

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

• Панель мониторинга устройств
• REST API или WebSocket
• Области авторизации (на английском)
• Лимиты запросов и повторные попытки (на английском)