Интеграция с модулем аналитики#

Доступно только в UEM версии

Интеграция с модулем аналитики — передача справочных данных из внешней системы в отдельную таблицу базы данных сервера RuDesktop через REST API модуля аналитики, без предоставления внешней системе прямого доступа к PostgreSQL

Назначение#

Во внешней системе часто хранится актуальный справочник, который нужен в отчётах: перечень ПО с признаками запрета, список разрешённых устройств и т.п. Если справочник меняется, каждый раз вручную переписывать SQL виртуального датасета неудобно

Интеграция работает так:

  1. На сервере выпускается токен доступа к REST API модуля аналитики — командой rude superset token create

  2. Внешняя система передаёт токен в заголовке Authorization запросов и загружает справочник в виде CSV-файла

  3. По загрузке в базе данных сервера создаётся отдельная таблица со справочником

  4. Виртуальный датасет читает справочник из этой таблицы вместо жёстко заданных значений

  5. При изменении справочника внешняя система повторяет загрузку — таблица заменяется целиком, 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 — формат файла, csv

  • already_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 в примерах отключает проверку встроенного самоподписанного сертификата; если на сервере установлен корпоративный сертификат, проверку лучше не отключать