Начало работы с REST API компонента «Универсальный диспетчер» Termidesk

Получение токена для доступа к REST API компонента «Универсальный диспетчер»

Перед использованием REST API нужно получить токен авторизации X-Auth-Token, который необходимо подставлять во все последующие запросы, кроме запросов health. Для получения токена нужно авторизоваться в Termidesk, для этого:

  • выполнить запрос «https://disp.termidesk.local/api/auth/v6.1/authenticators»;

  • запомнить значения параметров authUuid, authSmallName, auth;

  • выполнить запрос, подставив соответствующие значения параметров, полученных ранее:

    • либо с использованием утилиты curl. Пример (в поле authId подставляется значение из authUuid):

      curl -X 'POST' \
  'https://disp.termidesk.local/api/auth/v6.1/legacy/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-CSRFToken: UHnQAF4p8PrwF7pAjvToe102tzj3d6QmO6JKdciOb4p7o49tGxJ1Ak28kW9fkVCp' \
  -d '{
  "username": "admin123",
  "password": "admin123",
  "auth": "Встроенный",
  "authId": "a6ec7be4-93d1-4473-8471-6dfc8f734d78",
  "authSmallName": "builtin"
}'

    • либо с использованием интерфейса Swagger, предоставляющего электронный справочник по командам.

В приведенных командах disp.termidesk.local - сетевой адрес или полное доменное имя узла компонента «Универсальный диспетчер» Termidesk.

Для запросов проверки состояния сервера health используется токен,определенный в конфигурационном файле /etc/opt/termidesk-vdi/termidesk.conf в значении параметра HEALTH_CHECK_ACCESS_KEY.

Формат запроса к /api/health/check выглядит следующим образом:

curl -X 'GET' \
'https://disp.termidesk.local/api/health/check' \
-H 'accept: application/json' \
-H 'Authorization: Token 072bfec46ac7c42078bb41ff5f6d1ae201006f0824fb4b2bb8ab8befacb01058'

где:

Token 072…​ - токен, определенный в параметре HEALTH_CHECK_ACCESS_KEY файла /etc/opt/termidesk-vdi/termidesk.conf.

Для форматированного вывода рекомендуется:

  • установить пакет jq:

sudo apt install jq

  • выполнить запрос, добавив в конец команды « |jq». Пример:

curl -X 'GET' \
'https://disp.termidesk.local/api/health/check' \
-H 'accept: application/json' \
-H 'Authorization: Token 072bfec46ac7c42078bb41ff5f6d1ae201006f0824fb4b2bb8ab8befacb01058' | jq

В случае, если запрос завершится ошибкой вида «curl: (60) SSL: no alternative certificate subject name matches target host name…​ curl failed to verify the legitimacy…​ », нужно дополнить запрос флагом --insecure, который отключит проверку валидности сертификатов:

Выполнение запроса без использования проверки SSL допустимо только на тестовых стендах. Для исправления ошибки в производственной среде необходимо установить на сервер с порталом «Универсальный диспетчер» валидные сертификаты.

 
curl -X 'GET' \
'https://disp.termidesk.local/api/health/check' \
-H 'accept: application/json' \
-H 'Authorization: Token 072bfec46ac7c42078bb41ff5f6d1ae201006f0824fb4b2bb8ab8befacb01058' --insecure | jq

Формат URL-команд компонента «Универсальный диспетчер»

Общий вид команд реализован следующим образом:

/api/<module>/<ver>/<name>/,

где:

<module> - наименование модуля, реализованного в REST API;

<ver> - версия;

<name> - наименование элемента. После наименования элемента также могут быть включены уникальные номера объектов и наименования других элементов.

Пример команды через curl:

curl -X 'GET' \
  'https://disp.termidesk.local/api/discover/' \
  -H 'accept: application/json' \
  -H 'X-Auth-Token: 7bjqtodywjd69dkpdta9ncqprifkr3pu'

В REST API реализовано следующее логическое разделение на модули:

  • «discover» - используется для отображения списка модулей API, предоставляемого сервером (команда /api/discover/);

  • «agent» - модуль взаимодействия с компонентом «Агент виртуального рабочего места»;

  • «aggregator» - модуль взаимодействия с порталом «Агрегатор»;

  • «ssa» - модуль взаимодействия с компонентом «Сессионный агент»;

  • «auth» - модуль для аутентификации пользователей веб-интерфейса;

  • «client» - модуль взаимодействия с компонентом «Клиент»;

  • «health» - модуль проверок состояния Termidesk;

  • «webui» - модуль управления функциями, доступными через веб-интерфейс Termidesk;

  • «wsproxy» - модуль взаимодействия с компонентом «Шлюз»;

  • «userinfo» - модуль получения информации о пользователе.

При этом список отображаемых модулей зависит от типа портала, который был выбран при установке «Универсального диспетчера»:

  • «Портал администратора»: доступны «agent», «aggregator», «ssa», «auth», «discover», «health», «userinfo», «webui»;

  • «Портал пользователя»: доступны «agent», «aggregator», «ssa», «auth», «discover», «health», «client», «userinfo», «wsproxy»;

  • «Портал администратора» и «Портал пользователя»: доступны все модули.

Электронный справочник по командам компонента «Универсальный диспетчер»

Полная информация о параметрах и командах REST API доступна при вводе URL-команды https://disp.termidesk.local/api/docs/, где disp.termidesk.local - сетевой адрес или полное доменное имя узла «Универсального диспетчера» Termidesk.

Для получения доступа пользователь должен быть аутентифицирован на «Портале администратора» фермы Termidesk в этой же сессии веб-браузера.

Пример использования:

image
Рисунок 1. Расположение экранных кнопок для получения доступа к формированию запроса

После нажатия будет отображена также команда для запроса через curl.

image
Рисунок 2. Расположение экранной кнопки для формирования запроса