Руководство по использованию DBAPI

Введение в продукт

• DBAPI — это инструмент для разработчиков хранилищ данных, позволяющий с минимальными усилиями создавать HTTP‑интерфейсы: достаточно написать SQL‑запрос на странице и задать параметры. Он помогает быстро разрабатывать серверные API, особенно подходя для создания бэкендов BI‑отчётов и интерфейсов больших панелей визуализации данных.

• DBAPI является центром управления всеми корпоративными API и платформой для предоставления внешних сервисов данных. Он обеспечивает динамическое создание и публикацию API, единое управление интерфейсами, а также возможности администрирования клиентских приложений: мониторинг вызовов API со стороны клиентов и контроль их прав доступа.

Демо‑версия

Основные характеристики

• ✅ Готов к использованию: не требует программирования и не зависит от стороннего ПО (в автономном режиме требуется только Java‑среда).
• ✅ Лёгкая установка: минимальное потребление ресурсов; стабильная работа возможна на сервере с 2 ядрами и 4 ГБ ОЗУ.
• ✅ Поддержка множества платформ: работает в standalone‑режиме и в кластере, поддерживает Windows, Linux и macOS.
• ✅ Динамическая конфигурация: позволяет динамически создавать и изменять API и источники данных, с горячей перезагрузкой без прерывания работы.
• ✅ Контроль прав доступа: управление правами доступа на уровне API, поддержка IP‑белых и чёрных списков.
• ✅ Широкая совместимость: поддерживает все реляционные базы данных, использующие JDBC (MySQL, SQL Server, PostgreSQL, Oracle, Hive, Dameng, Kingbase, Doris, OceanBase, GaussDB и др.).
• ✅ Динамический SQL: поддерживает динамический SQL в стиле MyBatis, интегрированные функции редактирования, выполнения и отладки запросов.
• ✅ Полная поддержка: SELECT, INSERT, UPDATE, DELETE и вызов хранимых процедур.
• ✅ Управление транзакциями: поддержка выполнения нескольких SQL‑запросов с гибким управлением транзакциями.
• ✅ Расширяемость плагинами: богатый набор плагинов для кэширования, преобразования данных, обработки ошибок, обработки параметров и др.
• ✅ Простота миграции: импорт/экспорт конфигураций API для удобной переносимости между тестовой и продакшн‑средами.
• ✅ Обработка параметров: поддержка передачи параметров через API и сложных вложенных JSON‑параметров, а также валидация параметров.
• ✅ Мониторинг и статистика: просмотр журнала вызовов API и анализ информации о доступе.
• ✅ Контроль трафика: механизм ограничения скорости обращений к API.
• ✅ Организация сложных процессов: поддержка составных API‑процессов.
• ✅ Открытая интеграция: предоставляет OpenAPI‑интерфейс для лёгкой интеграции с другими системами.

Основные понятия

Исполнитель

Исполнитель — это абстракция для выполнения бизнес‑логики API. В настоящее время поддерживаются следующие типы:

Тип исполнителя	Описание
SQL‑исполнитель	Выполняет SQL‑запросы в базе данных и возвращает результаты.
Elasticsearch‑исполнитель	Выполняет запросы на языке Elasticsearch DSL и возвращает результаты.
HTTP‑исполнитель	Работает как HTTP‑клиент, перенаправляя HTTP‑запросы и получая ответ.

[!ВНИМАНИЕ]
В бесплатной версии доступен только SQL‑исполнитель.

Группа API

Позволяет организовать API по категориям, объединяя связанные между собой API в одну группу для упрощённого управления и поиска.

Клиент

Это приложение, которое обращается к API платформы, например, Python или Java. Каждому клиенту присваивается уникальный идентификатор clientId и секретный ключ secret, которые назначаются администратором системы и используются для получения доступа к API.

Быстрый старт

Авторизация в системе

Авторизуйтесь с помощью стандартных учётных данных: admin/admin.

Настройка источников данных

1. Перейдите в раздел управления источниками данных и нажмите «Создать источник данных».

   

