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

Привет, Хабр! На связи 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. 

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

После получения авторизационного токена можем протестировать некоторые методы в 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

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

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

OpenPlatfrom и ClientAPI

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

Второй доступный способ интеграции публичных 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.

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

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