Привет, Хабр! На связи Business Intelligence GlowByte.
В данной статье разберем основы интеграции FineBI c внешними системами. С помощью публичных методов API можно использовать интерфейс, управлять системой удаленно и автоматизировать бизнес-процессы. Существует несколько способов интеграции публичных API в FineBI, и в зависимости от поставленных задач разработчики должны выбрать, какой способ им более подходит, или комбинировать их между собой. Далее рассмотрим доступные варианты, разберем их отличия и особенности и протестируем некоторые методы в http-клиенте Postman.
Web API
Первый метод интеграции публичных 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.
Авторизационный токен можно получить с помощью 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-функция |
После получения авторизационного токена можем протестировать некоторые методы в Postman.
Обновление датасета
Для вызова запроса обновления датасета нужно вначале получить ID папки и название датасета. Далее согласно документации добавим параметр info, значение которого равно {"packageId":"ID папки","tableName":"Имя датасета","fullLoad":"false (инкрементальное обновление) или true (полное обновление)"}. Далее нужно заменить специальные символы в значении параметра с помощью функции EncodeURIComponent.
Давайте проверим, что будет, если выполнить данный запрос с авторизационным токеном пользователя, у которого нет доступа к папке 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
Второй доступный способ интеграции публичных API доступен с помощью дополнительных плагинов (сначала необходимо установить плагин OpenPlatform, затем ClientAPI), у плагинов есть пробный период в 90 дней. После установки в System Management появится новый раздел OpenPlatform.
OpenPlatfrom и ClientAPI
Второй доступный способ интеграции публичных API доступен с помощью дополнительных плагинов (сначала необходимо установить плагин OpenPlatform, затем ClientAPI), у плагинов есть пробный период в 90 дней. После установки в System Management появится новый раздел OpenPlatform.
Давайте изучим интерфейс раздела. На вкладке можно настроить максимальную частоту запросов, максимальное количество параллельных запросов, запись в лог, потребление памяти и др.
На вкладке Manage API представлен список доступных API-запросов, распределенных по группам. Для запроса можно настроить частоту запроса, вайт-лист, возможно также сделать запрос публичным (публичныеAPI можно вызвать без аутентификации).
Нажмем на значок карандаша -> Test, откроется встроенный http-клиент, из которого можно протестировать запросы.
На вкладке Manage Clients можно создать клиентов OpenPlatform. При создании клиента можно выбрать три режима шифрования пароля: AkSk direct authentication — без шифрования, SM2 или Digest Signature Authentication — MD5/SM3/SHA256-шифрование (рекомендуемый способ). После создания клиента перейдем в интерфейс редактирования клиента, чтобы получить ID клиента (Client ID) и пароль (Key).
На вкладке Authentication Method можно посмотреть настройки методов шифрования и при необходимости добавить собственные.
На следующей вкладке Manage Permissions можно настроить разрешения на вызов API отдельно для каждого клиента. И на последней вкладке Manage Log можем получить журнал вызванных API-запросов.
Чтобы сделать запрос в заголовках нужно передать 2 ключа: clientId (id клиента) и secret (пароль). Если для пароля клиента задано шифрование, то в заголовки вместо secret передается ключ _sign_, который рассчитывается следующим образом для Digest Signature Authentication в предобработке запроса в Postman:
Давайте протестируем некоторые запросы плагина OpenPlatform. API-запросы плагина OpenPlatform имеют вид http(s)://IP:Порт/webroot/decision/sp/client/api/v3/… В данной документации приведены все доступные запросы. Рекомендуется вначале проверить правильность выполнения запроса в интерфейса плагина.
Выдача лицензий
Следующий запрос позволяет указать типы лицензий пользователей, вместо редактирования вкладки вручную Platform User.
Список групп запросов для плагина 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:
Созданные клиенты на вкладке 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/…
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.
Программа подходит для всех, кто работает с данными, от разработчиков до руководителей.
Регистрируйтесь по ссылке
