› › ›

Настройка

После установки драйвера для подключения приложения к Elasticsearch через ODBC необходимо предоставить драйверу набор параметров конфигурации. В зависимости от приложения, существуют обычно три способа предоставления этих параметров:

через строку подключения;
используя источник данных пользователя или системы;
через файл источника данных.

DSN (имя источника данных) — это общее имя, задаваемое для набора параметров, необходимых ODBC-драйверу для подключения к базе данных.

Мы будем называть эти параметры параметрами подключения или DSN (несмотря на то, что некоторые из этих параметров настраивают другие аспекты работы драйвера, например, ведение журнала, размеры буферов...).

Использование DSN является наиболее распространенным, простым и безопасным способом настройки драйвера. Создание строки подключения, с другой стороны, является самым примитивным и, следовательно, наименее распространенным методом.

Мы будем сосредоточиваться только на использовании DSN.

1. Запуск администратора источников данных ODBC

Для управления источниками данных ODBC предоставляет приложение Администратор источников данных ODBC, которое легко устанавливается на всех современных настольных операционных системах Windows.

32-битная версия файла Odbcad32.exe находится в папке %systemdrive%\Windows\SysWoW64.
64-битная версия файла Odbcad32.exe находится в папке %systemdrive%\Windows\System32.

Чтобы запустить его, откройте меню поиска — Win + S — и введите "Источники данных ODBC (64-битная версия)" или "Источники данных ODBC (32-битная версия)" и нажмите Ввод:

Запуск администратора источников данных ODBC launch administrator

После запуска вы можете проверить, что драйвер был установлен правильно, нажав на вкладку Драйверы в Администраторе источников данных ODBC и убедившись, что Драйвер Elasticsearch присутствует в списке установленных драйверов.

Вы также должны увидеть номер версии установленного драйвера.

Вкладка "Драйверы" administrator drivers

2. Настройка DSN

Следующим шагом является настройка DSN. Вы можете выбрать один из следующих вариантов, отображаемых на первых трех вкладках приложения Администратора:

DSN пользователя

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

Фактический набор параметров, составляющих DSN, хранится драйвером в системном реестре. Таким образом, пользователю впоследствии потребуется только указать приложению имя DSN, чтобы подключиться к настроенному экземпляру Elasticsearch.
Системный DSN

Аналогично DSN пользователя, за исключением того, что соединения, настроенные на этой вкладке, будут доступны всем пользователям, настроенным в системе.
DSN файла

Эта вкладка содержит функциональность, которая позволит хранить набор параметров подключения в файле вместо реестра.

Затем такой файл можно использовать совместно на нескольких системах, и пользователю потребуется указать путь к нему, чтобы приложение подключилось к настроенному экземпляру Elasticsearch.

Шаги настройки аналогичны для всех вышеперечисленных пунктов. Ниже приведен пример настройки системного DSN.

2.1 Запуск редактора DSN драйвера Elasticsearch SQL ODBC

Нажмите на вкладку Системный DSN, а затем на кнопку Добавить…:

Добавить новый DSN administrator system add

Откроется новое окно, в котором будут перечислены все доступные установленные драйверы. Нажмите на Драйвер Elasticsearch, чтобы выделить его, а затем на кнопку Готово:

Запустить редактор DSN administrator launch editor

Это действие закроет ранее открытое второе окно и откроет новое вместо него — редактор DSN драйвера Elasticsearch SQL ODBC:

Редактор DSN драйвера Elasticsearch SQL ODBC dsn editor basic

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

2.2 Параметры подключения

Эта вкладка позволяет настроить следующие элементы:

Имя

Это имя, по которому будет ссылаться DSN.

Символы, доступные для этого поля, ограничены набором, разрешенным для ключа реестра.

Пример: localhost
Описание

Это поле позволяет ввести произвольный текст; обычно используется для коротких заметок о настроенном подключении.

Пример: Подключение без шифрования к локальному [::1]:9200.
Идентификатор облака

Идентификатор облака — это строка, которая упрощает настройку при подключении к облачной службе Elasticsearch от Elastic; она получена из консоли облака каждого кластера Elasticsearch и кодирует параметры подключения к этому кластеру.

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

В это поле требуется ввести IP-адрес или разрешаемое доменное имя экземпляра Elasticsearch, к которому будет подключаться драйвер.