2. Заполните данные подключения к базе данных и сохраните.

   

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

   

[!ВНИМАНИЕ]

• Поддерживаются все базы данных, работающие по протоколу JDBC.
• При использовании других СУБД или Oracle необходимо вручную указать класс JDBC‑драйвера и поместить соответствующий JAR‑файл в директорию extlib или lib, после чего перезапустить сервис (в кластерной конфигурации — на всех узлах).
• В директории lib уже содержатся драйверы MySQL, SQL Server, PostgreSQL и ClickHouse; при несоответствии версий замените их вручную.
• Рекомендуется помещать собственные JAR‑файлы драйверов в директорию extlib для унифицированного управления.

Создание API

1. Создание группы API

• Перейдите в раздел управления API и нажмите кнопку «Создать группу API» слева.

  

• В открывшемся окне укажите название группы и сохраните.

  

• После сохранения на левой панели появится новая группа; нажав кнопку «Подробнее», можно редактировать или удалить её.

  

2. Создание API

• В выбранной группе нажмите кнопку «Создать API» и перейдите к настройкам.

  

• Перейдите во вкладку «Основные сведения» и заполните базовые данные API.

  

  Права доступа: открытые API доступны всем, закрытые — только по токену клиента (для простоты тестирования выберем открытый доступ).

  Путь: можно задать произвольную многоуровневую структуру, например /a/b/c, /a/b/c/d.

  Content-Type: если API использует формат application/x-www-form-urlencoded, необходимо указать параметры; если используется application/json, нужно ввести пример JSON‑параметров.

• Перейдите к настройкам исполнителя и укажите необходимые данные.

  

  Написание SQL: используется синтаксис динамического SQL MyBatis (без внешних тегов <select>, <insert>, <delete>, <update>); параметры обозначаются как #{} или ${}. Подробности см. в документации по динамическому SQL ([dynamicSQL/]).

  Управление транзакциями: по умолчанию транзакции отключены; для операций INSERT, UPDATE, DELETE рекомендуется включать транзакции, чтобы в случае ошибки выполнялся откат. Если в API несколько SQL‑запросов, включённые транзакции объединят их в один блок.

  Важно: для баз данных, не поддерживающих транзакции, таких как HIVE, не включайте транзакции — это приведёт к ошибке.

  Преобразование данных: если требуется преобразование данных, укажите имя Java‑класса плагина; если плагин нуждается в параметрах, укажите их. Подробности см. в документации по плагинам ([plugin/]).

  Поддержка нескольких SQL‑запросов: нажмите кнопку «Добавить», чтобы открыть дополнительное окно для написания SQL‑запросов. В одном API можно выполнять несколько запросов, а результаты объединяются в единый ответ — например, при реализации пагинации, когда требуется одновременно получить детали и общее количество записей. В одном окне можно написать только один SQL‑запрос.

  

[!ПРИМЕЧАНИЕ]
Если в одном исполнителе содержится несколько SQL‑запросов, каждый из них будет связан с отдельным плагином преобразования данных; плагины всегда применяются к результатам одного конкретного запроса.

• Нажмите кнопку «Развернуть окно», чтобы перейти к отладке SQL‑запросов.

  

• Нажмите «Выполнить SQL», чтобы запустить запрос; если в запросе есть параметры, укажите их.

  

• Нажмите «Глобальные плагины», чтобы задать глобальные настройки.

  

  Кэширование: если требуется кэширование, укажите имя Java‑класса плагина; если плагин нуждается в параметрах, укажите их.
  Оповещение: если требуется оповещение о сбоях, укажите имя Java‑класса плагина; если плагин нуждается в параметрах, укажите их.
  Глобальное преобразование данных: если требуется преобразование данных, укажите имя Java‑класса плагина; если плагин нуждается в параметрах, укажите их.
  Обработка параметров: если требуется обработка параметров, укажите имя Java‑класса плагина; если плагин нуждается в параметрах, укажите их.

  Подробности см. в документации по плагинам ([plugin/]).

