設定

ドライバーがインストールされたら、アプリケーションが ODBC を介して Elasticsearch に接続できるようにするために、一連の設定パラメーターをドライバーに提供する必要があります。アプリケーションによって、これらのパラメーターを提供する方法は一般的に 3 つあります:

  • 接続文字列を介して;
  • ユーザー DSN またはシステム DSN を使用して;
  • ファイル DSN を介して。

DSN (データソース名) は、ODBC ドライバーがデータベースに接続するために必要なパラメーターのセットに付けられた一般的な名前です。

これらのパラメーターを 接続パラメーター または DSN と呼びます（これらのパラメーターの一部は、ドライバーの機能の他の側面を設定するために使用されます; 例: ロギング、バッファサイズ…）。

DSN を使用することは、ドライバーの設定を行う最も広く使用されている、最も簡単で安全な方法です。一方、接続文字列を構築することは最も原始的な方法であり、したがって最も一般的ではありません。

私たちは DSN の使用にのみ焦点を当てます。

1. ODBC データソース管理者の起動

DSN 管理のために、ODBC は ODBC データソース管理者 アプリケーションを提供しており、これはすべての最近のデスクトップ Windows オペレーティングシステムにインストールされています。

  • 32 ビット版の Odbcad32.exe ファイルは %systemdrive%\Windows\SysWoW64 フォルダーにあります。
  • 64 ビット版の Odbcad32.exe ファイルは %systemdrive%\Windows\System32 フォルダーにあります。

これを起動するには、検索メニューを開き - Win + S - そして「ODBC データソース (64 ビット)」または「ODBC データソース (32 ビット)」と入力して Enter を押します:

ODBC データソース管理者の起動launch administrator

起動後、ODBC データソース管理者の ドライバー タブをクリックして、Elasticsearch Driver がインストールされたドライバーのリストに存在することを確認することで、ドライバーが正しくインストールされたかどうかを確認できます。

インストールされたドライバーのバージョン番号も表示されるはずです。

ドライバータブadministrator drivers

2. DSN の設定

次のステップは DSN を設定することです。管理者アプリケーションの最初の 3 つのタブにマッピングされた以下のオプションから選択できます:

  • ユーザー DSN
    このタブの下で設定された接続は、現在ログインしているユーザーのみが利用可能です。これらの DSN のそれぞれは、選択した任意の名前（通常はホストまたはクラスター名）で参照されます。
    DSN を構成する実際のパラメーターのセットは、ドライバーを介してシステムレジストリに保存されます。したがって、ユーザーは後でアプリケーションに DSN 名を提供するだけで、構成された Elasticsearch インスタンスに接続できます。
  • システム DSN
    ユーザー DSN と似ていますが、このタブの下で設定された接続は、システム上のすべてのユーザーが利用可能です。
  • ファイル DSN
    このタブには、接続パラメーターの 1 セットをレジストリではなくファイルに書き込む機能があります。
    このファイルは複数のシステム間で共有でき、ユーザーはアプリケーションが構成された Elasticsearch インスタンスに接続するために、そのパスを指定する必要があります。

上記のすべてのポイントに対する設定手順は似ています。以下は、システム DSN を設定する例です。

2.1 Elasticsearch SQL ODBC ドライバー DSN エディターの起動

まず システム DSN タブをクリックし、次に 追加… ボタンをクリックします:

新しい DSN を追加administrator system add

新しいウィンドウが開き、すべての利用可能なインストール済みドライバーがリストされます。Elasticsearch Driver をクリックしてハイライトし、次に 完了 ボタンをクリックします:

DSN エディターの起動administrator launch editor

この操作により、以前に開かれた 2 番目のウィンドウが閉じられ、新しいウィンドウが開きます。Elasticsearch SQL ODBC ドライバーの DSN エディター:

Elasticsearch SQL ODBC ドライバー DSN エディターdsn editor basic

この新しいウィンドウには 3 つのタブがあり、それぞれが一連の設定パラメーターを担当しています。

2.2 接続パラメーター