Пример: ::1
Порт

Порт, на котором слушает экземпляр Elasticsearch.

Если поле оставлено пустым, будет использован стандартный порт 9200.
Имя пользователя, Пароль

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

Как минимум, необходимо заполнить поля Имя и Имя хоста, прежде чем сохранять DSN.

Шифрование соединения включено по умолчанию. Необходимо изменить это значение, если вы подключаетесь к узлу Elasticsearch без шифрования.

2.3 Параметры криптографии

Можно выбрать один из следующих вариантов SSL:

Выключено. Все коммуникации нешифрованные.

Обмен данными между драйвером и экземпляром Elasticsearch выполняется по открытому соединению.

Это значение может раскрыть учетные данные доступа для третьей стороны, перехватывающей сетевой трафик, и не рекомендуется.
Включено. Сертификат не проверяется.

Включено шифрование соединения, но сертификат сервера не проверяется.

В настоящее время это значение является значением по умолчанию.

Это значение позволяет третьей стороне легко выступать в роли человека-посредника и, таким образом, перехватывать все коммуникации.
Включено. Сертификат проверен; имя хоста не проверен.

Включено шифрование соединения, и драйвер проверяет, является ли сертификат сервера действительным, но он не проверяет, работает ли сертификат на сервере, для которого он предназначен.

Это значение позволяет третьей стороне, имеющей доступ к сертификату сервера, действовать в роли человека-посредника и, таким образом, перехватывать все коммуникации.
Включено. Сертификат проверен; имя хоста проверено.

Включено шифрование соединения, и драйвер проверяет, является ли сертификат действительным, а также используется ли он на сервере, для которого он предназначен.
Включено. Проверяется цепочка идентификации сертификата.

Это значение эквивалентно предыдущему, с дополнительной проверкой на отзыв сертификата. Это обеспечивает самый высокий уровень безопасности и рекомендуется для развертывания в рабочей среде.
Файл сертификата

В случае, если сервер использует сертификат, который не является частью инфраструктуры открытых ключей, например, самоподписанный сертификат, можно настроить путь к файлу сертификата X.509, который будет использоваться драйвером для проверки предложенного сертификата сервера.

Драйвер будет читать содержимое файла непосредственно перед попыткой подключения. См. раздел 2.7 Тестирование подключения далее, чтобы узнать, как проверить правильность предоставленных параметров.

Файл сертификата не может быть скомпонован или защищен паролем, так как драйвер не запрашивает пароль.

Если использовать проводник для поиска сертификата, нажав кнопку Обзор…, то по умолчанию будут рассмотрены только файлы с расширениями .pem и .der. Выберите Все файлы (*.*) из выпадающего списка, если ваш файл имеет другое расширение:

Проводник для файла сертификата

2.4 Параметры прокси

Если подключение к узлу Elasticsearch необходимо осуществлять через прокси-сервер, необходимо настроить следующие параметры:

Тип

Какой протокол использовать при подключении к хосту прокси-сервера. Это также определяет, как необходимо указать узел Elasticsearch, к которому вы хотите подключиться через прокси, в разделе 2.2 Параметры подключения:
- HTTP, SOCKS4A, SOCKS5H: допускается ввод IP-адреса или имени хоста; прокси будет выполнять разрешение доменного имени;
- SOCKS4, SOCKS5: расположение узла Elasticsearch необходимо указать как IP-адрес;
Порт

TCP-порт, на котором прокси-сервер слушает подключения.
Имя пользователя

Часть учетных данных, используемых для аутентификации на прокси-сервере.
Пароль

Часть учетных данных для прокси-сервера.

Параметры прокси dsn editor proxy

2.5 Параметры подключения

Параметры подключения можно дополнительно настроить с помощью следующих параметров.

Таймаут запроса (с)

Максимальное время (в секундах), которое может занять запрос к серверу. Это можно переопределить более длинным таймаутом на уровне заявления. Значение 0 означает отсутствие таймаута.
Максимальный размер страницы (строки)

Максимальное количество строк, которые сервер Elasticsearch SQL должен отправить драйверу для одной страницы. Это соответствует параметру fetch_size API поиска SQL. Значение 0 указывает на значение по умолчанию сервера.
Максимальная длина страницы (МБ)