• Нажмите «Сохранить», чтобы завершить создание API; затем перейдите в меню API, чтобы вернуться к списку.

3. Публикация API

• Нажмите кнопку «Подробнее» рядом с API, чтобы открыть кнопку «Опубликовать». Нажмите её, чтобы опубликовать API.

  

• Нажмите кнопку «Подробнее» рядом с API, чтобы открыть кнопку «Тестировать запрос». Нажмите её, чтобы перейти к тестированию.

  

• Нажмите кнопку «Отправить запрос», чтобы отправить запрос; если есть параметры, укажите их.

  

Управление клиентами

• Перейдите в меню «Клиенты» и нажмите кнопку «Создать клиента».

  

• Заполните данные клиента и сохраните.

  

После создания клиента система сгенерирует clientId и secret; администратор должен сообщить эти данные клиенту (пользователю API).

Клиент использует свой clientId и secret для обращения к интерфейсу http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx, чтобы динамически получить токен. Только с этим токеном клиент сможет получить доступ к закрытым API (при условии, что администратор уже предоставил этому клиенту права доступа).

При создании клиента обязательно укажите срок действия токена; каждый последующий запрос будет использовать токен с установленным сроком действия. По истечении этого срока потребуется повторно запросить новый токен.

[!ПРИМЕЧАНИЕ]
Если хотите сделать токен постоянным, установите очень большой срок действия, например, 100 лет.

• Нажмите кнопку «Авторизация», чтобы предоставить клиенту права доступа к API.

  

• Выберите нужную группу и сохраните.

  

Инструкция по работе с токеном

• Интерфейс для получения токена:

  http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx

• При обращении к закрытым API значение токена должно быть передано в заголовке Authorization. Для открытых API это не требуется.

• Пример вызова из Python:

import requests
headers = {"Authorization": "5ad0dcb4eb03d3b0b7e4b82ae0ba433f"}
re = requests.post("http://127.0.0.1:8520/api/userById", {"idList": [1, 2]}, headers=headers)
print(re.text)

• Измените ранее созданный API на закрытый, затем снова нажмите кнопку «Тестировать запрос».

  

• Теперь при нажатии «Отправить запрос» вы обнаружите, что API недоступен.

  

• Введите clientId и secret, нажмите кнопку, чтобы получить токен.

  

• Вставьте этот токен в заголовок Authorization и снова нажмите «Отправить запрос» — теперь API доступен.

  

Настройка IP‑фаервола

Включение фаервола позволяет фильтровать доступ по IP‑адресам.

Мониторинг

DBAPI может работать, опираясь только на метабазу (postgresql/mysql/sqlite), однако если вам также необходимы функции мониторинга на странице (отслеживание записей вызовов API, количества обращений, уровня успешности и т. п.), потребуется дополнительная база логов (ее необходимо настроить самостоятельно) для хранения журналов доступа к API; рекомендуется использовать clickhouse/mysql/postgresql/doris, хотя можно применять и другие реляционные СУБД.

В настоящее время в каталоге sql предоставлены скрипты инициализации баз данных логов для clickhouse, mysql и postgresql.

NOTE

Если функция мониторинга вам не нужна, можно обойтись без создания базы логов и в файле conf/application.properties установить параметр access.log.writer=null. По умолчанию этот параметр уже имеет значение null.

Способы сбора логов

1. Сбор через файлы: По умолчанию DBAPI записывает журналы доступа к API в файл на диске — logs/dbapi-access.log; пользователи могут самостоятельно использовать инструменты вроде datax, flume и др. для переноса этих логов в базу данных логов.

2. Прямое подключение к базе данных: Если в файле conf/application.properties задано access.log.writer=db, то DBAPI асинхронно записывает журналы доступа непосредственно в базу данных логов; такой способ подходит для случаев с относительно небольшим объёмом логов.

3. Кэширование через Kafka: При настройке параметра access.log.writer=kafka в файле conf/application.properties DBAPI отправляет журналы доступа в Kafka; пользователю предстоит самостоятельно извлекать эти данные из Kafka и загружать их в базу логов. Этот метод подходит для больших объёмов логов, поскольку Kafka позволяет осуществлять буферизацию данных.

