Xiot-controller-local-api: различия между версиями

Версия от 08:43, 28 мая 2026

Локальное 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"}

В этом случае проверьте ключ в настройках контроллера и обновите его во внешней системе.

@@ Строка 1: / Строка 1: @@
-Локальное API контроллера XIOT работает на контроллере по HTTP на порту 5552.
+Локальное API контроллера XIOT позволяет внешним системам получать состояние дома и управлять устройствами в локальной сети. API работает на контроллере по адресу:
-== Авторизация ==
+<syntaxhighlight lang="text">
+http://<ip-контроллера>:5552
+</syntaxhighlight>
+== Ключ доступа ==
-Все запросы к API должны передавать ключ локального API. Запрос без ключа или с неверным ключом возвращает HTTP 401:
+Для работы с API нужен ключ доступа. Он отображается в редакторе XIOT:
-<syntaxhighlight lang="json">
+<syntaxhighlight lang="text">
-{"error":"unauthorized"}
+Настройки контроллера -> Ключ локального API (порт 5552)
 </syntaxhighlight>
-Ключ хранится на контроллере в системном теге <code>/system/plc/apikey</code> и сохраняется в <code>SaveVal</code>. В редакторе он отображается в окне '''Настройки контроллера''' в строке '''Ключ локального API (порт 5552)'''.
+Все запросы к API должны передавать этот ключ. Если ключ не указан или указан неверно, контроллер вернет ошибку авторизации.
-Для смены ключа нажмите '''Обновить ключ локального API'''. После обновления старый ключ сразу перестает подходить для новых запросов.
+Ключ можно обновить в том же окне настроек кнопкой '''Обновить ключ локального API'''. После обновления старый ключ перестает работать, поэтому его нужно заменить во всех внешних интеграциях.
-Ключ можно передавать одним из способов:
+== Как передавать ключ ==
+Рекомендуемый способ - передавать ключ в HTTP-заголовке:
 <syntaxhighlight lang="bash">
-curl -H "X-XIOT-API-Key: <ключ>" "http://<ip-контроллера>:5552/api/v1/remote/get/devices"
+curl -H "X-XIOT-API-Key: <ключ>" \
+  "http://192.168.1.10:5552/api/v1/remote/get/devices"
 </syntaxhighlight>
+Также поддерживается заголовок авторизации:
 <syntaxhighlight lang="bash">
-curl -H "Authorization: Bearer <ключ>" "http://<ip-контроллера>:5552/api/v1/remote/get/devices"
+curl -H "Authorization: Bearer <ключ>" \
+  "http://192.168.1.10:5552/api/v1/remote/get/devices"
 </syntaxhighlight>
-Для простых GET-запросов также поддерживается параметр URL <code>key</code>, <code>api_key</code> или <code>apikey</code>:
+Для простых проверок ключ можно передать в адресе запроса:
 <syntaxhighlight lang="text">
-http://<ip-контроллера>:5552/api/v1/remote/get/devices?key=<ключ>
+http://192.168.1.10:5552/api/v1/remote/get/devices?key=<ключ>
 </syntaxhighlight>
-Рекомендуемый способ для интеграций - HTTP-заголовок <code>X-XIOT-API-Key</code>.
+Для постоянных интеграций лучше использовать заголовок, а не параметр в адресе.
 == Получение данных ==
-Базовый адрес:
+Запросы чтения возвращают данные в формате JSON.
-<syntaxhighlight lang="text">
-http://<ip-контроллера>:5552
-</syntaxhighlight>
-Доступные GET-методы:
 {| class="wikitable"
-! Метод
+! Запрос
-! Описание
+! Что возвращает
 |-
 | <code>/api/v1/remote/get/home</code>
-| Получить объект дома и его характеристики.
+| Дом и его характеристики.
 |-
 | <code>/api/v1/remote/get/floors</code>
-| Получить список этажей.
+| Список этажей.
 |-
-| <code>/api/v1/remote/get/floor/&lt;floorid&gt;</code>
+| <code>/api/v1/remote/get/floor/&lt;id_этажа&gt;</code>
-| Получить один этаж.
+| Один этаж.
 |-
 | <code>/api/v1/remote/get/rooms</code>
-| Получить список комнат.
+| Список комнат.
 |-
-| <code>/api/v1/remote/get/room/&lt;roomid&gt;</code>
+| <code>/api/v1/remote/get/room/&lt;id_комнаты&gt;</code>
-| Получить одну комнату.
+| Одна комната.
 |-
 | <code>/api/v1/remote/get/devices</code>
-| Получить список устройств.
+| Список устройств.
 |-
-| <code>/api/v1/remote/get/device/&lt;devid&gt;</code>
+| <code>/api/v1/remote/get/device/&lt;id_устройства&gt;</code>
-| Получить одно устройство.
+| Одно устройство.
 |}
