Xiot-controller-local-api
Локальное API контроллера XIOT работает на контроллере по HTTP на порту 5552.
Авторизация
Все запросы к API должны передавать ключ локального API. Запрос без ключа или с неверным ключом возвращает HTTP 401:
{"error":"unauthorized"}
Ключ хранится на контроллере в системном теге /system/plc/apikey и сохраняется в SaveVal. В редакторе он отображается в окне Настройки контроллера в строке Ключ локального API (порт 5552).
Для смены ключа нажмите Обновить ключ локального API. После обновления старый ключ сразу перестает подходить для новых запросов.
Ключ можно передавать одним из способов:
curl -H "X-XIOT-API-Key: <ключ>" "http://<ip-контроллера>:5552/api/v1/remote/get/devices"
curl -H "Authorization: Bearer <ключ>" "http://<ip-контроллера>:5552/api/v1/remote/get/devices"
Для простых GET-запросов также поддерживается параметр URL key, api_key или apikey:
http://<ip-контроллера>:5552/api/v1/remote/get/devices?key=<ключ>
Рекомендуемый способ для интеграций - HTTP-заголовок X-XIOT-API-Key.
Получение данных
Базовый адрес:
http://<ip-контроллера>:5552
Доступные GET-методы:
| Метод | Описание |
|---|---|
/api/v1/remote/get/home
|
Получить объект дома и его характеристики. |
/api/v1/remote/get/floors
|
Получить список этажей. |
/api/v1/remote/get/floor/<floorid>
|
Получить один этаж. |
/api/v1/remote/get/rooms
|
Получить список комнат. |
/api/v1/remote/get/room/<roomid>
|
Получить одну комнату. |
/api/v1/remote/get/devices
|
Получить список устройств. |
/api/v1/remote/get/device/<devid>
|
Получить одно устройство. |
Пример:
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/get/device/12"
Ответ содержит объект, где ключом является идентификатор сущности. Характеристики возвращаются в поле characteristic.
Управление
Управление выполняется GET-запросом /api/v1/remote/set/.... При успешной записи API возвращает:
{"set":"ok"}
Если запись не выполнена:
{"set":"error"}
Доступные команды:
| Метод | Описание |
|---|---|
/api/v1/remote/set/home/<homeid>/<характеристика>/<значение>
|
Установить характеристику дома. |
/api/v1/remote/set/floor/<floorid>/<характеристика>/<значение>
|
Установить характеристику этажа. |
/api/v1/remote/set/room/<roomid>/<характеристика>/<значение>
|
Установить характеристику комнаты. |
/api/v1/remote/set/device/<devid>/<характеристика>/<значение>
|
Установить характеристику устройства. |
Пример включения устройства:
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/set/device/12/On/1"
Пример выключения устройства:
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/set/device/12/On/0"
Медиа-плеер
Адреса вида /api/v1/mplayer/... передаются в модуль mplayer. Они также требуют ключ локального API.
Безопасность
- Не публикуйте ключ в общедоступных проектах, скриншотах и документации.
- При компрометации ключа обновите его в настройках контроллера.
- После обновления ключа внешние интеграции нужно переключить на новое значение.
- API работает по локальной сети без HTTPS, поэтому не передавайте ключ через недоверенные сети.