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

Текущая версия от 22:12, 2 октября 2026

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

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

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

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

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

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

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

Admin (обсуждение | вклад)