Databricks JDBC Driver を使用して Databricks への接続を構成する

この記事では、 Databricks JDBC Driver バージョン 3 以降を使用して Databricks への接続を構成する方法について説明します。

接続を構成する

JDBC ドライバーを使用して Azure Databricks ワークスペースに接続するには、Azure Databricks ワークスペースのサーバー ホスト名、コンピューティング リソース設定、ワークスペースに接続するための認証資格情報など、さまざまな接続設定を指定する必要があります。

それらのプロパティの値は、JDBC 接続 URL で設定する方法、DriverManager.getConnection メソッドで設定して渡す方法、またはその両方を組み合わせて指定できます。 特定のアプリ、クライアント、SDK、API、または SQL ツールを使用して接続するのに最適な方法については、プロバイダーのドキュメントを参照してください。

JDBC 接続 URL の形式は以下に従う必要があります。 プロパティの大文字と小文字は区別されません。

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

この代わりに、java.util.Properties クラスまたは組み合わせによって設定を指定することもできます。

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

接続 URL 要素については、以下の表で説明するとおりです。

認証プロパティ、SQL 構成プロパティ、ログ プロパティなど、追加のプロパティについては、「 サポートされている接続プロパティ」を参照してください。

Azure Databricks クラスターの JDBC 接続 URL を取得するには、以下のようにします。

1. Azure Databricks ワークスペースにログインします。
2. サイドバーで、[ コンピューティング] をクリックし、ターゲット クラスターの名前をクリックします。
3. [構成] タブで、[詳細オプション] を展開します。
4. [JDBC/ODBC] タブをクリックします。
5. JDBC 接続 URL として使用する JDBC URL をコピーするか、サーバー ホスト名、ポート、および HTTP パス フィールドの値から URL を作成します。

Databricks SQL ウェアハウスの JDBC 接続 URL を取得するには、以下のようにします。

1. Azure Databricks ワークスペースにログインします。
2. サイドバーで、[ SQL Warehouses] をクリックし、ターゲット ウェアハウスの名前をクリックします。
3. [接続の詳細] タブをクリックします。
4. JDBC 接続 URL として使用する JDBC URL をコピーするか、サーバー ホスト名、ポート、および HTTP パス フィールドの値から URL を作成します。

クエリ タグを構成する

追跡と分析のために、SQL クエリにキー値タグをアタッチできます。 クエリタグは、クエリの識別と分析のために system.query.history テーブルに表示されます。

接続にクエリ タグを追加するには、JDBC URL に query_tags プロパティを含めます。

jdbc:databricks://<server-hostname>:<port>/<schema>;query_tags=key1:value1,key2:value2

クエリ タグでは、コンマ区切りのキーと値のペア形式が使用されます。

• query_tags=key:value (単一タグ)
• query_tags=key1:value1,key2:value2,key3:value3 (複数のタグ)

プロキシ接続を構成する

Databricks に直接接続するのではなく、プロキシ サーバー経由で接続するようにコネクタを構成できます。 プロキシ サーバー経由で接続する場合、コネクタは基本認証と SPNEGO 認証をサポートします。

プロキシ接続を構成するには:

1. UseProxy プロパティを 1 に設定します。
2. システム レベルでプロキシ設定を構成するには、 UseSystemProxy プロパティを 1 に設定します。それ以外の場合は、次のようにドライバーに設定します。
   1. ProxyHost プロパティをプロキシ サーバーの IP アドレスまたはホスト名に設定します。
   2. ProxyPort プロパティを、プロキシ サーバーがクライアント接続をリッスンするために使用するポートに設定します。
   3. ProxyIgnoreList プロパティをコンマ区切りのホスト名に設定します。
   4. プロキシ サーバーで認証します。
      • 基本認証を使用するには
        1. ProxyAuth プロパティを 1 に設定します。
        2. ProxyUIDプロパティをサーバーにアクセスするためのユーザー名に設定します。
        3. ProxyPWDプロパティをサーバーにアクセスするためのパスワードに設定します。
      • SPNEGO 認証を使用するには:
        1. システム レベルで Kerberos プリンシパルを認証します。
        2. ProxyAuth プロパティを 2 に設定します。

CloudFetch 専用に別のプロキシを使用するには、上記の手順に従って、UseCFProxy、CFProxyHost、CFProxyPort、CFProxyAuth、CFProxyUID、CFProxyPwdを設定してください。

SSL の構成

Secure Sockets Layer (SSL) が有効になっている Databricks に接続している場合は、SSL 対応ソケットに接続するようにコネクタを構成できます。 SSL 経由でサーバーに接続する場合、コネクタは一方向認証を使用してサーバーの ID を確認します。

