Интеграция с модулем аналитики#
Доступно только в UEM версии
Интеграция с модулем аналитики — передача справочных данных из внешней системы в отдельную таблицу базы данных сервера RuDesktop через REST API модуля аналитики, без предоставления внешней системе прямого доступа к PostgreSQL
Назначение#
Во внешней системе часто хранится актуальный справочник, который нужен в отчётах: перечень ПО с признаками запрета, список разрешённых устройств и т.п. Если справочник меняется, каждый раз вручную переписывать SQL виртуального датасета неудобно
Интеграция работает так:
На сервере выпускается токен доступа к REST API модуля аналитики — командой
rude superset token createВнешняя система передаёт токен в заголовке
Authorizationзапросов и загружает справочник в виде CSV-файлаПо загрузке в базе данных сервера создаётся отдельная таблица со справочником
Виртуальный датасет читает справочник из этой таблицы вместо жёстко заданных значений
При изменении справочника внешняя система повторяет загрузку — таблица заменяется целиком, SQL датасета не меняется
Подсказка
Модуль аналитики — встроенный Apache Superset. Порядок его установки — на странице Установка модуля аналитики, устройство раздела Аналитика — в руководстве пользователя
Требования#
Лицензия UEM и установленный запущенный модуль аналитики (
rude superset status)У подключения RuDesktopDB включена настройка «Загрузка из файла»: Отчёты → Аналитика → Базы данных → наведите на RuDesktopDB → Редактировать → включите переключатель «Загрузка из файла» (подробнее — Базы данных)
Токен доступа, выпущенный командой
rude superset token createСетевой доступ с узла внешней системы к веб-интерфейсу сервера (порт 443)
Загрузка файлов требует роли Admin модуля аналитики. Роль назначается автоматически при входе через SSO: суперпользователь RuDesktop получает Admin, остальные пользователи — Public без права загрузки. Пользователь, на которого выпускается токен, должен уже существовать в модуле аналитики — два способа его завести:
техническая учётная запись под загрузку (рекомендуется): создайте её прямо в модуле аналитики с ролью Admin — через интерфейс (
https://[SERVER_ADDR]/analytics/users/add) или командойrude superset fab create-user(см. superset token). Учётная запись на сервере RuDesktop для неё не нужна, вход по SSO выполнять не требуетсясуществующий пользователь: если пользователь уже входил в раздел Аналитика, его учётная запись создалась автоматически при первом входе
Шаг 1. Получение токена#
Токен выпускается на сервере командой superset token create и печатается в стандартный вывод — сохраните его, повторно получить значение нельзя:
rude superset token create [имя_пользователя]
Дальше токен передаётся в заголовке Authorization каждого запроса к REST API модуля аналитики:
curl -k -H "Authorization: Bearer [TOKEN]" -H "Accept: application/json" \
"https://[SERVER_ADDR]/analytics/api/v1/database/"
Ответ 200 со списком подключённых баз подтверждает, что доступ работает. Поле id записи RuDesktopDB в result — идентификатор базы, в которую загружается справочник (для единственной базы обычно 1); далее в примерах используется [DATABASE_ID]
Примечание
Ответ 401 на запрос с корректным токеном означает, что установленный модуль аналитики ещё не поддерживает авторизацию по токенам — обновите пакет rudesktop-superset
Важно
Передавайте Accept: application/json во всех запросах. Без этого заголовка (например, в curl по умолчанию) сообщения об ошибках API могут приходить не в JSON, а HTML-страницей с кодом 500 — с заголовком тот же запрос возвращает корректный JSON-ответ со статусом 4xx и описанием ошибки
Шаг 2. Подготовка CSV-файла#
Первая строка файла — имена колонок. Для справочника ПО с параметрами software, pattern, exclude, kind, allowed:
software,pattern,exclude,kind,allowed
Bittorrent,bittorrent,,forbidden,
Transmission,transmission,common|libtransmission,forbidden,
Wireshark,wireshark,,restricted,"RU78994,RM83190"
AnyDesk,anydesk,,restricted,RDU3478
Правила форматирования:
Пустое поле загружается как
NULLЗначение с запятой заключается в двойные кавычки:
"RU78994,RM83190"Регулярное выражение в колонке
excludeпередаётся как обычная строка, спецсимволы экранировать не нужно:common|libtransmission
Проверить, что модуль аналитики правильно читает файл, можно до загрузки — эндпоинт вернёт распознанные колонки:
curl -k -H "Authorization: Bearer [TOKEN]" -H "Accept: application/json" -X POST \
"https://[SERVER_ADDR]/analytics/api/v1/database/upload_metadata/" \
-F "file=@perechen.csv" -F "type=csv"
Ответ: {"result": {"items": [{"column_names": ["software", "pattern", "exclude", "kind", "allowed"], "sheet_name": null}]}}
Шаг 3. Первая загрузка справочника#
Загрузка создаёт в базе таблицу с указанным именем:
curl -k -H "Authorization: Bearer [TOKEN]" -H "Accept: application/json" -X POST \
"https://[SERVER_ADDR]/analytics/api/v1/database/[DATABASE_ID]/upload/" \
-F "file=@perechen.csv" \
-F "type=csv" \
-F "schema=public" \
-F "table_name=perechen" \
-F "already_exists=fail" \
-F 'column_data_types={"software": "string", "pattern": "string", "exclude": "string", "kind": "string", "allowed": "string"}'
Успешная загрузка возвращает 201 и {"message": "OK"}
Обязательные параметры:
table_name— имя создаваемой таблицы, в примереperechen; таблица создаётся в схеме из параметраschema(public)type— формат файла,csvalready_exists— поведение при существующей таблице:fail(ошибка),replace(заменить данные),append(добавить строки)column_data_types— JSON со строковыми типами колонок
Предупреждение
Явно указывайте типы колонок через column_data_types. При автоматическом определении полностью пустая колонка получает неверный тип — например, колонка exclude, в которой все значения пустые, создаётся как double precision. С явными типами все пять колонок создаются строковыми (TEXT)
Поддерживаются типы библиотеки pandas: string, int, float, boolean и другие
Шаг 4. Обновление справочника#
Для повторной загрузки в существующую таблицу укажите already_exists=replace — предыдущее содержимое полностью заменяется новыми данными:
curl -k -H "Authorization: Bearer [TOKEN]" -H "Accept: application/json" -X POST \
"https://[SERVER_ADDR]/analytics/api/v1/database/[DATABASE_ID]/upload/" \
-F "file=@perechen.csv" \
-F "type=csv" \
-F "schema=public" \
-F "table_name=perechen" \
-F "already_exists=replace" \
-F 'column_data_types={"software": "string", "pattern": "string", "exclude": "string", "kind": "string", "allowed": "string"}'
Примечание
При already_exists=fail и уже существующей таблице данные не меняются, запрос возвращает 422 с сообщением «Таблица уже существует…». Для регулярного обновления используйте replace
Важно
Режим replace пересоздаёт таблицу целиком. Если во внешней системе изменился не только состав строк, но и состав колонок, обновите столбцы в датасете кнопкой «Синхронизировать из источника» — см. Датасеты
Использование в виртуальном датасете#
Созданная таблица сразу доступна в SQL Lab и как источник для датасетов. В SQL виртуального датасета замените блок значений на выборку из таблицы
Было — справочник вписан в запрос:
WITH
perechen(software, pattern, exclude, kind, allowed) AS (
VALUES
('Bittorrent', 'bittorrent', NULL, 'forbidden', NULL),
('Transmission', 'transmission', 'common|libtransmission', 'forbidden', NULL),
('Wireshark', 'wireshark', NULL, 'restricted', 'RU78994,RM83190'),
('AnyDesk', 'anydesk', NULL, 'restricted', 'RDU3478')
),
matched AS (
...
)
Стало — справочник читается из таблицы:
WITH
perechen(software, pattern, exclude, kind, allowed) AS (
SELECT
software,
pattern,
exclude,
kind,
allowed
FROM public.perechen
),
matched AS (
...
)
Дальнейшая логика датасета не меняется. После обновления таблицы внешней системой при следующем выполнении запроса используется актуальное содержимое справочника
Полный пример скрипта загрузки#
Скрипт проверяет файл и загружает его с полной заменой; подходит для запуска по расписанию из внешней системы:
#!/bin/bash
set -e
SERVER="https://[SERVER_ADDR]"
TOKEN="[TOKEN]"
DATABASE_ID="1"
TABLE="perechen"
FILE="perechen.csv"
TYPES='{"software": "string", "pattern": "string", "exclude": "string", "kind": "string", "allowed": "string"}'
AUTH="Authorization: Bearer $TOKEN"
ACCEPT="Accept: application/json"
# 1. Проверка файла
curl -k -s -H "$AUTH" -H "$ACCEPT" -X POST "$SERVER/analytics/api/v1/database/upload_metadata/" \
-F "file=@$FILE" -F "type=csv"
# 2. Загрузка с полной заменой
curl -k -s -H "$AUTH" -H "$ACCEPT" -X POST "$SERVER/analytics/api/v1/database/$DATABASE_ID/upload/" \
-F "file=@$FILE" -F "type=csv" -F "schema=public" \
-F "table_name=$TABLE" -F "already_exists=replace" \
-F "column_data_types=$TYPES"
Хранение и отзыв токена#
Токен действует от имени учётной записи со всеми её правами — используйте учётную запись, созданную специально под интеграцию, и не используйте её для входа людей
Храните токен как секрет — в хранилище секретов внешней системы, не в репозитории и не в открытом виде в задачах планировщика
Срок действия можно ограничить при выпуске:
--days N— по истечении токен перестаёт действовать сам, без отзываОтзыв — командой
rude superset token revoke(по значению токена или егоuuidиз списка superset token list); отзыв применяется сразуМежду внешней системой и сервером должен использоваться HTTPS. Флаг
-kв примерах отключает проверку встроенного самоподписанного сертификата; если на сервере установлен корпоративный сертификат, проверку лучше не отключать