このタブでは、以下の項目の設定が可能です:

  • 名前
    これは DSN が参照される名前です。
    このフィールドに使用できる文字は、レジストリキーに許可されているセットに制限されています。
    例: localhost
  • 説明
    このフィールドには任意のテキストを入力できます。一般的には、構成された接続に関する短いメモに使用されます。
    例: ローカル [::1]:9200 へのクリアテキスト接続。
  • Cloud ID
    Cloud ID は、Elastic の Cloud Elasticsearch Service に接続する際の設定を簡素化する文字列です。これは各 Elasticsearch クラスターの Cloud コンソール内から取得され、そのクラスターへの接続パラメーターをエンコードします。
    このフィールドが提供されると、ホスト名、ポート、およびセキュリティ設定も提供され、それぞれの入力が無効になります。
  • ホスト名
    このフィールドには、ドライバーが接続する Elasticsearch インスタンスの IP アドレスまたは解決可能な DNS 名が必要です。
    例: ::1
  • ポート
    Elasticsearch がリッスンするポートです。
    空のままにすると、デフォルトの 9200 ポート番号が使用されます。
  • ユーザー名、パスワード
    セキュリティが有効になっている場合、これらのフィールドにはアクセスユーザーの資格情報を含める必要があります。

最低限、DSN を保存する前に 名前 と ホスト名 フィールドを提供する必要があります。

接続の暗号化はデフォルトで有効になっています。暗号化なしで Elasticsearch ノードに接続する場合は、これを変更する必要があります。

2.3 暗号化パラメーター

次の SSL オプションのいずれかを選択できます:

  • 無効。すべての通信が暗号化されていません。
    ドライバーと Elasticsearch インスタンス間の通信は、クリアテキスト接続を介して行われます。
    この設定は、ネットワークトラフィックを傍受する 3 番目の者にアクセス資格情報を露出させる可能性があり、推奨されません。
  • 有効。証明書は検証されません。
    接続の暗号化は有効ですが、サーバーの証明書は検証されません。
    これは現在のデフォルト設定です。
    この設定により、3 番目の者が中間者として簡単に行動し、すべての通信を傍受することができます。
  • 有効。証明書は検証され、ホスト名は検証されません。
    接続の暗号化は有効で、ドライバーはサーバーの証明書が有効であることを確認しますが、その証明書が意図されたサーバーで実行されているかどうかは検証しません。
    この設定により、サーバーの証明書にアクセスできる 3 番目の者が中間者として行動し、すべての通信を傍受することができます。
  • 有効。証明書は検証され、ホスト名も検証されます。
    接続の暗号化は有効で、ドライバーは証明書が有効であることを確認し、さらにその証明書が意図されたサーバーで展開されていることを確認します。
  • 有効。証明書のアイデンティティチェーンが検証されます。
    この設定は前の設定と同等で、証明書の失効に対する追加のチェックがあります。これは最も強力なセキュリティオプションを提供し、製品展開に推奨される設定です。
  • 証明書ファイル
    サーバーが PKI の一部でない証明書（たとえば、自己署名証明書）を使用している場合、ドライバーがサーバーが提供する証明書を検証するために使用する X.509 証明書ファイルのパスを設定できます。
    ドライバーは、接続が試行される直前にファイルの内容を読み取ります。提供されたパラメーターの有効性を確認する方法については、2.7 接続のテスト セクションを参照してください。
    証明書ファイルはバンドルしたりパスワード保護したりできません。ドライバーはパスワードを要求しません。
    証明書を見つけるためにファイルブラウザを使用する場合 - [参照…] ボタンを押すことで - デフォルトでは .pem および .der 拡張子のファイルのみが考慮されます。ファイルが異なる拡張子で終わる場合は、ドロップダウンからすべてのファイル (.) を選択してください:
    証明書ファイルブラウザdsn editor security cert

2.4 プロキシパラメーター

Elasticsearch ノードに接続する際にプロキシを経由する必要がある場合、次のパラメーターを設定する必要があります:

  • タイプ
    プロキシホストに接続する際に使用するプロトコルの種類。これにより、プロキシを介して接続したい Elasticsearch ノードを 2.2 接続パラメーター の下で指定する必要があります:
    • HTTP、SOCKS4A、SOCKS5H: IP アドレスまたはホスト名が受け入れられます。プロキシが DNS 名を解決します。
    • SOCKS4、SOCKS5: Elasticsearch ノードの場所は IP アドレスとして提供する必要があります;
  • ポート
    プロキシが接続を待機している TCP ポート。
  • ユーザー名
    プロキシに認証するために使用される資格情報のユーザー部分。
  • パスワード
    プロキシの資格情報のパスワード部分。

プロキシパラメーターdsn editor proxy

2.5 接続パラメーター

