Пульт.Онлайн API
Доступ к API
Пульт.Онлайн предоставляет API для большинства отдельных сервисов, входящих в состав системы. API предоставляется в формате JSONRPC2.0 по протоколу Websocket. Порт, на котором сервис принимает API-запросы, указан в его настройках в параметре tcp_port. Данный порт должен быть открыт в фаерволе. Необходимо также убедиться что у сервиса включен параметр listen_tcp_port, а параметр allowed_ip позволяет подключаться с IP клиента.Websocket Client
Для тестовых запросов можно воспользоваться плагином для браузера, например Smart Websocket Client или Advanced Websocket Client. В строке Websocket address необходимо указать URL сервиса, включая хост и порт, например:ws://192.168.0.100:11200/В данном примере будет выполнено подключение к сервису Core (порт 11200). Запрос выполняется кнопкой Send после подключения к сервису (кнопка Connect).Интерфейс командной строки (CLI)
Доступ к API любого сервиса может быть выполнен через Интерфейс командной строки (API over CLI):./cli unix://<unix_socket> @<method> [<param1>=<value1> <paramN>=<valueN>]Где: ./cli - скрипт-обертка к сервису rpcconsole, должен выполняться из директории установки (cd /pult) <unix_socket> - имя unix-сокета целевого сервиса. См. настройки сервиса, параметр unix_socket @<method> - имя api-метода, предваряемое символом @ (строгий режим вывода json) <param1>=<value1> - передача параметра и значения Например:> cd /pult > ./cli unix://core.us @set var=P1_N1_var1 value=12345 {"result":true} >Список API-функций сервиса
Список доступных API-функций сервиса можно получить, выполнив запрос с методом api без параметров:{ "jsonrpc":"2.0", "id":1, "method":"api", }Пример ответа (сервис Core):{ "jsonrpc": "2.0", "id": "1", "result": { "request_methods": { "api": [], "exist": [], "list": [], "status": ["vars"], "set": ["var", "value", "payload"], "subscribe": ["event", "id", "options"], "unsubscribe": ["event", "id", "options"] }, "subscription_events": ["update", "upload", "unload"] } }Где: request_methods - объект: -- ключи - доступные методы API-функций сервиса -- значения - массив параметров, принимаемых API-функцией subscription_events - массив имен доступных подписок.
Форматы API
Доступно два формата работы с API: 1) выполнение запросов 2) подписка на события Все запросы выполняются последовательно и синхронно *. Данные приходят в ответе на запрос. Подписка на события позволяет получать данные асинхронно, без выполнения запросов. Данные поступают в JSONRPC-уведомлениях, до прекращения подписки или разрыва соединения.Выполнение запросов
Список API-функций сервиса, доступных по запросу, можно получить, выполнив запрос api (см. Список API-функций сервиса). Список доступных запросов будет возвращен в секции request_methods. В запросе: Поле method - имя API-функции Поле params - аргументы API-функции В ответе: Поле result - успешный ответ API-функции Поле error - ошибка API-функции Общий формат запроса:{ "jsonrpc":"2.0", "id": строка; ID запрооса, "method": строка; имя API-функции "params": опционально, параметры запроса (формат зависит от API-функции) }Общий формат ответа:{ "jsonrpc":"2.0", "id": строка; ID запрооса, "result": опционально, возвращаемые данные (формат зависит от API-функции) "error": { опционально, объект; ошибка, см. JSONRPC2.0 "code": число; код ошибки "message": строка; сообщение ошибки "data": опционально, строка; дополнительные сведения по ошибке } }В ответе присутствует либо result, либо error (см. JSONRPC2.0). Пример запроса с параметрами:{ "jsonrpc":"2.0", "id":1, "method":"status", "params":{ "vars":["var1","var2","var3"] } }Ответ:{ "jsonrpc": "2.0", "id": "1", "result": [ ["var1", 1693912094026, 123], ["var2", 1693912094027, 456], ["var3", 1693912094021, 789] ] }В данном примере вызывается API-функция status сервиса Core, возвращающая статус указанных в параметре vars переменных. В ответ были получены статусы трех переменных, в виде массивов, содержащих [имя_переменной, метку_времени, значение_переменной]Подписка на события
Подписка на интересующие события выполняется API-функцией subscribe. Отписка от события выполняется API-функцией unsubscribe. Общий формат запроса подписки/отписки:{ "jsonrpc":"2.0", "id": строка; ID запрооса, "method": строка; subscribe | unsubscribe, subscribe - подписка, unsubscribe - отписка "params":{ опционально, объект; параметры подписки "event": опционально, строка или массив; имя события или массив имен "id": опционально, строка; id ранее выполненой подписки "options": опционально, формат зависит от подписки; опции подписки } }Общий формат ответных уведомлений:{ "jsonrpc": "2.0", "method": "subscription", "params": { объект; параметры уведомления "event": строка; имя события "data": опционально, данные уведомления, формат зависит от подписки "close": опционально, true; прекращение уведомлений по подписке (требуется переподписаться) "error": опционально, объект; причина прекращения подписки, формат аналогичен стандартной ошибке JSONRPC2.0 } }В уведомлении присутствует либо data, либо close и error в случае прекращения подписки. В случае прекращения подписки необходимо выполнить подписку заново, указав все параметры и опции подписки. Пример подписки на изменения статусов переменных:{ "jsonrpc":"2.0", "id":1, "method":"subscribe", "params":{ "event":"update", "options":{ "vars":["var1","var2","var3"] } } }Пример ответных уведомлений:{ "jsonrpc": "2.0", "method": "subscription", "params": { "event": "update", "data": { "time": 1693926902606, "changes": [ ["var2", 0, 457] ["var3", 15, 791] ["var1", 93, 125] ] } } }
* - синхронные функции не прерывают работу сервисов, сервисы продолжают обслуживать другие запросы, если не занят основной поток