Просмотр кода страницы Xiot-controller-local-api

{{DISPLAYTITLE:Локальное API контроллера XIOT}}
'''Локальное API контроллера XIOT''' — входящий HTTP-интерфейс XIOT-PLC. Внешняя система в доверенной локальной сети может через него прочитать объекты и характеристики загруженного проекта или передать команду. API не создаёт новые адреса: оно использует дом, этажи, комнаты, виртуальные устройства и характеристики, которые уже есть в действующей конфигурации контроллера.

Не путайте локальное API с исходящим модулем REST API: локальное API принимает обращения внешней системы на XIOT-PLC, а исходящий модуль сам обращается к другому серверу. Обзор интеграционных модулей: [[Driver-setup|Настройка драйверов]].

Описанный контракт проверен по опубликованному пакету XIOT-PLC <code>14.1-1-1</code>. В этой версии контроллер принимает запросы по схеме HTTP на своём IP-адресе и порту <code>5552</code>.

== Перед началом ==

* Загрузите на XIOT-PLC актуальную конфигурацию проекта и убедитесь, что нужное виртуальное устройство связано с реальным оборудованием: [[Device-bindings|Привязка реальных устройств к виртуальным]].
* Подключайте внешнюю систему только из доверенной локальной сети либо через защищённый VPN.
* Не пробрасывайте порт <code>5552</code> на маршрутизаторе и не публикуйте его в Интернете.
* Для первой команды выберите известное устройство с безопасной и видимой реакцией. Не начинайте проверку на замках, воротах, насосах, отоплении, защитной автоматике и другом оборудовании, неожиданное включение которого опасно.

== Получение и обновление ключа ==

# Откройте привязанный контроллер в XIOT-EDITOR.
# Откройте окно '''Настройки контроллера'''.
# Скопируйте значение поля '''Ключ локального API (порт 5552)'''.

Это единый секрет контроллера: с ним можно читать данные проекта и отправлять команды доступным через API объектам. Храните ключ как пароль. Не помещайте его в вики, исходный код, скриншоты, обращения в поддержку и общие журналы.

Кнопка '''Обновить ключ локального API''' создаёт новый ключ. Старый ключ после этого перестаёт проходить авторизацию, поэтому обновите его во всех разрешённых интеграциях. Если ключ мог попасть к посторонним, обновите его сразу.

== Подготовка запроса ==

В примерах ниже используются две переменные, значения которых задаются только в вашей локальной среде:

* <code>XIOT_API</code> — базовый адрес из схемы <code>http</code>, IP-адреса контроллера и порта <code>5552</code>;
* <code>XIOT_API_KEY</code> — текущий ключ локального API.

Для разовой проверки в <code>bash</code> или <code>zsh</code> значения можно ввести интерактивно, не записывая их в историю команд:

<syntaxhighlight lang="bash">
read -r -p "Базовый адрес XIOT API: " XIOT_API
read -r -s -p "Ключ XIOT API: " XIOT_API_KEY
printf '\n'
</syntaxhighlight>

Рекомендуемый вариант авторизации — заголовок <code>X-XIOT-API-Key</code>:

<syntaxhighlight lang="bash">
curl --silent --show-error --max-time 10 \
  -H "X-XIOT-API-Key: ${XIOT_API_KEY}" \
  "${XIOT_API}/api/v1/remote/get/devices"
</syntaxhighlight>

Также поддерживается заголовок <code>Authorization: Bearer</code>. Не передавайте ключ в адресе запроса: адрес может сохраниться в истории, журналах и системах мониторинга.

Текущая реализация использует метод HTTP <code>GET</code> и для чтения, и для команд изменения. Не открывайте командные адреса в браузере, не сохраняйте их в закладках и не пропускайте через кэширующие или автоматически повторяющие запросы посредники.

== Получение данных ==

{| class="wikitable"
! Путь
! Результат
|-
| <code>/api/v1/remote/get/home</code>
| Дом и его характеристики. Идентификатор дома в текущей реализации — <code>1</code>.
|-
| <code>/api/v1/remote/get/floors</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;id&gt;</code>
| Одна комната с указанным идентификатором.
|-
| <code>/api/v1/remote/get/devices</code>
| Все виртуальные устройства с комнатами, этажами и характеристиками.
|-
| <code>/api/v1/remote/get/device/&lt;id&gt;</code>
| Одно виртуальное устройство с указанным идентификатором.
|}

Ответ имеет формат JSON. Объекты индексируются их идентификаторами. Для устройств возвращаются имя, тип, сведения о комнате и этаже, а также объект <code>characteristic</code> с текущими значениями характеристик. Набор полей и характеристики зависят от загруженного проекта.

Сначала запросите списки и возьмите идентификаторы из фактического ответа. Не угадывайте идентификатор и не переносите его из чужого примера. После изменения структуры проекта выполните обнаружение заново.

== Отправка команды ==

Форма пути команды:

<syntaxhighlight lang="text">
/api/v1/remote/set/<тип>/<id>/<характеристика>/<значение>
</syntaxhighlight>

Поддержаны типы <code>home</code>, <code>floor</code>, <code>room</code> и <code>device</code>. Идентификатор и имя характеристики берите из текущего проекта и ответа API. До команды проверьте в XIOT-EDITOR или в документации виртуального устройства, что характеристика предназначена для управления. Если сегмент содержит специальные символы, его нужно корректно кодировать для URL.

Пример с заранее проверенными локальными переменными:

<syntaxhighlight lang="bash">
curl --silent --show-error --max-time 10 \
  -H "X-XIOT-API-Key: ${XIOT_API_KEY}" \
  "${XIOT_API}/api/v1/remote/set/device/${DEVICE_ID}/${CHARACTERISTIC}/${VALUE}"
