API удалённого взаимодействие с платформой
Дата последнего изменения документа: 21 ноября 2023.
Удалённое взаимодействие с платформой осуществляется при помощи отправки HTTP (POST, GET, PUT) запросов.
Описанные механизмы доступны только зарегистрированным пользователям:
а) при использовании специального (строкового) ключа, получаемого у администратора (посредством взаимодействия по e-mail);
или
б) при исползовании JWT токена, получаемого при вызове метода signin:
- адрес - https://iacpaas.dvo.ru/api/signin
- тип запроса - POST запрос
- в заголовок добавить Content-Type: application/json
- данные запроса: json-строка вида {"username":"...", "password":"..."}, где вместо "..." указываются логин и пароль пользователя
При этом доступна работа ТОЛЬКО с инфоресурсами и сервисами этого пользователя.
Кодировка запросов - UTF-8
Импорт-экспорт инфоресурсов осуществляется в формате JSON (см. Документация / Инфоресурсы / JSON-представление информационных ресурсов)
2.1. Импорт инфоресурса в платформу
- адрес - https://iacpaas.dvo.ru/api/data/import
- тип запроса - POST запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- также в заголовок добавить Content-Type: application/json
- Параметры:
- path - путь в "Мой Фонд" до папки, содержащей импортируемую EX (указывать в начале пути "<e-mail>>/Мой Фонд/" не нужно, также не нужно включать имя ЕХ, так как это путь к папке-контейнеру)
- json - собственно импортируемый JSON в виде строки
- clearIfExists - указание на необходимость очистки ИР (удаление всех вершин кроме корневой) перед импортом (true/false)
2.2. Экспорт инфоресурса из платформы
- адрес - https://iacpaas.dvo.ru/api/data/export/user-item
- тип запроса - GET запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- Параметры:
- path - путь до EX в "Мой Фонд", откуда экспортируется JSON (указывать в начале пути "<e-mail>/Мой Фонд/" не нужно)
- json-type - "universal" или "meta" или "simple"
- start-target-concept-path (необязательный) - путь до вершины (в рамках инфоресурса), начиная с которой нужно экспортировать подграф (путь к этой вершине от корня, тем не менее, также будет экспортирован)
- export-depth (необязательный) - глубина экспорта (0 - экспортировать только одну вершину - корень или указанную в качестве начальной; при отсутствии - подграф экспортируется полностью)
- compress (необязательный) - указание на необходимость (zip) сжатия результата (true/false)
- no-blob-data (необязательный) - указание на необходимость пропускать в инфоресурсе blob-значения (true/false)
3.1. Запуск сервиса
- адрес - /api/service/run/{id}
- тип запроса - GET запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- Параметры:
- id - код инфоресурса сервиса (отображается в редакторе сервиса, в меню 'инфо')
3.2. Остановка сервиса
- адрес - /api/service/{id}/stop
- тип запроса - PUT запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- Параметры:
- id - код инфоресурса сервиса (отображается в редакторе сервиса, в меню 'инфо')
3.3. Выяснение статуса работы сервиса
- адрес - /api/service/{id}/running
- тип запроса - GET запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- Параметры:
- id - код инфоресурса сервиса (отображается в редакторе сервиса, в меню 'инфо')
3.4. Рекомендуемый интегрированный запрос для взаимодействия с сервисом (безинтерфейсным)
При необходимости удалённо запускать сервис (без интерфейса!) на платформе с передачей ему некоторых данных до запуска и получением результата по окончании его работы необходимо использовать (интегрированный) запрос:
- адрес - /api/service/import-run-export
- тип запроса - POST запрос
- авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
- также в заголовок добавить Content-Type: application/json
- Параметры (тело запроса в виде JSON):
- import - массив с описаниями импортируемых ресурсов (path - путь в Мой фонд, json - JSON представление, clearIfExists - необходимость предварительной очистки)
- export - массив с описаниями экспортируемых ресурсов (path - путь в Мой фонд, jsonType - тип JSON представления (universal, meta, simple), start-target-concept-path (необязательный) - путь до вершины, export-depth (необязательный) - глубина экспорта)
- id - код инфоресурса сервиса (отображается в редакторе сервиса, в меню 'инфо')
Примечания:
- При выполнении такого запроса ожидается, что сервис не запущен, а после запуска завершит свою работу в течение максимум 30 секунд.
- Ввиду того, что обращение к платформе может выполняться одним и тем же пользователем одновременно (с разных устройств, вкладок браузера и т.п.) - может возникнуть ситуация параллельного множественного выполнения, что приведёт к неопределённому поведению (ошибки в работе агентов, "порча" обрабатываемых инфоресурсов). Во избежание этого запросы этого типа обрабатываются последовательно.
Описание доступных методов в формате Open API можно получить по ссылкам: