Download PDF
Download page REST API. Начало работы с REST API компонента «Универсальный диспетчер» Termidesk.
REST API. Начало работы с REST API компонента «Универсальный диспетчер» Termidesk
Получение токена
Перед использованием REST API нужно получить токен (-H 'X-Auth-Token: 7bjqtodywjd69dkpdta9ncqprifkr3pu'
из примера выше), который необходимо подставлять во все последующие запросы, кроме запросов health
. Для получения токена необходимо авторизоваться в Termidesk, для этого:
- выполнить URL-запрос:
https://disp.termidesk.local/api/auth/v1.4/authenticators
; - запомнить значения параметров
authUuid
,authSmallName
,auth
; - выполнить URL-запрос:
https://disp.termidesk.local/api/auth/v1.4/legacy/login
и заполнить экранные поля «Логин», «Пароль», «Название аутентификатора» (значение параметра auth из предыдущей команды), «UUID аутентификатора» (значение параметра authUuid из предыдущей команды), «Короткое название аутентификатора» (значение параметра authSmallName из предыдущей команды).
В приведенных командах disp.termidesk.local
- сетевой адрес или полное доменное имя узла компонента «Универсальный диспетчер» Termidesk.
Для запросов проверки состояния сервера /api/health
используется токен, определенный в конфигурационном файле /etc/opt/termidesk-vdi/termidesk.conf
в значении переменной HEALTH_CHECK_ACCESS_KEY
.
Формат запроса к /api/health
выглядит следующим образом:
curl -X 'GET' \
'https://disp.termidesk.local/api/health/' \
-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/' \
-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 допустимо только на тестовых стендах. Для исправления ошибки в производственной среде необходимо установить на сервер Termidesk валидные сертификаты.
curl -X 'GET' \
'https://disp.termidesk.local/api/health/' \
-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» - модуль взаимодействия с компонентом «Агент» виртуального рабочего места (ВРМ);
- «auth» - модуль для аутентификации пользователей веб-интерфейса;
- «client» - модуль взаимодействия с компонентом «Клиент»;
- «health» - модуль проверки состояния Termidesk;
- «webui» - модуль управления функциями, доступными через веб-интерфейс Termidesk;
- «wsproxy» - модуль взаимодействия с компонентом «Шлюз».
При этом список отображаемых модулей зависит от типа портала, который был выбран при установке «Универсального диспетчера»:
- «Портал администратора»: доступны «auth», «discover», «health», «agent», «webui»;
- «Портал пользователя»: доступны «auth», «discover», «health», «client», «wsproxy», «agent»;
- «Портал администратора» и «Портал пользователя»: доступны все модули.
Электронный справочник по командам
Полная информация о параметрах и командах REST API доступна при вводе URL-команды https://disp.termidesk.local/api/docs/
, где disp.termidesk.local
- сетевой адрес или полное доменное имя узла «Универсального диспетчера» Termidesk.
Доступ предоставляется после авторизации в Termidesk.
По нажатию кнопки [Try it out] в пространстве команд какого-либо модуля можно составить запрос и отправить его на выполнение кнопкой [Execute]. После нажатия будет отображена также команда для запроса через curl
.
Для ввода токена доступа к определенным командам необходимо нажать кнопку [Authorize] и ввести необходимые ключи:
- «bearerAuth» - токен для аутентификации в модулях раздела «external». Получить токен можно в модуле «auth» по URL:
/external/login
; - «legacyTokenAuth» - альтернативный способ аутентификации в модулях раздела «webui». Может быть получен в модуле «auth» по URL:
/legacy/login
. Наименование в заголовках запросов:X-Auth-Token
; - «healthTokenAuth» - токен для аутентификации в модулях раздела «health». Указывается в формате:
Token <значение>
. Значение токена определено в конфигурационном файле/etc/opt/termidesk-vdi/termidesk.conf
,HEALTH_CHECK_ACCESS_KEY
.