</syntaxhighlight>

Ответ обработчика на принятую команду:

<syntaxhighlight lang="json">
{"set":"ok"}
</syntaxhighlight>

Этот ответ означает, что обработчик нашёл объект и характеристику и вызвал внутреннюю команду XIOT. Он не подтверждает физическое выполнение оборудованием. Если обработчик не нашёл объект или характеристику либо не смог вызвать команду, обычно возвращается:

<syntaxhighlight lang="json">
{"set":"error"}
</syntaxhighlight>

Оба ответа могут прийти с кодом HTTP <code>200</code>, поэтому проверяйте и код, и JSON, и фактический результат.

== Безопасная проверка ==

# Выполните <code>/api/v1/remote/get/devices</code> и найдите нужное устройство по фактическому ответу.
# Сверьте его идентификатор, характеристику управления и допустимое значение с текущим проектом.
# Выберите безопасную нагрузку с видимой реакцией и запишите исходное состояние.
# Отправьте одну команду. Не настраивайте автоматические повторы при неопределённом результате.
# Проверьте физическую реакцию оборудования, затем повторно запросите <code>/api/v1/remote/get/device/&lt;id&gt;</code> и сравните состояние.
# Если значение было изменено только для теста, верните исходное состояние и ещё раз проверьте оборудование.

Ответ API без физической реакции не считается успешной приёмкой всей цепочки. Если адрес состояния не отражает реальность, сначала исправьте привязку устройства.

== Коды и ответы ==

{| class="wikitable"
! Наблюдение
! Что оно означает
|-
| HTTP <code>401</code> и <code>{"error":"unauthorized"}</code>
| Ключ отсутствует или не совпадает с текущим ключом контроллера.
|-
| HTTP <code>200</code> и непустой JSON объекта
| Запрос чтения обработан; содержимое всё равно нужно проверить.
|-
| HTTP <code>200</code> и <code>{}</code>
| Объект не найден, путь не распознан либо в текущей конфигурации нет данных. Код <code>200</code> сам по себе не доказывает правильность пути.
|-
| HTTP <code>200</code> и <code>{"set":"ok"}</code>
| Внутренняя команда вызвана; физический результат ещё нужно проверить.
|-
| HTTP <code>200</code> и <code>{"set":"error"}</code>
| Команда не принята обработчиком; проверьте полный путь, тип, идентификатор и характеристику.
|-
| Нет HTTP-ответа
| Проверьте питание и доступность контроллера, его текущий IP-адрес, маршрут, локальный межсетевой экран и порт <code>5552</code>.
|}

Не рассчитывайте на отдельный код <code>404</code> для каждого неверного пути: текущий обработчик может вернуть пустой JSON с кодом <code>200</code>.

== Безопасность сети ==

* API слушает порт <code>5552</code> на сетевых интерфейсах контроллера и рассчитан на доверенный контур.
* Встроенный интерфейс использует обычный HTTP без TLS. В недоверенной сети можно перехватить и ключ, и команды.
* Разрешайте соединение только нужным узлам локальной сети. Для удалённого доступа используйте администрируемый VPN с ограничением маршрутов и источников.
* Не открывайте порт <code>5552</code> в Интернет, даже если используется сложный ключ.
* Не передавайте ключ в строке запроса. Не записывайте полные заголовки авторизации в журналы.
* При увольнении подрядчика, компрометации компьютера или публикации конфигурации обновите ключ и удалите старое значение из всех хранилищ и журналов, где это возможно.

== После изменения проекта ==

Локальное API работает с конфигурацией, фактически загруженной на XIOT-PLC. Команда '''Загрузить конфигурацию на контроллер''' сначала сохраняет проект локально и после успешной записи отправляет сохранённую конфигурацию на XIOT-PLC. Облачное сохранение и публикацию приложения проверяют отдельно: успешная загрузка на PLC их не подтверждает. Отдельное сохранение без загрузки не изменяет набор объектов API на контроллере.

После добавления, удаления или повторного создания объектов заново запросите списки, проверьте идентификаторы и выполните безопасную приёмку интеграции. Не считайте старые идентификаторы бессрочным контрактом.

== Если запрос не работает ==

# Убедитесь, что XIOT-PLC включён и доступен по его текущему IP-адресу из той же доверенной сети.
# Проверьте, что используется порт <code>5552</code>, а ключ передан ровно в одном поддерживаемом заголовке.
# При ошибке <code>401</code> заново скопируйте текущий ключ; после обновления ключа старое значение уже не подходит.
# При пустом ответе сначала проверьте полный путь и получите актуальные идентификаторы списочным запросом.
# При <code>{"set":"error"}</code> сверьте объект и направление характеристики в проекте.
# Если получено <code>{"set":"ok"}</code>, но оборудование не отреагировало, проверьте адрес управления, адрес состояния, драйвер и физическое оборудование. Полезны [[Xiot-plc-system-log-events|Системные события в журнале XIOT-PLC]] и [[Xiot-tags|Механизм работы тегов в XIOT]].

Если причина не найдена, обратитесь на страницу [[Support|Связь с поддержкой]]. Передавайте время проверки, версию XIOT-PLC и обезличенный путь запроса; не отправляйте ключ и полные заголовки авторизации.

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

* [[Driver-setup|Настройка драйверов]] — исходящие интеграционные модули и протоколы.
* [[Device-bindings|Привязка реальных устройств к виртуальным]] — связь команды API с физическим оборудованием.
* [[Xiot-tags|Механизм работы тегов в XIOT]] — адреса управления и состояния.

[[Категория:XIOT-PLC]]
[[Категория:Интеграции]]
{{DEFAULTSORT:Локальное API контроллера XIOT}}