-Пример:
+Пример запроса устройства:
 <syntaxhighlight lang="bash">
@@ Строка 74: / Строка 78: @@
 </syntaxhighlight>
-Ответ содержит объект, где ключом является идентификатор сущности. Характеристики возвращаются в поле <code>characteristic</code>.
+В ответе используется идентификатор объекта и список его характеристик.
+== Управление устройствами ==
-== Управление ==
+Управление выполняется запросами вида:
+<syntaxhighlight lang="text">
+/api/v1/remote/set/<тип>/<id>/<характеристика>/<значение>
+</syntaxhighlight>
-Управление выполняется GET-запросом <code>/api/v1/remote/set/...</code>. При успешной записи API возвращает:
+При успешном выполнении контроллер вернет:
 <syntaxhighlight lang="json">
@@ Строка 84: / Строка 94: @@
 </syntaxhighlight>
-Если запись не выполнена:
+Если команда не выполнена:
 <syntaxhighlight lang="json">
@@ Строка 93: / Строка 103: @@
 {| class="wikitable"
-! Метод
+! Запрос
-! Описание
+! Что делает
 |-
-| <code>/api/v1/remote/set/home/&lt;homeid&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
+| <code>/api/v1/remote/set/home/&lt;id_дома&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
-| Установить характеристику дома.
+| Устанавливает характеристику дома.
 |-
-| <code>/api/v1/remote/set/floor/&lt;floorid&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
+| <code>/api/v1/remote/set/floor/&lt;id_этажа&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
-| Установить характеристику этажа.
+| Устанавливает характеристику этажа.
 |-
-| <code>/api/v1/remote/set/room/&lt;roomid&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
+| <code>/api/v1/remote/set/room/&lt;id_комнаты&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
-| Установить характеристику комнаты.
+| Устанавливает характеристику комнаты.
 |-
-| <code>/api/v1/remote/set/device/&lt;devid&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
+| <code>/api/v1/remote/set/device/&lt;id_устройства&gt;/&lt;характеристика&gt;/&lt;значение&gt;</code>
-| Установить характеристику устройства.
+| Устанавливает характеристику устройства.
 |}
@@ Строка 123: / Строка 133: @@
 </syntaxhighlight>
-== Медиа-плеер ==
+== Ошибка авторизации ==
+Если ключ не передан или указан неверно, контроллер возвращает код 401 и ответ:
+<syntaxhighlight lang="json">
+{"error":"unauthorized"}
+</syntaxhighlight>
-Адреса вида <code>/api/v1/mplayer/...</code> передаются в модуль <code>mplayer</code>. Они также требуют ключ локального API.
+В этом случае проверьте ключ в настройках контроллера и обновите его во внешней системе.
-== Безопасность ==
+== Рекомендации ==
-* Не публикуйте ключ в общедоступных проектах, скриншотах и документации.
+* Не передавайте ключ третьим лицам.
-* При компрометации ключа обновите его в настройках контроллера.
+* Не публикуйте ключ в открытых проектах, скриншотах и документации.
-* После обновления ключа внешние интеграции нужно переключить на новое значение.
+* Если ключ мог попасть к посторонним, обновите его в настройках контроллера.
-* API работает по локальной сети без HTTPS, поэтому не передавайте ключ через недоверенные сети.
+* API работает в локальной сети без шифрования, поэтому не используйте его через недоверенные сети.