Привет, Хабр! На связи Business Intelligence GlowByte.

В данной статье разберем основы интеграции FineBI c внешними системами. С помощью публичных методов API можно использовать интерфейс, управлять системой удаленно и автоматизировать бизнес-процессы. Существует несколько способов интеграции публичных API в FineBI, и в зависимости от поставленных задач разработчики должны выбрать, какой способ им более подходит, или комбинировать их между собой. Далее рассмотрим доступные варианты, разберем их отличия и особенности и протестируем некоторые методы в http-клиенте Postman.

Web API

Документация (EN)

Документация (CN)

Первый метод интеграции публичных API называется веб-API. Он встроен в приложение «из коробки» и не требует установки дополнительных плагинов. Чтобы лучше понять, как работает этот метод, необходимо кратко рассмотреть принцип работы FineBI. После успешного входа в систему пользователю выдается уникальный временный авторизационный токен, который обеспечивает доступ к защищенным ресурсам. Этот токен, называемый Bearer Token или «Токен на предъявителя», можно найти с помощью Инструментов разработчика. Для этого выберите любой запрос на вкладке «Сеть» и в заголовках запроса «Request Headers», «Cookie» найдите запись вида «fine_auth_token=ey…».

Символы, следующие за «fine_auth_token=», представляют собой авторизационный токен сессии. Важно помнить, что данный токен нельзя передавать другим лицам, так как это может быть небезопасно. При работе с веб-API токен передается в конце запроса в качестве параметра fine_auth_token (URL запроса имеет вид http(s)://IP:Порт/webroot/decision/xxx?param1=value1&fine_auth_token=ey…), либо в заголовках как «Authorization»: «Bearer ey…» (более безопасный вариант). Для веб-API запросов доступны только методы GET и POST.

Получение fine_auth_token из Инструментов разработчика

Пример запроса веб-API. Получение полного дерева директорий

Авторизационный токен можно получить с помощью API-запроса. URL запроса /login/cross/domain?, параметры запроса:

Параметр	Обязательный	Описание
fine_username	да	Логин
fine_password	да	Пароль
encrypted	нет	Пароль зашифрован с помощью AES? true / false
validity	да	Срок действия токена Значение -2: 14 дней Значение -1: Management System > System Management > Login > Login Timeout
callback	нет	Callback-функция

Получения токена. Авторизационный токен в поле accessToken.

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

Обновление датасета

Для вызова запроса обновления датасета нужно вначале получить ID папки и название датасета. Далее согласно документации добавим параметр info, значение которого равно {"packageId":"ID папки","tableName":"Имя датасета","fullLoad":"false (инкрементальное обновление) или true (полное обновление)"}. Далее нужно заменить специальные символы в значении параметра с помощью функции EncodeURIComponent.

При передаче JSON в URL используем функцию EncodeURIComponent

Датасет успешно обновлен. Обратите внимание, что обновление произведено особым пользователем – API

Давайте проверим, что будет, если выполнить данный запрос с авторизационным токеном пользователя, у которого нет доступа к папке Data Analysis Model. Как видим, данный запрос вернет ошибку и сообщение, что у пользователя нет разрешений на запрашиваемый объект.

Полный список доступных методов веб-API:

Обновление данных:

глобальное обновление,
обновить таблицы/папки,
инкрементальное обновление,
получить информацию про обновление.

Датасеты:

создать/изменить Self-Service/SQL/DB датасет,
переименовать датасет,
удалить датасет,
получить информацию про датасет,
получить данные из датасета,
получить SQL-запрос датасета c прямым подключением из My Analysis.

Public Data:

добавить/переименовать/удалить папку,
получить информацию про папку,
получить информацию про датасет из папки,
получить информацию из корневой папки.

Дашборды:

создать новый дашборд,
удалить/переименовать дашборд,
сохранить дашборд в песочницу (Save as),
создать публичную ссылку,
экспортировать дашборд/компонент как excel/pdf/png,
поделиться дашбордом с другими пользователями,
отменить “поделиться”,
пользователи, с которыми поделились дашбордом,
дашборды, которыми поделились со мной,
получить информацию про пользователя и созданные им дашборды,
получить информацию из вкладки Publication Management,
получить полную информацию про Subject,
получить информацию про дашборд,
получить список компонентов дашборда.

Интеграция в веб-страницу:

страница редактирования дашборда,
страница предпросмотра дашборда,
страница Public Data,
страница предпросмотра датасета в Public Data,
страница My Analysis,
страница Data в My Analysis для редактирования Self-Service Dataset.

Директории:

получить полное дерево Directory.

Полный список можно посмотреть также в документации.

Отметим, что возможности настроить, какие запросы пользователи могут выполнять или отключить использование веб-API, нет.

Итак, мы разобрали первый вариант интеграции FineBI с помощью встроенных запросов веб-API. Основной сценарий использования данного метода – интеграция FineBI c системами во внутреннем контуре, если необходимо сохранить ролевую модель для бизнес-пользователей и разработчиков.

OpenPlatfrom и ClientAPI

Документация (EN)

Второй доступный способ интеграции публичных API доступен с помощью дополнительных плагинов (сначала необходимо установить плагин OpenPlatform, затем ClientAPI), у плагинов есть пробный период в 90 дней. После установки в System Management появится новый раздел OpenPlatform.

Раздел OpenPlatform в интерфейсе FineBI. Вкладка Manage API

OpenPlatfrom и ClientAPI

Документация (EN)

Второй доступный способ интеграции публичных API доступен с помощью дополнительных плагинов (сначала необходимо установить плагин OpenPlatform, затем ClientAPI), у плагинов есть пробный период в 90 дней. После установки в System Management появится новый раздел OpenPlatform.

Раздел OpenPlatform в интерфейсе FineBI. Вкладка Manage API

Давайте изучим интерфейс раздела. На вкладке можно настроить максимальную частоту запросов, максимальное количество параллельных запросов, запись в лог, потребление памяти и др.

На вкладке Manage API представлен список доступных API-запросов, распределенных по группам. Для запроса можно настроить частоту запроса, вайт-лист, возможно также сделать запрос публичным (публичныеAPI можно вызвать без аутентификации).

Копируем API по новому URL и делаем его публичным, ставя галочку PubliсAPI

Нажмем на значок карандаша -> Test, откроется встроенный http-клиент, из которого можно протестировать запросы.

Встроенный http-клиент плагина OpenPlatform

На вкладке Manage Clients можно создать клиентов OpenPlatform. При создании клиента можно выбрать три режима шифрования пароля: AkSk direct authentication — без шифрования, SM2 или Digest Signature Authentication — MD5/SM3/SHA256-шифрование (рекомендуемый способ). После создания клиента перейдем в интерфейс редактирования клиента, чтобы получить ID клиента (Client ID) и пароль (Key).

Интерфейс редактирования клиента OpenPlatform

На вкладке Authentication Method можно посмотреть настройки методов шифрования и при необходимости добавить собственные.

Метод шифрования MD5 в Digest Signature Authentication по умолчанию

На следующей вкладке Manage Permissions можно настроить разрешения на вызов API отдельно для каждого клиента. И на последней вкладке Manage Log можем получить журнал вызванных API-запросов.

Чтобы сделать запрос в заголовках нужно передать 2 ключа: clientId (id клиента) и secret (пароль). Если для пароля клиента задано шифрование, то в заголовки вместо secret передается ключ _sign_, который рассчитывается следующим образом для Digest Signature Authentication в предобработке запроса в Postman:

Шифрование ключа алгоритмом MD5 для Digest Signature Authentication

Необходимые заголовки для вызова API-запросов OpenPlatform

Давайте протестируем некоторые запросы плагина OpenPlatform. API-запросы плагина OpenPlatform имеют вид http(s)://IP:Порт/webroot/decision/sp/client/api/v3/… В данной документации приведены все доступные запросы. Рекомендуется вначале проверить правильность выполнения запроса в интерфейса плагина.

Выдача лицензий

Следующий запрос позволяет указать типы лицензий пользователей, вместо редактирования вкладки вручную Platform User.

Выдаем пользователю demo лицензию разработчика отчетов

Список групп запросов для плагина OpenPlatform:

API данных для отчетов FineReport (получение данных из отчетов, запись в Data, Entry) + отправить SQL-запрос к БД из Data Connections,
Управление департаментами,
Управление позициями,
Получить список отчетов FineReport,
Управление ролями,
Управление разрешениями,
Управление подключениями,
Управление сервер-датасетами,
Управление Directory,
Получение логов в виде JSON с вкладки Platform Log,
Управление системой оповещения,
Управление запланированными задачами,
Управление пользователями.

Далее разберем плагин ClientAPI, который расширяет список доступных запросов OpenPlatform. Многие запросы плагина ClientAPI повторяют запросы Web API. Краткий список запросов по темам, все запросы в документации:

Управление разрешениями (папки/датасеты в Public Data, строки/столбцы, дашборды),
Датасеты/обновления/папки в Public Data,
Управление песочницей My Analysis,
“Поделиться” и коллабория дашбордов.

API-запросы ClientAPI имеют вид http(s)://IP:Порт/webroot/decision/sp/client/api/v3/bi/… Давайте попробуем обновить SQL-датасет, используя запрос, предоставляемый плагином ClientAPI:

Запрос на обновление SQL-датасета в режиме экстракт

Датасет успешно обновлен. Обратите внимание, что в интерфейсе обновление запущено от УЗ админа, который создал клиента

Созданные клиенты на вкладке Manage Clients не являются обычными пользователями платформы. На них не распространяется ролевая модель, поэтому ограничить доступ клиентов к каким-то объектам нельзя (клиенты обладают правами администратора), можно ограничить только доступ к самим запросам.

Вы могли заметить, что группы Client API две: Client API for FineBI6 V3 и Client API for FineBI6 V3 by fine_auth_token. API-запросы второй группы используют авторизацию токеном fine_auth_token, как веб-API, а не через клиентов. Аналогично есть плагин для API-запросов OpenPlatform, который использует авторизационный токен. Вызов вернет ошибку, если у пользователя (не клиента!), который его вызывает нет разрешений на запрашиваемые разделы или действия (как в веб-API). Схема таких API-запросов: http(s)://IP:Порт/webroot/decision/sp/client/api/module/v3/…

http(s)://IP:Порт/webroot/decision/sp/client/api/module/v3/bi/…

Группы запросов с подписью Platform Login Authentication

Получаем список подключений с авторизационным токеном пользователя admin — Получаем список подключений с авторизационным токеном пользователя *admin*

Запрос с токеном пользователя demo, без доступа к разделу Data Connections — Запрос с токеном пользователя *demo*, без доступа к разделу Data Connections

P.S.: Помимо основного метода аутентификации для вызова запросов OpenPlatform и ClientAPI с передачей в заголовки clientId и secret / _sign_, есть также возможность входа с временным “универсальным” токеном. По URL-запросу /sp/client/spi/token сервер вернет access_token, который можно будет передать как параметр или в заголовках для вызова других запросов. Сценарий использования данного метода входа до конца не понятен. Было предположение, что с помощью “универсального” токена можно вызывать веб-API запросы, но нет, не сработало.

Подведем итоги. Доступные API-запросы покрывают значительную часть всего функционала FineBI. Строить дашборды по API, конечно, не получится, но производить практически все администрирование можно не заходя в приложение. Также API открывают широкий простор для “творчества” (примеры от вендора). Пример несложной веб-страницы, которую удалось собрать.

Надеемся, наш эксперимент был наглядным и полезным. Больше полезной информации о работе FineBI вы найдете в нашем сообществе FineBIChat.

Пользуясь случаем, хочу пригласить всех 16 сентября на образовательный проект GlowByte и DataYoga по работе с BI-инструментом FineBI! 🐲

10 дней теории, практики и вдохновения от ведущих российских компаний. Узнайте о возможностях анализа и визуализации данных в FineBI, а также получите практические советы по оптимизации BI-практики от GlowByte.

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

Регистрируйтесь по ссылке

Использование API в FineBI