Xiot-controller-local-api - История изменений

Admin: Английские адреса Wiki: обновление ссылок с сохранением русских подписей

2026-10-02T22:12:13Z

Английские адреса Wiki: обновление ссылок с сохранением русских подписей

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

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

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

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

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

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

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

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

Admin: Admin переименовал страницу Локальное API контроллера XIOT в Xiot-controller-local-api: Английский адрес статьи, русский заголовок и сохранение истории по поручению владельца

2026-10-02T20:53:16Z

Admin переименовал страницу Локальное API контроллера XIOT в Локальное API контроллера XIOT: Английский адрес статьи, русский заголовок и сохранение истории по поручению владельца

← Предыдущая версия	Версия от 20:53, 2 октября 2026
(нет различий)

Admin: Английский адрес статьи, русский заголовок и сохранение истории по поручению владельца

2026-10-02T20:53:14Z

Английский адрес статьи, русский заголовок и сохранение истории по поручению владельца

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

Admin: OLD-05D: локальное сохранение, облако и загрузка PLC по актуальным исходникам

2026-09-16T06:56:04Z

OLD-05D: локальное сохранение, облако и загрузка PLC по актуальным исходникам

← Предыдущая версия		Версия от 06:56, 16 сентября 2026
Строка 162:		Строка 162:
	== После изменения проекта ==		== После изменения проекта ==

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

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

Admin: OLD-04E: безопасная инструкция локального API XIOT-PLC и маршрут из обзора драйверов

2026-09-13T22:43:26Z

OLD-04E: безопасная инструкция локального API XIOT-PLC и маршрут из обзора драйверов

Внесённые изменения

Admin: Уточнено описание локального API контроллера

2026-05-28T08:43:19Z

Уточнено описание локального API контроллера

Внесённые изменения

Admin: Добавлено описание локального API контроллера

2026-05-27T18:59:38Z

Добавлено описание локального API контроллера

Новая страница

Локальное API контроллера XIOT работает на контроллере по HTTP на порту 5552.

== Авторизация ==

Все запросы к API должны передавать ключ локального API. Запрос без ключа или с неверным ключом возвращает HTTP 401:

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

Ключ хранится на контроллере в системном теге <code>/system/plc/apikey</code> и сохраняется в <code>SaveVal</code>. В редакторе он отображается в окне '''Настройки контроллера''' в строке '''Ключ локального API (порт 5552)'''.

Для смены ключа нажмите '''Обновить ключ локального API'''. После обновления старый ключ сразу перестает подходить для новых запросов.

Ключ можно передавать одним из способов:

<syntaxhighlight lang="bash">
curl -H "X-XIOT-API-Key: <ключ>" "http://<ip-контроллера>:5552/api/v1/remote/get/devices"
</syntaxhighlight>

<syntaxhighlight lang="bash">
curl -H "Authorization: Bearer <ключ>" "http://<ip-контроллера>: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=<ключ>
</syntaxhighlight>

Рекомендуемый способ для интеграций - HTTP-заголовок <code>X-XIOT-API-Key</code>.

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

Базовый адрес:

<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/<floorid></code>
| Получить один этаж.
|-
| <code>/api/v1/remote/get/rooms</code>
| Получить список комнат.
|-
| <code>/api/v1/remote/get/room/<roomid></code>
| Получить одну комнату.
|-
| <code>/api/v1/remote/get/devices</code>
| Получить список устройств.
|-
| <code>/api/v1/remote/get/device/<devid></code>
| Получить одно устройство.
|}

Пример:

<syntaxhighlight lang="bash">
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/get/device/12"
</syntaxhighlight>

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

== Управление ==

Управление выполняется GET-запросом <code>/api/v1/remote/set/...</code>. При успешной записи API возвращает:

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

Если запись не выполнена:

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

Доступные команды:

{| class="wikitable"
! Метод
! Описание
|-
| <code>/api/v1/remote/set/home/<homeid>/<характеристика>/<значение></code>
| Установить характеристику дома.
|-
| <code>/api/v1/remote/set/floor/<floorid>/<характеристика>/<значение></code>
| Установить характеристику этажа.
|-
| <code>/api/v1/remote/set/room/<roomid>/<характеристика>/<значение></code>
| Установить характеристику комнаты.
|-
| <code>/api/v1/remote/set/device/<devid>/<характеристика>/<значение></code>
| Установить характеристику устройства.
|}

Пример включения устройства:

<syntaxhighlight lang="bash">
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/set/device/12/On/1"
</syntaxhighlight>

Пример выключения устройства:

<syntaxhighlight lang="bash">
curl -H "X-XIOT-API-Key: <ключ>" \
"http://192.168.1.10:5552/api/v1/remote/set/device/12/On/0"
</syntaxhighlight>

== Медиа-плеер ==

Адреса вида <code>/api/v1/mplayer/...</code> передаются в модуль <code>mplayer</code>. Они также требуют ключ локального API.

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

* Не публикуйте ключ в общедоступных проектах, скриншотах и документации.
* При компрометации ключа обновите его в настройках контроллера.
* После обновления ключа внешние интеграции нужно переключить на новое значение.
* API работает по локальной сети без HTTPS, поэтому не передавайте ключ через недоверенные сети.