一方向認証では、サーバーの ID を確認するために、署名された信頼された SSL 証明書が必要です。 適切な証明書を含む特定の TrustStore にアクセスするようにコネクタを構成できます。 TrustStore を指定しない場合、コネクタは jssecacerts という名前の既定の Java TrustStore を使用します。 jssecacerts を使用できない場合、コネクタは代わりに cacerts を使用します。

SSL を構成するには:

1. SSL プロパティを 1 に設定します。
2. 既定の Java トラスト ストアのいずれかを使用していない場合は、トラスト ストアを作成し、それを使用するようにコネクタを構成します。
   1. 署名された信頼されたサーバー証明書を含む信頼ストアを作成します。
   2. SSLTrustStore プロパティを TrustStore の完全パスに設定します。
   3. SSLTrustStorePwd プロパティを TrustStore にアクセスするためのパスワードに設定します。
   4. TrustStore が JKS TrustStore でない場合は、SSLTrustStoreType プロパティを正しい型に設定します。 サポートされている種類は次のとおりです:
      • SSLTrustStoreType=BCFKS (バウンスキャッスル FIPS キーストア)
      • SSLTrustStoreType=PKCS12 (公開キー暗号化標準 #12)

証明書失効戦略を変更する場合、コネクタは次のパラメーターを提供します。

• CheckCertRevocation プロパティを 0 に設定すると、失効した証明書が受け入れられます (プロパティの既定値は 1)
  • AcceptUndeterminedRevocation プロパティを 1 に設定すると、証明書の失効状態を識別できない証明書が受け入れられます (CRLDP は到達不能/タイムアウトなど)、このプロパティの既定値は 0 です

ドライバーを認証する

JDBC ドライバー接続の認証には、以下のいずれかの認証メカニズムを使用できます。

• OAuth ユーザー対マシン (U2M) 認証 (推奨)
• Azure マネージド ID を使用した M2M
• Azure Databricks の個人用アクセス トークン

OAuth ユーザー対マシン (U2M) 認証

JDBC ドライバーは、OAuth ユーザー対マシン (U2M) 認証に対応しており、リアルタイムの人間のサインインと同意を使用して、ターゲットの Databricks ユーザー アカウントを認証します。 これは、ブラウザーベースの OAuth 認証とも呼ばれます。

Azure Databricks は、顧客用に OAuth クライアント ID databricks-sql-jdbc を作成しました。 これは、JDBC ドライバーで使用される既定の OAuth クライアント ID でもあります。 OAuth U2M 認証を設定するには、既存の JDBC 接続 URL または java.util.Properties オブジェクトに次のプロパティを追加するだけです。

OAuth マシン間 (M2M) 認証

JDBC ドライバーは、次のいずれかのプリンシパルまたは ID を使用して、OAuth マシン間 (M2M) 認証 (OAuth 2.0 クライアント資格情報 認証とも呼ばれます) をサポートします。 OAuth を使用した Azure Databricks へのサービス プリンシパル アクセスの承認に関するページを参照してください。

• Databricks サービス プリンシパル
• Azure マネージド サービス プリンシパル
• Azure マネージド ID (システム割り当てまたはユーザー割り当て)

Databricks マネージド サービス プリンシパルを使用した M2M

Databricks マネージド サービス プリンシパルを使用して認証を構成するには:

1. Databricks マネージド サービス プリンシパルを作成し、それを Databricks アカウントとワークスペースに割り当てます。
2. サービス プリンシパルの Databricks OAuth シークレットを作成します。 OAuth M2M セットアップ ガイドを参照してください。
3. クラスターと SQL ウェアハウスへのアクセス許可を付与します。
4. 以下のプロパティを、既存の JDBC 接続 URL または java.util.Properties オブジェクトに追加します。

Azure マネージド サービス プリンシパルを使用した M2M

Azure マネージド サービス プリンシパルを使用して認証を構成するには:

1. サービス プリンシパルの Databricks OAuth シークレットを作成します。 OAuth M2M セットアップ ガイドを参照してください。
2. クラスターと SQL ウェアハウスへのアクセス許可を付与します。
3. 以下のプロパティを、既存の JDBC 接続 URL または java.util.Properties オブジェクトに追加します。

Azure マネージド ID を使用した M2M

Azure マネージド ID を使用して認証を構成するには:

1. Azure リソースのマネージド ID を構成します。
2. クラスターと SQL ウェアハウスへのアクセス許可を付与します。
3. 以下のプロパティを、既存の JDBC 接続 URL または java.util.Properties オブジェクトに追加します。

Azure Databricks 個人用アクセス トークン

Azure Databricks 個人用アクセス トークン を使用して JDBC ドライバー接続を認証する場合は、JDBC 接続 URL または java.util.Properties オブジェクトに以下のプロパティを追加します。