Максимальный размер (в мегабайтах), до которого может вырасти ответ, прежде чем драйвер отклонит его как слишком большой. Это касается тела HTTP-ответа одной страницы, а не суммарного объёма данных, которые запрос может сгенерировать.
Предел VARCHAR

Максимальная ширина столбцов типа строка. Если это значение больше нуля, драйвер будет объявлять все столбцы типа строка как имеющие максимальную длину символов, равную этому значению, и будет усекать любые более длинные строки до него. Типы строк - это текстовые поля (TEXT, KEYWORD и т. д.) и некоторые специализированные поля (IP, GEO и т. д.). Обратите внимание, что никакой интерпретации значения не выполняется перед усечением, что может привести к некорректным значениям, если предел установлен слишком низко. Это необходимо для тех приложений, которые не поддерживают длину столбцов так же большую, как поля Elasticsearch.
Формат чисел с плавающей точкой

Управляет тем, как будут выводиться числа с плавающей точкой, когда они преобразуются в строки драйвером. Возможные значения для этого параметра:
- scientific: экспоненциальная запись (например: 1.23E01);
- default: стандартная запись (например: 12.3);
- auto: драйвер выберет одно из вышеперечисленных значений в зависимости от выводимого значения. Обратите внимание, что количество десятичных знаков зависит от точности (или шкалы ODBC) выводимого значения и варьируется в зависимости от разных типов чисел с плавающей точкой, поддерживаемых Elasticsearch SQL. Эта настройка не эффективна, когда приложение получает значения от драйвера как числа, а затем само выполняет преобразование.
Кодировка данных

Это значение контролирует формат данных, в котором кодируется REST-содержимое. Возможные значения:
- CBOR: использование формата Concise Binary Object Representation. Это предпочтительная кодировка, учитывая её более компактный формат.
- JSON: использование формата JavaScript Object Notation. Этот формат более подробный, но проще для чтения, особенно полезен при устранении неполадок.
Сжатие данных

Эта настройка контролирует, сжимается ли REST-содержимое - закодированное в одном из вышеупомянутых форматов - и когда. Возможные значения:
- on: включает сжатие;
- off: отключает сжатие;
- auto: включает сжатие, за исключением случая, когда данные проходят через защищённое соединение; так как в этом случае уровень шифрования использует собственное сжатие данных, и могут быть последствия для безопасности, когда включено дополнительное сжатие, параметр следует оставлять на этом значении.
Следовать HTTP-редиректам

Должен ли драйвер следовать HTTP-редиректам запросов на сервер?
Использовать локальную часовую зону

Эта настройка контролирует часовую зону:
- контекста, в котором будет выполняться запрос (особенно актуально для функций, имеющих дело с компонентами временных меток);
- временных меток, полученных от / отправленных на сервер.
  
  Если отключено, будет применена часовая зона UTC; в противном случае, часовая зона, установленная на локальном компьютере.
Автоматическое экранирование PVAs

Аргументы со значениями-шаблонами используют _ и % в качестве специальных символов для построения значений для сопоставления с шаблоном. Однако некоторые приложения используют эти символы как обычные, что может привести к тому, что Elasticsearch SQL вернёт больше данных, чем ожидалось приложением. При автоматическом экранировании драйвер будет проверять аргументы и будет экранировать эти специальные символы, если они ещё не экранированы приложением.
Поле с множественными значениями - снисходительно

Эта настройка контролирует поведение сервера в случае запроса к полю с несколькими значениями. Если это установлено, и сервер обнаруживает такое поле, он выберет одно значение из набора - без каких-либо гарантий, что это будет, но обычно первое в естественном порядке возрастания - и вернёт его как значение для столбца. Если не установлено, сервер вернёт ошибку. Соответствует параметру field_multi_value_leniency API поиска SQL.
Включать замороженные индексы

Если этот параметр равен true, сервер включит замороженные индексы в выполнении запроса. Соответствует параметру запроса Elasticsearch SQL index_include_frozen
Раннее выполнение запроса

Если эта настройка установлена, драйвер выполнит оператор сразу после того, как приложение отправит его на подготовку - т.е. рано - и функционально эквивалентен прямому выполнению. Это произойдёт только в том случае, если запрос не содержит параметров. Раннее выполнение полезно для тех приложений, которые проверяют результат перед фактическим выполнением запроса. Elasticsearch SQL не имеет API подготовки, поэтому раннее выполнение необходимо для межплатформенной совместимости с этими приложениями.

