API удалённого взаимодействие с платформой

Дата последнего изменения документа: 11 ноября 2024.

Содержание

Общие сведения
Импорт-экспорт
Сервисы
Open API

1. Общие сведения

Удалённое взаимодействие с платформой осуществляется при помощи отправки HTTP (POST, GET, PUT) запросов.

Описанные механизмы доступны только зарегистрированным пользователям:
а) при использовании специального (строкового) ключа, получаемого у администратора (посредством взаимодействия по e-mail);
или
б) при исползовании JWT токена, получаемого при вызове метода signin:

адрес - https://iacpaas.dvo.ru/api/signin
тип запроса - POST запрос
в заголовок добавить Content-Type: application/json
данные запроса: json-строка вида {"username":"...", "password":"..."}, где вместо "..." указываются логин и пароль пользователя

При этом доступна работа ТОЛЬКО с инфоресурсами и сервисами этого пользователя.

Кодировка запросов - UTF-8

2. Работа с данными

Работа с данными включает выполнение запросов CRUD - Create, Read, Update, Delete. Импорт-экспорт (создание и чтение) инфоресурсов (или их фрагментов) осуществляется в формате JSON (см. Документация / Инфоресурсы / JSON-представление информационных ресурсов)

2.1. Импорт инфоресурса (create)

адрес - 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. Экспорт инфоресурса (read)

адрес - 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)

2.3. Обновление вершины (update)

адрес - https://iacpaas.dvo.ru/api/data/update
тип запроса - PUT запрос
авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
Параметры - передаются в теле запроса в виде JSON со следующими атрибутами:
- path - путь до EX, в которой необходимо обновить вершину, в "Мой Фонд" (указывать в начале пути "<e-mail>/Мой Фонд/" не нужно)
- comment (не обязательный) - новый комментарий вершины
- concept-path - путь до вершины (в рамках инфоресурса)
- metaconcept-path - путь до вершины, состоящий из меток мета-вершин, соответствующих вершинам в пути concept-path
- mark (необязательный) - новая метка вершины (в строковом представлении)

2.4. Удаление вершины (delete)

адрес - https://iacpaas.dvo.ru/api/data/delete
тип запроса - DELETE запрос
авторизация - через HTTP заголовок X-API-KEY=key (key - выданный администратором ключ) или с помощью JWT токена (HTTP заголовок Authorization: Bearer ... - см. ссылки с примерами в разделе 4)
Параметры - передаются в теле запроса в виде JSON со следующими атрибутами:
- path - путь до EX, в которой необходимо обновить вершину, в "Мой Фонд" (указывать в начале пути "<e-mail>/Мой Фонд/" не нужно)
- mode - режим удаления:
  deleteIR - удалить ИР полностью из Фонда пользователя
  trashIR - удалить ИР в корзину (в Фонде пользователя)
  clearIR - очистить ИР (удалить все вершины, кроме корневой)
  deleteSubGraph - удалить подграф в ИР
- concept-path - путь до вершины (в рамках инфоресурса, в случае удаления подграфа)
- metaconcept-path - путь до вершины, состоящий из меток мета-вершин, соответствующих вершинам в пути concept-path (в случае удаления подграфа)

3. Работа с сервисами

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 секунд.
Ввиду того, что обращение к платформе может выполняться одним и тем же пользователем одновременно (с разных устройств, вкладок браузера и т.п.) - может возникнуть ситуация параллельного множественного выполнения, что приведёт к неопределённому поведению (ошибки в работе агентов, "порча" обрабатываемых инфоресурсов). Во избежание этого запросы этого типа обрабатываются последовательно.

4. Open API

Описание доступных методов в формате Open API можно получить по ссылкам: