Карьера
РУ
Использование API в FineBI
В данной статье разберем основы интеграции 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?, параметры запроса:
Получения токена. Авторизационный токен в поле accessToken.
После получения авторизационного токена можем протестировать некоторые методы в Postman.

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

Для вызова запроса обновления датасета нужно вначале получить ID папки и название датасета. Далее согласно документации добавим параметр info, значение которого равно {"packageId":"ID папки","tableName":"Имя датасета","fullLoad":"false (инкрементальное обновление) или true (полное обновление)"}. Далее нужно заменить специальные символы в значении параметра с помощью функции EncodeURIComponent.
Получаем ID папки из URL
При передаче 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
Давайте изучим интерфейс раздела. На вкладке можно настроить максимальную частоту запросов, максимальное количество параллельных запросов, запись в лог, потребление памяти и др.
Настройки запросов плагина OpenPlatform
На вкладке Manage API представлен список доступных API-запросов, распределенных по группам. Для запроса можно настроить частоту запроса, вайт-лист, возможно также сделать запрос публичным (публичныеAPI можно вызвать без аутентификации).
Копируем API по новому URL и делаем его публичным, ставя галочку PubliсAPI
Нажмем на значок карандаша -> Test, откроется встроенный http-клиент, из которого можно протестировать запросы.
Раздел OpenPlatform в интерфейсе FineBI. Вкладка Manage API
На вкладке 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-запросов.
Разрешения на вызов API для клиентов
Вкладка Manage Log
Чтобы сделать запрос в заголовках нужно передать 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:
Получение ID SQL-датасета
Запрос на обновление 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
Запрос с токеном пользователя 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.

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

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

Теги: