Коннектор, тип sql

Коннекторы с типом sql используются для выборки данных из Систем Управления Базами Данных (СУБД). KUMA поддерживает работу с несколькими типами баз данных. При создании коннектора с типом sql вам нужно указать значения для общих параметров коннектора и отдельных параметров подключения к базе данных. Доступные параметры коннектора с типом sql описаны в таблицах ниже.

Вкладка Основные параметры

Параметр

Описание

Название

Уникальное имя ресурса. Максимальная длина имени составляет до 128 символов в кодировке Unicode.

Обязательный параметр.

Тенант

Название тенанта, которому принадлежит ресурс.

Обязательный параметр.

Тип

Тип коннектора – sql.

Обязательный параметр.

Теги

Запрос по умолчанию

SQL-запрос, который выполняется при подключении к базе данных.

Обязательный параметр.

Переподключаться к БД каждый раз при отправке запроса

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

Интервал запросов, сек.

Интервал выполнения SQL-запросов в секундах. Значение по умолчанию: 10 секунд.

Соединение

Параметры подключения к базе данных:

Тип базы данных – тип базы данных для подключения. При выборе типа базы данных в поле URL отображается префикс, соответствующий протоколу взаимодействия. Например, для типа базы данных ClickHouse в поле URL отображается префикс clickhouse://.
Секрет отдельно – флажок, позволяющий просматривать информацию о подключении.
URL – URL-адрес подключения. Вы сможете просматривать информацию о подключении и вам не придется повторно создавать большое количество подключений при изменении пароля учетной записи, которую вы использовали для подключений.
При создании подключений могут неправильно обрабатываться строки с учетными данными, содержащими специальные символы. Если при создании подключения возникает ошибка, но вы уверены в том, что указали правильные значения параметров, укажите специальные символы в процентной кодировке.

Коды специальных символов

!

#

$

%

&

'

(

)

*

+

%21

%23

%24

%25

%26

%27

%28

%29

%2A

%2B

,

/

:

;

=

?

@

[

]

\

%2C

%2F

%3A

%3B

%3D

%3F

%40

%5B

%5D

%5C

Следующие специальные символы не поддерживаются в паролях доступа к базам SQL: пробел, [, ], :, /, #, %, \.

Если вы установили флажок Секрет отдельно, вы можете выбрать существующий URL-адрес или создать новый URL-адрес. Для создания нового URL-адреса выберите значение Создать.

Если вы хотите изменить параметры существующего URL-адреса, нажмите рядом с ним на значок карандаша .
Секрет – секрет urls, в котором хранится список URL-адресов для подключения к базе данных. Это поле отображается, если вы установили флажок Секрет отдельно.
Столбец идентификатора – название столбца, содержащего идентификатор для каждой строки таблицы.
Обязательный параметр.
Начальное значение идентификатора – значение в столбце идентификатора для определения строки, с которой требуется начать считывание данных из SQL-таблицы.
Запрос – дополнительный SQL-запрос, который выполняется вместо SQL-запроса по умолчанию.
Интервал запросов, сек – интервал выполнения SQL-запросов в секундах. Указанный интервал используется вместо интервала, указанного по умолчанию для коннектора. Значение по умолчанию: 10 секунд.

Вы можете добавить несколько подключений или удалить подключение. Для добавления подключения нажмите на кнопку + Добавить подключение. Для удаления подключения нажмите рядом с ним на значок удаления cross-black .

Описание

Описание ресурса. Максимальная длина описания составляет до 4000 символов в кодировке Unicode.

Вкладка Дополнительные параметры

Параметр	Описание
Отладка	Переключатель, включающий логирование ресурса. По умолчанию этот переключатель выключен.
Кодировка символов	Кодировка символов. По умолчанию выбрано значение UTF-8. KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.

Параметр

Описание

Отладка

Переключатель, включающий логирование ресурса. По умолчанию этот переключатель выключен.

Кодировка символов

Кодировка символов. По умолчанию выбрано значение UTF-8.

KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.

В рамках одного коннектора вы можете создать подключение для нескольких поддерживаемых баз данных. Если коллектор с коннектором типа sql не удаётся запустить, вам нужно проверить, пуст ли state-файл /opt/kaspersky/kuma/collector/<идентификатор коллектора>/sql/state-<идентификатор файла>. Если state-файл пуст, вам нужно его удалить и перезапустить коллектор.

Поддерживаемые типы SQL и особенности их использования

Поддерживаются следующие типы SQL:

MSSQL.
Например:
- sqlserver://{user}:{password}@{server:port}/{instance_name}?database={database}
Мы рекомендуем использовать этот вариант URL.
- sqlserver://{user}:{password}@{server}?database={database}
В качестве плейсхолдера в SQL-запросе используются символы @p1.

Если вы хотите подключиться с доменными учетными данными, укажите имя учетной записи в формате <домен>%5C<пользователь>. Например: sqlserver://domain%5Cuser:password@ksc.example.com:1433/SQLEXPRESS?database=KAV.
MySQL/MariaDB .
Например:

mysql://{user}:{password}@tcp({server}:{port})/{database}

В качестве плейсхолдера в SQL-запросе используются символ ?.
PostgreSQL.
Например: postgres://{user}:{password}@{server}/{database}?sslmode=disable

В качестве плейсхолдера в SQL-запросе используются символы $1.
CockroachDB.
Например:

