Xiot-controller-local-api

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Путь	Результат
`/api/v1/remote/get/home`	Дом и его характеристики. Идентификатор дома в текущей реализации — `1`.
`/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>`	Одно виртуальное устройство с указанным идентификатором.

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

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

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

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

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

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

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

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}"

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

{"set":"ok"}

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

{"set":"error"}

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

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

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

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

Коды и ответы

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

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

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

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

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

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

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

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

Убедитесь, что XIOT-PLC включён и доступен по его текущему IP-адресу из той же доверенной сети.
Проверьте, что используется порт 5552, а ключ передан ровно в одном поддерживаемом заголовке.
При ошибке 401 заново скопируйте текущий ключ; после обновления ключа старое значение уже не подходит.
При пустом ответе сначала проверьте полный путь и получите актуальные идентификаторы списочным запросом.
При {"set":"error"} сверьте объект и направление характеристики в проекте.
Если получено {"set":"ok"}, но оборудование не отреагировало, проверьте адрес управления, адрес состояния, драйвер и физическое оборудование. Полезны Системные события в журнале XIOT-PLC и Механизм работы тегов в XIOT.

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

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

Настройка драйверов — исходящие интеграционные модули и протоколы.
Привязка реальных устройств к виртуальным — связь команды API с физическим оборудованием.
Механизм работы тегов в XIOT — адреса управления и состояния.