Xiot-controller-local-api
Локальное API контроллера XIOT позволяет внешним системам получать состояние дома и управлять устройствами в локальной сети. API работает на контроллере по адресу:
http://<ip-контроллера>:5552
Ключ доступа
Для работы с API нужен ключ доступа. Он отображается в редакторе XIOT:
Настройки контроллера -> Ключ локального API (порт 5552)
Все запросы к API должны передавать этот ключ. Если ключ не указан или указан неверно, контроллер вернет ошибку авторизации.
Ключ можно обновить в том же окне настроек кнопкой Обновить ключ локального API. После обновления старый ключ перестает работать, поэтому его нужно заменить во всех внешних интеграциях.
Как передавать ключ
Рекомендуемый способ - передавать ключ в HTTP-заголовке:
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/get/devices"
Также поддерживается заголовок авторизации:
curl -H "Authorization: Bearer <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/get/devices"
Для простых проверок ключ можно передать в адресе запроса:
http://192.168.1.10:5552/api/v1/remote/get/devices?key=<ключ>
Для постоянных интеграций лучше использовать заголовок, а не параметр в адресе.
Получение данных
Запросы чтения возвращают данные в формате JSON.
| Запрос | Что возвращает |
|---|---|
/api/v1/remote/get/home
|
Дом и его характеристики. |
/api/v1/remote/get/floors
|
Список этажей. |
/api/v1/remote/get/floor/<id_этажа>
|
Один этаж. |
/api/v1/remote/get/rooms
|
Список комнат. |
/api/v1/remote/get/room/<id_комнаты>
|
Одна комната. |
/api/v1/remote/get/devices
|
Список устройств. |
/api/v1/remote/get/device/<id_устройства>
|
Одно устройство. |
Пример запроса устройства:
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/get/device/12"
В ответе используется идентификатор объекта и список его характеристик.
Управление устройствами
Управление выполняется запросами вида:
/api/v1/remote/set/<тип>/<id>/<характеристика>/<значение>
При успешном выполнении контроллер вернет:
{"set":"ok"}
Если команда не выполнена:
{"set":"error"}
Доступные команды:
| Запрос | Что делает |
|---|---|
/api/v1/remote/set/home/<id_дома>/<характеристика>/<значение>
|
Устанавливает характеристику дома. |
/api/v1/remote/set/floor/<id_этажа>/<характеристика>/<значение>
|
Устанавливает характеристику этажа. |
/api/v1/remote/set/room/<id_комнаты>/<характеристика>/<значение>
|
Устанавливает характеристику комнаты. |
/api/v1/remote/set/device/<id_устройства>/<характеристика>/<значение>
|
Устанавливает характеристику устройства. |
Пример включения устройства:
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"
Ошибка авторизации
Если ключ не передан или указан неверно, контроллер возвращает код 401 и ответ:
{"error":"unauthorized"}
В этом случае проверьте ключ в настройках контроллера и обновите его во внешней системе.
Рекомендации
- Не передавайте ключ третьим лицам.
- Не публикуйте ключ в открытых проектах, скриншотах и документации.
- Если ключ мог попасть к посторонним, обновите его в настройках контроллера.
- API работает в локальной сети без шифрования, поэтому не используйте его через недоверенные сети.