接続設定は、以下のパラメーターによってさらに調整できます。

  • リクエストタイムアウト (秒)
    サーバーへのリクエストがかかる最大時間 (秒)。これは、より大きなステートメントレベルのタイムアウト設定によって上書きされる可能性があります。値 0 はタイムアウトなしを意味します。
  • 最大ページサイズ (行)
    Elasticsearch SQL サーバーがドライバーに 1 ページのために送信すべき最大行数。これは SQL 検索 API の fetch_size パラメーターに対応します。 0 値はサーバーのデフォルトを示します。
  • 最大ページ長 (MB)
    応答が拒否される前に、応答が成長できる最大サイズ (メガバイト)。これは、1 ページの HTTP 応答ボディに関するものであり、クエリが生成する可能性のある累積データ量ではありません。
  • Varchar 制限
    文字列列の最大幅。この設定が 0 より大きい場合、ドライバーはすべての文字列型列をこの値と等しい最大文字長を持つものとして宣伝し、長い文字列はそれに切り詰められます。文字列型はテキストフィールド (TEXT、KEYWORD など) と一部の特殊フィールド (IP、GEO など) です。切り詰める前に値の解釈は行われないため、制限が低すぎると無効な値が生じる可能性があります。これは、Elasticsearch フィールドのように大きな列長をサポートしないアプリケーションに必要です。
  • 浮動小数点形式
    浮動小数点数がドライバーによって文字列に変換される際の表示方法を制御します。このパラメーターに与えられる可能な値:
    • scientific: 指数表記 (例: 1.23E01);
    • default: デフォルト表記 (例: 12.3);
    • auto: ドライバーは、印刷される値に応じて上記のいずれかを選択します。小数点以下の桁数は、印刷される値の精度 (または ODBC スケール) に依存し、Elasticsearch SQL がサポートするさまざまな浮動小数点型によって異なります。この設定は、アプリケーションがドライバーから値を数値として取得し、その後自分自身で変換する場合には効果がありません。
  • データエンコーディング
    この値は、REST コンテンツをエンコードするデータ形式を制御します。可能な値は:
    • CBOR: 簡潔なバイナリオブジェクト表現形式を使用します。これは、よりコンパクトな形式であるため、推奨されるエンコーディングです。
    • JSON: JavaScript オブジェクト表現形式を使用します。この形式は冗長ですが、特にトラブルシューティングに役立つため、読みやすいです。
  • データ圧縮
    この設定は、REST コンテンツ - 上記のいずれかの形式でエンコードされた - が圧縮されるかどうか、またはいつ圧縮されるかを制御します。可能な値は:
    • on: 圧縮を有効にします;
    • off: 圧縮を無効にします;
    • auto: 圧縮を有効にしますが、データが安全な接続を介して流れる場合は除きます。この場合、暗号化層が独自のデータ圧縮を使用し、追加の圧縮を有効にするとセキュリティ上の問題が生じる可能性があるため、この値に設定する必要があります。
  • HTTP リダイレクトの追従
    ドライバーは、サーバーへのリクエストの HTTP リダイレクトに従うべきですか?
  • ローカルタイムゾーンの使用
    この設定は、次のタイムゾーンを制御します:
    • クエリが実行されるコンテキスト (特にタイムスタンプコンポーネントを扱う関数に関連);
    • サーバーから受信した/サーバーに送信されたタイムスタンプ。
      無効にすると、UTC タイムゾーンが適用されます。それ以外の場合は、ローカルマシンの設定されたタイムゾーンが適用されます。
  • 自動エスケープ PVA
    パターン値引数は、_ および % を特別な文字として使用してパターンマッチング値を構築します。ただし、一部のアプリケーションはこれらの文字を通常の文字として使用するため、Elasticsearch SQL がアプリケーションが意図したよりも多くのデータを返す可能性があります。自動エスケープを使用すると、ドライバーは引数を検査し、アプリケーションによってまだ行われていない場合はこれらの特別な文字をエスケープします。
  • マルチバリューフィールドの寛容性
    この設定は、マルチバリューフィールドがクエリされた場合のサーバーの動作を制御します。これが設定されている場合、サーバーがそのようなフィールドに遭遇すると、セット内の値を選択し - それが何であるかの保証はありませんが、通常は自然な昇順で最初の値 - それを列の値として返します。設定されていない場合、サーバーはエラーを返します。これは SQL 検索 API の field_multi_value_leniency パラメーターに対応します。
  • 凍結インデックスを含める
    このパラメーターが true の場合、サーバーはクエリ実行に凍結インデックスを含めます。これは Elasticsearch SQL のリクエストパラメーター index_include_frozen に対応します。
  • 早期クエリ実行
    この設定が行われている場合、ドライバーはアプリケーションが準備のために提出したステートメントをすぐに実行します - すなわち早期に - そしてこれは直接実行と機能的に同等です。これは、クエリにパラメーターがない場合にのみ発生します。早期実行は、結果を実行する前に確認するアプリケーションに便利です。Elasticsearch SQL には準備 API がないため、これらのアプリケーションとの相互運用性のために早期実行が必要です。