NOTE

В этом случае необходимо указать адрес Kafka в файле conf/application.properties.

Кроме того, DBAPI предоставляет встроенный инструмент для чтения логов из Kafka и записи их в базу данных логов — используйте скрипт bin/dbapi-log-kafka2db.sh.

Сводные данные мониторинга

• Нажав на меню «Мониторинг», вы можете просматривать статистику вызовов API.

  

Просмотр записей вызовов интерфейса

• Перейдя на вкладку «Подробности», можно выполнять поиск по записям вызовов API.

  

Другие функции

Экспорт документации интерфейса

• В меню API нажмите кнопку «Инструменты», затем выберите «Экспорт документации интерфейса».

  

Плагинная система

DBAPI предлагает пять типов плагинов; скачать их можно на рынке плагинов. Если вы хотите разработать собственный плагин, обратитесь к документации по плагинам.

Плагин кэширования

• Кэширует результаты работы исполнителей: например, для SQL‑исполнителя кэшируются результаты запросов, что позволяет избежать частых обращений к базе данных и снижает нагрузку на неё.
• Логика кэширования реализуется самим пользователем; можно сохранять данные в ehcache, redis, mongodb и других системах.
• Если данные не найдены в кэше, выполняется запрос к исполнителю, после чего результат снова помещается в кэш.

Сценарий с несколькими SQL‑запросами

Если в одном исполнителе содержится несколько SQL‑запросов, плагин кэширования объединяет результаты всех запросов (если для отдельного запроса настроен плагин преобразования, он сначала обрабатывает результат) и кэширует полученный набор данных.

Плагин оповещений

• При возникновении ошибок внутри API плагин оповещений отправляет уведомления — по электронной почте, SMS, DingTalk, Feishu, WeCom и другим каналам.
• Логика оповещений разрабатывается пользователем самостоятельно.

Плагин преобразования данных

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

Сценарий с несколькими SQL‑запросами

Если в одном исполнителе содержится несколько SQL‑запросов, для каждого запроса настраивается отдельный плагин преобразования данных; при этом каждый плагин работает только с результатами соответствующего запроса.

Глобальный плагин преобразования данных

• По умолчанию ответ API имеет формат {success: true, msg: xxx, data: xxx}.
• В некоторых случаях требуется изменить формат ответа; например, фреймворк низкоуровневого кодирования для фронтенда AMIS требует, чтобы ответ API обязательно содержал поле status. В таких случаях применяется глобальный плагин преобразования данных, который изменяет формат всего ответа API.

Разница между плагином преобразования данных и глобальным плагином

Плагин преобразования данных изменяет формат результатов работы исполнителя (например, результаты SQL‑запроса), тогда как глобальный плагин преобразования данных меняет формат всего ответа API.

Плагин обработки параметров

• Позволяет выполнять пользовательскую обработку входящих параметров:
• Например, переводить все значения параметров в верхний регистр;
• Или, если API принимает зашифрованные параметры, реализовать логику дешифрования.

Поддержка версий

Плагин обработки параметров стал доступен начиная с версии Personal Edition 4.0.16 и Enterprise Edition 4.1.10.

Примечания

Поддержка источников данных

• Если вы используете Oracle или другие типы источников данных, необходимо вручную поместить соответствующие JDBC‑драйверы в каталог extlib или lib после развертывания DBAPI (в случае кластерной установки jar‑файлы нужно добавить на каждом узле).
• Рекомендуется размещать драйверы в каталоге extlib для удобства централизованного управления.

Стандарты написания SQL‑запросов

• Как и в случае динамического SQL‑синтаксиса MyBatis, поддерживаются параметры #{} и ${}; можно ориентироваться на документацию по динамическому SQL‑синтаксису. Не требуется дополнительно заключать запрос в теги <select>, <update> и т. п. — пишите непосредственно текст SQL.
• Обратите внимание: как и в MyBatis, знаки «меньше» следует записывать как <, а не <.