postgres://{user}:{password}@{server}:{port}/{database}?sslmode=disable

В качестве плейсхолдера в SQL-запросе используются символы $1.
SQLite3.
Например:

sqlite3://file:{file_path}

В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

При обращении к SQLite3, если начальное значение идентификатора используется в формате datetime, вам нужно добавить преобразование даты с помощью функции sqlite datetime в SQL-запрос. Например:

select * from connections where datetime(login_time) > datetime(?, 'utc') order by login_time

В этом примере connections – это таблица SQLite, а значение переменной ? берется из поля Начальное значение идентификатора, и его требуется указывать в формате {<дата>}T{<время>}Z, например 2021-01-01T00:10:00Z).
Oracle DB.
Начиная с версии 2.1.3 KUMA использует новый драйвер для подключения к oracle. При обновлении KUMA переименует секрет для подключения в oracle-deprecated и коннектор продолжит работу. Если после запуска коллектора с типом драйвера oracle-deprecated не удается получить события, создайте новый секрет с драйвером oracle и используйте его для подключения. Мы рекомендуем использовать новый драйвер.

Пример URL секрета с новым драйвером oracle:

oracle://{user}:{password}@{server}:{port}/{service_name}

oracle://{user}:{password}@{server}:{port}/?SID={SID_VALUE}

Если время выполнения запроса превышает 30 секунд. драйвер oracle прерывает SQL-запрос и в журнале коллектора появится ошибка user requested cancel of current operation. Для увеличения времени выполнения SQL-запроса укажите в строке подключения значение параметра timeout в секундах, например:

oracle://{user}:{password}@{server}:{port}/{service_name}?timeout=300

Пример URL секрета с прежним драйвером oracle-deprecated:

oracle-deprecated://{user}/{password}@{server}:{port}/{service_name}

В качестве плейсхолдера в SQL-запросе используется переменная :val.

При обращении к Oracle DB, если начальное значение идентификатора используется в формате datetime, требуется учитывать тип поля в базе данных и при необходимости добавить дополнительные преобразования строки со временем в SQL-запросе для обеспечения правильной работы SQL-коннектора. Например, если в базе создана таблица Connections, в которой есть поле login_time, возможны следующие преобразования:
- Если у поля login_time тип TIMESTAMP, в зависимости от параметров базы данных в поле login_time может быть указано значение в формате YYYY-MM-DD HH24:MI:SS, например 2021-01-01 00:00:00. В этом случае вам нужно указать значение 2021-01-01T00:00:00Z в поле Начальное значение идентификатора, а в SQL-запросе произвести преобразование с помощью функции to_timestamp, например:
  select * from connections where login_time > to_timestamp(:val, 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
- Если у поля login_time тип TIMESTAMP WITH TIME ZONE, в зависимости от параметров базы данных в поле login_time может быть указано значение в формате YYYY-MM-DD"T"HH24:MI:SSTZH:TZM, например 2021-01-01T00:00:00+03:00. В этом случае вам нужно указать значение 2021-01-01T00:00:00+03:00 в поле Начальное значение идентификатора, а в SQL-запросе произвести преобразование с помощью функции to_timestamp_tz, например:
  select * from connections_tz where login_time > to_timestamp_tz(:val, 'YYYY-MM-DD"T"HH24:MI:SSTZH:TZM')
  
  Подробнее о функциях to_timestamp и to_timestamp_tz см. в официальной документации Oracle.
Для обращения к Oracle DB вам нужно установить пакет Astra Linux libaio1.
Firebird® SQL.
Например:

firebirdsql://{user}:{password}@{server}:{port}/{database}

В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

Если возникает проблема подключения к firebird на Windows, используйте полный путь до файла с базой данных, например:

firebirdsql://{user}:{password}@{server}:{port}/C:\Users\user\firebird\db.FDB
ClickHouse.
При использовании шифрования TLS по умолчанию коннектор работает с ClickHouse только по порту 9000. Если шифрование TLS не используется, по умолчанию коннектор работает с ClickHouse только по порту 9440. Если на сервере с ClickHouse настроен режим шифрования TLS, а в параметрах коннектора в раскрывающемся списке Режим TLS выбрано Выключено или наоборот, соединение с базой данных не будет установлено.

Если вы хотите подключиться к ClickHouse KUMA, вам нужно в параметрах коннектора с типом SQL указать тип секрета PublicPki, который содержит закрытый ключ PEM, закодированный в base64, и открытый ключ.

В параметрах коннектора с типом SQL для типа соединения ClickHouse вам нужно выбрать Выключено в раскрывающемся списке Режим TLS. Это значение недопустимо указывать, если для аутентификации используется сертификат. Если в раскрывающемся списке Режим TLS вы выбираете Нестандартный CA, в поле Столбец идентификатора вам нужно указать ID секрета типа certificate. Вам также нужно выбрать одно из следующих значений в раскрывающемся списке Тип авторизации:
- Выключено. При выборе этого значения вам нужно оставить пустым значение в поле Столбец идентификатора.
- Обычная. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа credentials.
- PublicPki. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа PublicPki.
Флажок Секрет отдельно используется, чтобы можно было указать URL отдельно, а не в секрете.

В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать SQL-запрос select * from <название таблицы с данными> where id > <плейсхолдер>, при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.

Примеры SQL-запросов

В начало