接続パラメーターdsn editor misc

2.6 ロギングパラメーター

トラブルシューティングの目的で、Elasticsearch SQL ODBC ドライバーは、アプリケーションが行う API 呼び出しをログに記録する機能を提供します。これは管理者アプリケーションで有効にできます:

アプリケーション ODBC API ロギングを有効にするadministrator tracing

ただし、これはアプリケーションによって行われた ODBC API 呼び出しのみを ドライバーマネージャー に記録し、ドライバーマネージャー がドライバー自体に行った呼び出しは記録しません。ドライバーが受け取る呼び出しや内部ドライバー処理イベントのロギングを有効にするには、エディターの ロギング タブでドライバーのロギングを有効にできます:

  • ロギングを有効にしますか?
    これにチェックを入れると、ドライバーのロギングが有効になります。このオプションが有効な場合、ロギングディレクトリも必須です（次のオプションを参照）。ただし、指定されたロギングディレクトリは、ロギングが無効であっても DSN に保存されます。
  • ログディレクトリ
    ここでは、ログファイルを書き込むディレクトリを指定します。
    ドライバーは、ロギングメッセージを生成する接続ごとに 1 つのログファイル を作成します。
  • ログレベル
    ログの詳細度を設定します。
    ドライバーのロギングを有効にするdsn editor logging
    認証が有効になっている場合、パスワードはログから隠されます。

デバッグロギングは、非常に大きなファイルを多数生成し、かなりの処理オーバーヘッドを生じる可能性があります。指示がある場合にのみ有効にし、できれば少量のデータを取得する際にのみ有効にしてください。

2.7 接続のテスト

ホスト名、ポート (暗黙のデフォルトと異なる場合) および SSL オプションが設定されたら、接続テスト ボタンを押すことで提供されたパラメーターが正しいかどうかをテストできます。これにより、ドライバーは Elasticsearch インスタンスに接続し、簡単な SQL テストクエリを実行します。（これには、SQL プラグインが有効な実行中の Elasticsearch インスタンスが必要です。）

接続テストdsn editor conntest

接続テストを行うと、すべての設定されたパラメーターが考慮され、ロギング設定も含まれます。これにより、ファイル/ディレクトリのアクセス権の競合を早期に検出できます。

ロギングの代替設定方法については、代替ロギング設定 セクションを参照してください。

3. DSN が利用可能

すべてが整ったら、保存 ボタンを押すことで、設定が選択した宛先 (レジストリまたはファイル) に保存されます。

DSN 設定を保存する前に、提供されたファイル/ディレクトリパスが現在のシステムで有効であることが確認されます。ただし、DSN エディターは構成された ホスト名: ポート の有効性や到達可能性を確認しません。詳細なチェックについては、2.7 接続のテスト を参照してください。

すべてが正しければ、新しく作成された DSN の名前が利用可能としてリストされます:

接続が追加されましたadministrator system added

代替ロギング設定

ODBC API の仕様により、ドライバーは接続 API が呼び出されるまで、設定された DSN パラメーター - ロギングパラメーターを含む - を受け取ることはありません (SQLConnect または SQLDriverConnect など)。ただし、ドライバーマネージャー は、接続を確立しようとする前に、常にドライバーに一連の API 呼び出しを行います。これらの呼び出しもキャプチャするには、別の方法でロギング設定パラメーターを渡す必要があります。Elasticsearch SQL ODBC ドライバーは、この目的のために環境変数を使用します。

環境変数の設定は OS に依存し、このガイドでは詳細に説明されていません。変数がシステム全体で設定されるべきか、ユーザー固有であるべきかは、ODBC 対応アプリケーションの実行方法と、ロギングが現在のユーザーのみに影響を与えるべきかどうかによります。

環境変数の定義は次のように行う必要があります:

  • 名前: ESODBC_LOG_DIR
  • 値: path、ここで:
    [path] はログファイルが書き込まれるディレクトリへのパス;
    [level] はオプションで、次のいずれかの値を取ることができます: debug、info、warn、error; 提供されない場合は、debug が仮定されます。

ロギング環境変数env var log

環境変数を介してロギングを有効にすると、ドライバーは プロセスごとに 1 つのログファイル を作成します。

ロギングの設定方法は共存でき、両方が同じ宛先ロギングディレクトリを使用できます。ただし、1 つのロギングメッセージは 1 回だけ記録され、接続ロギングが環境変数ロギングに優先されます。