Biconnector 26.1100.0–26.1200.0: ClickHouse, ИИ-инструменты для BI и статистика внешних систем по кнопке

В коробку пришли сразу две версии BI-коннектора, 26.1100.0 и 26.1200.0. Обе собраны 24 августа с разницей в 28 минут. Прошлую, 26.1050.0, мы разбирали здесь. В 26.1100.0 за выключенными опциями появились ClickHouse как внешний источник, расчёт агрегации на стороне источника и демо-отчёты. 26.1200.0 добавил инструменты ИИ-ассистента для BI-конструктора и защиту bi_builder.php от нагрузки.

Свой код проверьте, если вызываете KeyManager::save() или Superset\KeyManager::deleteKey(). С 26.1200.0 журнал по умолчанию не пишет запросы Power BI и других внешних систем и хранит записи только неделю, так что отчёты по нему тоже придётся пересмотреть.

Новое

ClickHouse как внешний источник (26.1100.0)

Новый тип внешнего SQL-источника ходит в ClickHouse через его HTTP-интерфейс. Он доступен там же, где остальные внешние SQL-источники, то есть в коробке с включённым BI-конструктором, и только при опции bi_clickhouse_source:

        <?php declare(strict_types=1);

use Bitrix\Main\Config\Option;

Option::set('biconnector', 'bi_clickhouse_source', 'Y');

    

Шифровать ли соединение, решает схема в адресе хоста: без порта http:// идёт на 8123, https:// на 8443. Соединение только читает. Каждый запрос уходит с readonly=2, пишущие методы ClickhouseConnection бросают исключение, а query() не отдаёт запрос в slave-пул портала. Ответ приходит в формате JSONCompactEachRowWithNamesAndTypes и читается построчно, а 64-битные целые и decimal коннектор просит строками, чтобы PHP не округлил их до double. При выключенной опции источник этого типа не создать и прямым запросом, мимо селектора: тип проверяет SourceManager.

Агрегацию считает источник (26.1100.0)

Плагин BI-конструктора может прислать в запросе к bi_builder.php блок aggregation с группировками, агрегатами, having, сортировкой и лимитом групп. Портал проверяет блок и строит GROUP BY в источнике, так что клиенту приходят уже группы. Блок применяется целиком или не применяется вовсе, это видно по заголовку X-Bitrix-Bi-Aggregation-Applied. Возможности источника отдаёт ?desc&caps=1. Диалект агрегации пока есть только у ClickHouse, остальные источники считают по-старому. Включает механизм опция aggregation_pushdown при включённом конструкторе.

Все ответы с данными заодно получили заголовки X-Bitrix-Bi-Filters-Applied и X-Bitrix-Bi-Where-Fingerprint, тело ответа не изменилось.

Инструменты ИИ для BI-конструктора (26.1200.0)

К набору инструментов для дашбордов добавились bi_charts, bi_datasets и bi_tables, всего 21 новый инструмент. Они читают таблицы, датасеты и графики, создают графики, дашборды, виртуальные и SQL-датасеты, публикуют и удаляют их. ExecuteSqlTool выполняет SELECT через Superset, отдаёт до 10 000 строк и требует права на редактирование отчётов. На пользователя приходится не больше 60 вызовов в минуту. Модуль регистрирует наборы в своём .settings.php секцией aiassistant.marta, если опция bitrixgpt_bi_constructor равна Y. Каждый набор наследует BaseToolSet из aiassistant и описывает getCode(), getMetadata(), getUsesTools() и getAdditionalRequiredModules(). Такую же секцию объявляют и другие модули коробки, среди них crm, im, mail и tasks. При этом модуля aiassistant в коробочном эталоне нет, так что в коробке инструменты пока не заработают.

Лимиты нагрузки на bi_builder.php (26.1200.0)

Защиту включает опция bi_builder_load_protection, по умолчанию она выключена. Скрипту даётся bi_builder_script_time_limit секунд (60, но не больше max_execution_time), SQL-запросу bi_builder_sql_time_limit (60), одновременно выполняется bi_builder_concurrency_limit запросов (3, максимум 10). Без свободного слота клиент получает HTTP 429 с {"error":"TOO_MANY_REQUESTS"}.

        <?php declare(strict_types=1);

use Bitrix\Main\Config\Option;

Option::set('biconnector', 'bi_builder_load_protection', 'Y');
Option::set('biconnector', 'bi_builder_concurrency_limit', '5');
Option::set('biconnector', 'bi_builder_sql_time_limit', '30');

    

Слоты сделаны на именованных блокировках БД biconnector_data_N, как семафор превью TIFF в disk 26.1175.0. Лимит SQL ставится на сессию соединения (max_execution_time в MySQL, max_statement_time в MariaDB, statement_timeout в PostgreSQL), после запроса прежнее значение возвращается.

Демо-отчёты, мобильный просмотр и мелкие API

Опция bi_demo_reports (26.1100.0) добавляет системным отчётам пункт меню грида «Посмотреть демо отчёт», он открывает /bi/dashboard/demo/<код>/. Гостевой токен выдаёт прокси Битрикс24, и запрос обходит проверки тарифа и готовности собственного Superset портала. На self-hosted Superset демо недоступно. С 26.1100.0 компонент biconnector.apachesuperset.dashboard.detail с параметром IS_MOBILE рендерит любой исход через шаблон mobile.php для нативного приложения, а список отчётов для него отдаёт Public\Provider\SupersetDashboardListProvider.

