REST API. Начало работы

Получение токена

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

выполнить URL-команду: https://disp.termidesk.local/api/auth/v1.1/authenticators;
запомнить значения параметров authUuid, authSmallName, auth;
выполнить URL-команду: https://disp.termidesk.local/api/auth/v1.1/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'

BASH

где:

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

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

:~$ sudo apt install jq

BASH

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

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

BASH

В случае, если запрос завершится ошибкой вида «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

BASH

Формат URL-команд

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

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

где:

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

<ver> - версия;

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

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

«agent» - модуль взаимодействия с компонентом «Агент» виртуального рабочего места (ВРМ);
«auth» - модуль для аутентификации пользователей веб-интерфейса;
«client» - модуль взаимодействия с компонентом «Клиент»;
«external/rubackup» - модуль для интеграции с системой резервного копирования RuBackup;
«health» - модуль проверки состояния Termidesk;
«webui» - модуль управления функциями, доступными через веб-интерфейс Termidesk;
«wsproxy» - модуль взаимодействия с компонентом «Шлюз».

Список модулей API, предоставляемого сервером, может быть получен URL-командой /api/discover/.

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

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

BASH

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

Полная информация о параметрах и командах 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.

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

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