Параметры соединения dsn editor misc

2.6 Параметры ведения журнала

Для целей отладки драйвер Elasticsearch SQL ODBC предоставляет возможность регистрировать API-вызовы, которые делает приложение; это включено в приложении Администрирования:

Включить ведение журнала API ODBC приложения administrator tracing

Однако это регистрирует только вызовы API ODBC, сделанные приложением в Диспетчер драйверов, а не те, которые делает Диспетчер драйверов в сам драйвер. Чтобы включить ведение журнала вызовов, получаемых драйвером, а также событий обработки внутри драйвера, вы можете включить ведение журнала драйвера на вкладке Ведение журнала редактора:

Включить ведение журнала?

Отметив это, вы включите ведение журнала драйвера. Каталог ведения журнала также обязателен, когда эта опция включена (см. следующую опцию). Однако указанный каталог ведения журнала будет сохранён в DSN, если предоставлен, даже если ведение журнала отключено.
Каталог ведения журнала

Здесь необходимо указать каталог для записи файлов журнала.

Драйвер будет создавать один файл журнала на соединение для тех соединений, которые генерируют сообщения ведения журнала.
Уровень ведения журнала

Настройте подробность логов.

Включить ведение журнала драйвера

При включенной аутентификации пароль будет замаскирован в логах.

Ведение отладочного журнала может быстро привести к созданию многих очень больших файлов и создать значительную нагрузку на обработку. Включайте только по необходимости и, предпочтительно, только при получении небольших объёмов данных.

2.7 Тестирование соединения

После того, как Имя хоста, Порт (если он отличается от неявного значения по умолчанию) и параметры SSL настроены, вы можете проверить правильность предоставленных параметров, нажав кнопку Тестировать соединение. Это инструктирует драйвер подключиться к экземпляру Elasticsearch и выполнить простой SQL-запрос теста. (Это потребует запущенного экземпляра Elasticsearch с включенным SQL-плагином.)

Тестирование соединения dsn editor conntest

При тестировании соединения учитываются все настроенные параметры, включая конфигурацию ведения журнала. Это позволит рано обнаружить потенциальные конфликты прав доступа к файлам/каталогам.

См. раздел Альтернативная конфигурация ведения журнала далее для альтернативного способа настройки ведения журнала.

3. DSN доступен

После того, как всё настроено, нажатие кнопки Сохранить сохранит конфигурацию в выбранном месте (реестр или файл).

Перед сохранением конфигурации DSN предоставленные пути к файлам/каталогам проверяются на валидность в текущей системе. Однако редактор DSN никоим образом не проверяет валидность или доступность настроенного Имя хоста : Порт. См. 2.7 Тестирование соединения для исчерпывающей проверки.

Если всё правильно, имя только что созданного DSN будет указано как доступное для использования:

Соединение добавлено administrator system added

Альтернативная конфигурация ведения журнала

Из-за спецификации API ODBC, драйвер получит настроенные параметры DSN — включая параметры ведения журнала — только один раз при вызове API подключения (например, SQLConnect или SQLDriverConnect). Однако менеджер драйверов всегда выполняет набор API-вызовов в драйвер перед попыткой установить подключение. Чтобы захватить и эти вызовы, необходимо передать параметры конфигурации ведения журнала альтернативным способом. Elasticsearch SQL ODBC Driver для этой цели будет использовать переменную среды.

Настройка переменной среды зависит от операционной системы и не описана в данном руководстве. Решение о том, следует ли настраивать переменную на уровне всей системы или на уровне пользователя, зависит от способа запуска приложения, поддерживающего ODBC, и того, должно ли ведение журнала влиять только на текущего пользователя или нет.

Определение переменной среды должно быть следующим:

Имя: ESODBC_LOG_DIR
Значение: [путь](?[уровень]), где:

[путь] — путь к каталогу, в который будут записываться файлы журнала;

[уровень] — необязательный параметр, который может принимать одно из следующих значений: debug, info, warn, error; если он не указан, используется debug.

Переменная среды ведения журнала env var log

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

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

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-odbc-setup.html