Public\Command\Dashboard\InstallDashboardCommand ставит дашборд из статуса NOT_INSTALLED и проверяет право просмотра (26.1100.0). В 26.1200.0 датасет bizproc_task получил поля USER_STATUS_ID, USER_STATUS_NAME и USER_STATUS из b_bp_task_user, а CSV-датасет запоминает разделитель, кодировку и признак строки заголовков, с которыми файл разобрался.

Что сломается

KeyManager::save() возвращает Result (26.1200.0)

\Bitrix\BIConnector\KeyManager::save(array $data) раньше отдавал int с ID при успехе и ErrorCollection при ошибке. Теперь это Bitrix\Main\Result, а ID лежит в getData()['ID']. Проверки через is_int() и instanceof ErrorCollection сломаются:

        <?php declare(strict_types=1);

use Bitrix\BIConnector\KeyManager;
use Bitrix\Main\Loader;

Loader::requireModule('biconnector');

$result = KeyManager::save([
    'USER_ID' => $adminId,
    'ACTIVE' => true,
    'USERS' => [$adminId],
]);
if (!$result->isSuccess()) {
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}
$keyId = (int)$result->getData()['ID'];

    

Новый KeyManager::deleteKey(int $id): Result удаляет ключ вместе с привязками пользователей. А Superset\KeyManager::deleteKey(string) переименован в deleteAccessKey(string).

Журнал пишет внешние BI-системы только по включению (26.1200.0)

Запросы всех сервисов, кроме Apache Superset, попадают в b_biconnector_log только пока открыто 24-часовое окно сбора. Его включает админ на странице статистики использования или код:

        <?php declare(strict_types=1);

\Bitrix\BIConnector\ExternalStatLoggerManager::enable(); // сбор запросов внешних систем на 24 часа

    

Дата последней активности ключа обновляется как раньше. Сам журнал теперь хранится 7 дней вместо 30. Записи старше недели, оставшиеся от прежнего срока, по докблоку удалит после обновления одноразовый агент UsageStatTailCleanUpAgent. Если ваша выгрузка читает журнал, забирайте данные чаще раза в неделю.

Цифры по отгрузкам изменятся (26.1200.0)

В датасете sale_document_saleorder_item отгрузки и складские строки теперь идут через одну цепочку JOIN. Раньше позиция корзины, отгруженная несколькими реализациями, получала складские строки всех отгрузок и суммировалась. Отчёты по этому датасету после обновления покажут другие числа.

Power BI видит строку с ошибкой (26.1200.0)

Если запрос падает, когда часть ответа уже отдана, сервис Power BI дописывает в конец массива строку {"error": "…"} (с errorMessage, если у ошибок есть описание) и закрывает массив. Свой парсер ответа научите её распознавать.

Проверьте наследников и свои реализации

В Integrator\IntegratorInterface в 26.1100.0 появился getDemoEmbeddedCredentials(string $reportCode, string $lang), а в 26.1200.0 ещё 11 методов (createChart, executeSql, listTables, getTableMetadata, createVirtualDataset, createDatasetFromSql и другие), так что своя реализация интерфейса упадёт с fatal error, пока их нет. В 26.1200.0 удалён базовый класс действий грида Superset\Grid\Row\Action\Dashboard\BaseDashboardAction, замена — Superset\Grid\Row\Action\FormatMenuAction. В 26.1100.0 Connector\Base::applyDateFilter() получил четвёртый параметр bool &$canBeFiltered = true, и наследник со старой сигнатурой метода тоже не загрузится.

Контроллер внешних датасетов в 26.1200.0 требует доступа к BI-конструктору и интранет-пользователя. Экстранет к нему больше не пустят.

БД

В b_biconnector_log (ORM Internal\Model\UsageStatTable) с 26.1100.0 есть READ_ROWS и READ_BYTES, сколько строк и байт реально прочитал источник. ROW_NUM по-прежнему считает строки, отданные клиенту, а при агрегации в источнике эти числа расходятся на порядки. Если источник статистику не сообщает, в новых колонках NULL. В 26.1200.0 у b_biconnector_external_dataset появились CSV_DELIMITER, CSV_ENCODING и CSV_HAS_HEADERS.

Мелочи и находки

• ExecuteSqlTool (26.1200.0) читает SQL нефильтрованным, через getJsonList()->getRaw('arguments') или из сырого тела запроса. По комментарию, иначе проактивный фильтр превращает SELECT в SEL ECT, а FROM в FR OM.
• Докблок UsageStatTailCleanUpAgent (26.1200.0) объясняет, почему чистку делает агент: апдейтер работает до копирования файлов модуля, и на диске в этот момент ещё старый порог. Агент стартует уже на новом коде и удаляет себя, вернув пустую строку.
• Агрегированный ответ bi_builder.php (26.1100.0) сначала пишет через ob_start() с колбэком в php://temp/maxmemory:1048576, а заголовок X-Bitrix-Bi-Aggregation-Applied: Y ставит только после выполнения запроса. Число групп не ограничено, держать такое тело в буфере вывода нельзя.