JDBCサービス・プロバイダ拡張機能

10.1 一元化された構成プロバイダ

これらのプロバイダを使用して、データベース・クライアントの分散構成をサポートします。

ノート:

ペイロードおよび形式の仕様は、.NETおよびC++クライアントで確認できます。

一元化された構成プロバイダはOracle JDBCドライバに対し、接続文字列(JDBC URL)を含むデータベース接続の作成に必要な情報、およびオプションでユーザーID、データベース・パスワード、ウォレットの場所などのJDBC接続プロパティを提供します。データベース・パスワードやウォレットの場所などの機密情報は、通常、ボールトに別々に格納されます。

サービス・プロバイダ契約は、次のように定義されます。JDBC URLが次の形式の場合:

jdbc:oracle:<driver type>:@config-<provider>

ドライバは、登録済サービス・プロバイダのリストから<provider>のロードを試行します。たとえば:

jdbc:oracle:thin:@config-azure:myappconfig?key=sales_app1&label=dev

アプリケーションで外部プロバイダを検出できるようにするには、次の点に注意する必要があります。

JDBCドライバで使用可能なoracle.jdbc.spi.OracleConfigurationProviderインタフェースを実装します。
getTypeメソッドをオーバーライドして、<provider>のURL文字列を指定します。
JDBCドライバで使用されるプロパティを返すgetConnectionPropertiesメソッドの実装を指定します。

オラクル社では、次のサービスの構成プロバイダとして個別のJARファイルをMaven Centralリポジトリに配布します。

Azure App Configuration (シークレットについてAzure Key Vaultをオプションで参照)
OCIオブジェクト・ストレージ(シークレットについてOCI Vaultをオプションで参照)
OCIデータベース・ツール接続(シークレットについてOCI Vaultをオプションで参照)

独自のプロバイダを構築する場合は、oracle.jdbc.spi.OracleConfigurationProviderインタフェースを拡張し、Java SPI仕様に従う必要があります。

10.1.1 Azure App Configuration

Oracleデータ・ソースでは、新しい接頭辞jdbc:oracle:thin:@config-azure:を使用して、Azure App Configurationを使用するためにロードする必要がある構成パラメータを識別できます。

既存のアプリケーションでこの機能を透過的に使用できるようにするには、Azure App Configurationの名前、およびオプションでキー名の接頭辞とラベルを次の構文で指定することのみ必要です。

jdbc:oracle:thin:@config-azure:{appconfig-name}[?key=prefix&label=value&option1
=value1&option2=value2]

唯一の要件は次のとおりです。

プロバイダJARファイルをクラスパスに含めるか、プロバイダ参照をPOMファイルに含めます。
既存のURL値を必要な値に置き換えます。

この機能により、データ・ソースの値がキー(Azure App Configuration内の複数のキーの接頭辞)およびラベルにアタッチされます。キーとラベルの両方ともオプションです。これらが指定されていない場合、構成にラベルおよび接頭辞なしですべての値がアタッチされます。

このキーとラベルのペアで確認される4つの固定値を次に示します。

connect_descriptor (必須)
user (オプション)
password (オプション)
wallet_location (オプション)

残りの値はJDBCドライバによって異なり、jdbc/接頭辞が付きます。特定のラベルとキーについて複数のキーと値のペアが取得され、データ・ソースに適用されます。キー値は、OracleConnectionインタフェースで定義されたプロパティ(定数キー)です。

たとえば、アプリケーション構成(myappconfigなど)の値jdbc:oracle:thin:@config-azure:myappconfig?key=/sales_app1/&label=devを含むデータ・ソースURLでは、次の値に類似した値を持つOracleDatasourceが生成されます。

ノート:

接頭辞は/sales_app1/で、ラベルはdevであることに注意してください。
JDBCドライバは、接続記述子をjdbc:oracle:thin:@と内部的に連結してURLを設定します。これにより、プロパティを他のドライバ実装と共有できます。

キー	値	ラベル	JDBCドライバ接続プロパティ
`/sales_app1/user`	`scott`	dev	`user=scott`
`/sales_app1/password`	`{"uri":"https://mykeyvault.vault.azure.net/secrets/<password>"}`	dev	`password=<password>` (URI内のシークレットの値)
`/sales_app1/wallet_location`	`{"uri":"https://mykeyvault.vault.azure.net/secrets/<wallet_location>"}`	dev	`oracle.net.wallet_location (value: "data:;base64,<value of the secret in the URI>")`
`/sales_app1/connect_descriptor`	`(description=(retry_count=20)(retry_delay=3s) (address=(protocol=tcps)(port=1521) (host=myserver.oraclecloud.com)) (connect_data=(service_name=myservice.oraclecloud.com)) (security=(ssl_server_dn_match=yes) (ssl_server_cert_dn="CN=DN1.oraclecloud.com, OU=Oracle US, O=Oracle Corporation, L=Redwood City, ST=California, C=US")))`	dev	`URL=jdbc:oracle:thin:@(description= (retry_count=20)(retry_delay=3s) (address=(protocol=tcps)(port=1521) (host=myserver.oraclecloud.com)) (connect_data=(service_name= myservice.oraclecloud.com))(security= (ssl_server_dn_match=yes)(ssl_server_cert_dn= "CN=DN1.oraclecloud.com, OU=Oracle US, O=Oracle Corporation, L=Redwood City, ST=California, C=US")))`
`/sales_app1/jdbc/autoCommit`	`false`	dev	`autoCommit=false`
`/sales_app1/jdbc/oracle.jdbc.loginTimeout`	20	dev	`oracle.jdbc.loginTimeout=20`
`/sales_app1/jdbc/oracle.jdbc.fanEnabled`	`false`	dev	`oracle.jdbc.fanEnabled=false`

次のコード・スニペットは、サンプルJavaクライアントの関連詳細を示しています。


OracleDataSource ds = new OracleDataSource();
ds.setURL("jdbc:oracle:thin:@config-azure:myappconfig?key=sales_app1&label=dev");
Connection cn = ds.getConnection();
Statement st = cn.createStatement();
ResultSet rs = st.executeQuery("select sysdate from dual");

10.1.2 OCIオブジェクト・ストレージ

この構成プロバイダを使用するには、シークレットについてOCI Vaultへのオプションの参照を行う必要があります。

この場合、構成はすべてのクライアントに共通するJSON形式で格納されます。プロバイダは、次の例に示すように、URLのociobjectプロバイダによって識別されます。

jdbc:oracle:thin:@config-ociobject:
https://objectstorage.oraclecloud.com/myjava/bucket1/payload_ojdbc_objectstorage.json

必須パラメータは、オブジェクトのURLパス(URI)のみです。この値は、次のナビゲーションを使用してOCI Webコンソールから取得できます: Object Storage / Buckets / Object → Object Details。これにより、次のような値が取得されます。

https://objectstorage.oraclecloud.com/myjava/bucket1/payload_ojdbc_objectstorage.json

このprefixとlabelのペアで確認される4つの固定値があります。

connect_descriptor (必須)
user (オプション)
password (オプション)
wallet_location (オプション)

残りの値はJDBCドライバによって異なり、jdbc/接頭辞が付きます。特定のラベルとキーについて複数のキーと値のペアが取得され、データ・ソースに適用されます。キー値は、OracleConnectionインタフェースで定義されたプロパティ(定数キー)です。

次のコード・スニペットに示すように、passwordおよびwallet_locationはVaultプロバイダへの参照です。

ノート:

Vaultプロバイダは、タイプとしてvault-azureを使用するAzure Key Vaultにすることもできます。


{"connect_descriptor": "(description=(retry_count=20)(retry_delay=3s)
(address=(protocol=tcps)(port=1521)(host=myhost.oraclecloud.com))
(connect_data=(service_name=myservice.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))",
  "user": "scott",
  "password": { 
    "type": "vault-oci",
    "value": "myvalue",
    "authentication": {
      "method": "OCI_INSTANCE_PRINCIPAL"
    }
  },

  "wallet_location": { 
    "type": "vault-oci",
    "value": "myvalue",
    "authentication": {
      "method": "OCI_INSTANCE_PRINCIPAL"
    }
  },
  "jdbc": {
    "oracle.jdbc.ReadTimeout": 1000,
    "defaultRowPrefetch": 20,
    "autoCommit": "false"
}}

1つのペイロードに複数のキーを設定し、URLにオプションの名前を追加できます。たとえば:

jdbc:oracle:thin:@config-ociobject:{object-url}
[?key=name&option1=value1&option2=value2]

次の例では、sales_app1およびhr_internal_app1という2つのキーを使用します。


{
  "sales_app1":
  {"connect_descriptor": "(description=(address=(protocol=tcps)
(port=1521)(host=myhost.oraclecloud.com))
    (connect_data=(service_name=myservice.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))",
    "user": "scott",
    "password": { 
      "type": "vault-oci",
      "value": "myvalue",
      "authentication": {
        "method": "OCI_INSTANCE_PRINCIPAL"
      }
    },
    "jdbc": {
      "oracle.jdbc.ReadTimeout": 1000,
      "defaultRowPrefetch": 20,
      "autoCommit": "false"
    }
  },
  "hr_internal_app1":
  {"connect_descriptor": "(description=(address=(protocol=tcps)
(port=1521)(host=myhost.oraclecloud.com))
    (connect_data=(service_name=myservice.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))",
    "user": "scott",
    "password": { 
      "type": "vault-oci",
      "value": "myvalue",
      "authentication": {
        "method": "OCI_INSTANCE_PRINCIPAL"
      }
    },
    "jdbc": {
     "oracle.jdbc.ReadTimeout": 0,
     "defaultRowPrefetch": 100,
     "autoCommit": "true"
    }
  }
}

10.1.3 OCIデータベース・ツール

この構成プロバイダを使用するには、シークレットについてOCI Vaultへのオプションの参照を行う必要があります。

OCIデータベース・ツール・サービスは、Oracle Autonomous DatabaseまたはMySQLのいずれかのデータベースへの接続を構成するために使用できるマネージド・サービスです。Webコンソールで、SQLワークシートにconnectionオブジェクトを使用できます。データベース接続構成のディレクトリとして使用することも、これらの構成へのアクセスを可能にするプロバイダとして使用することもできます。各構成には、使用される接続を識別するために使用されるOracle Cloud Identifier (OCID)があります。これには、connectionString、userName、userPassword、keyStoresおよびadvancedPropertiesが含まれます。advancedPropertiesは現在、JDBCプロパティに制限されています。

この例は、OCIデータベース・ツール・プロバイダを使用するJDBC URLを示しています。

jdbc:oracle:thin:@config-ocidbtools:ocid1.databasetoolsconnection

10.1.4 組込み構成プロバイダ

JDBCドライバには、1つのHTTPSプロバイダと1つのファイル・プロバイダという2つの組込み構成プロバイダが含まれています。

OCIオブジェクト・ストレージに使用されるものと同じJSONスキーマに基づいているため、これらのプロバイダを使用する際に追加のJARファイルは必要ありません。つまり、このスキーマは、すべてのJSONベース・プロバイダ(HTTPS、ファイルおよびOCIオブジェクト・ストレージ)に対して同じです。

関連項目:

Oracle Database JDBC Java APIリファレンス

HTTPS構成プロバイダ

JSON構成ドキュメントは、Oracle REST Data Services (ORDS)などのHTTPSエンドポイントを通じて提供できます。JSON構成ドキュメントに複数の別名が含まれている可能性があるため、HTTPはサポートされていません。そのため、URLはロードする必要がある別名(https://<URL>/aliasnameなど)で終わる必要があります。

IP ACL、TCPSおよびHTTP Basic認証を使用して、この構成ドキュメントへのアクセスを保護できます。

JDBC URLには次の形式を使用します。

jdbc:oracle:thin:@config-https://<URL>[?key=name&option1=value1]

https接頭辞の後にホストが続くため、httpまたはhttpsのいずれであっても、プロバイダ名の後に二重スラッシュ(//)が必要です。

次の例のように、プロパティによりウォレットを使用して、HTTPSを介したHTTP Basic認証でクライアント認証を構成できます。

jdbc:oracle:thin:@config-https://confighost.mydomain.com/oracleconfig?
key=name&authentication=BASIC_AUTH&wallet_location=/path/to/wallet

認証オプションを使用して、HTTP構成プロバイダでHTTP Basic認証を使用してJSON構成ドキュメントを取得するように指定できます。

ノート:

オラクル社が配布するHTTPS構成プロバイダは、HTTP Basic認証をサポートしています。

ファイル構成プロバイダ

この場合、JSON構成ドキュメントはファイル・システムを介して提供され、この構成へのアクセスはファイル・システムの保護によって保護されます。ファイル構成プロバイダの場合、JDBC URLは次の書式に従います。

jdbc:oracle:thin:@config-file:{path-to-file}[?option list]

ここで、{path-to-file}パラメータは、java.io.Fileクラスと同じルールを受け入れます。オプション・リストには、次の例のsales_app1のように、接続キー名を示す属性が含まれます。

jdbc:oracle:thin:@config-file:path/to/file.json?key=sales_app1

10.2 リソース・プロバイダ

リソース・プロバイダは、パスワードや接続文字列などの単一のリソースをOracle JDBCに提供します。

リソース・プロバイダは、接続プロパティによって構成されます。たとえば、次の接続プロパティを使用してパスワード・プロバイダを構成できます。

  oracle.jdbc.provider.password=example-provider
  oracle.jdbc.provider.password.vaultId=9999-8888-7777

前述の例では、oracle.jdbc.provider.passwordプロパティはパスワード・プロバイダの名前を構成します。oracle.jdbc.provider.password.vaultIdプロパティは、パスワード・プロバイダで認識されるパラメータを構成します。

リソース・プロバイダは、次のいずれかのリソースを提供できます。

データベース接続文字列
データベース・ユーザー名
データベース・パスワード
データベース・アクセス・トークン
TLS/SSL構成
トレース・イベント・リスナー

前述のリストに対応して、次の接続プロパティでリソース・プロバイダの名前を識別します。

oracle.jdbc.provider.connectionString
oracle.jdbc.provider.username
oracle.jdbc.provider.password
oracle.jdbc.provider.accessToken
oracle.jdbc.provider.tlsConfiguration
oracle.jdbc.provider.traceEventListener

接続プロパティとして追加パラメータを構成することもできます。

関連項目:

10.3 トレース・イベント・リスナー・プロバイダ

Oracle Databaseリリース23ai以降、JDBCドライバはJDBCアプリケーションの監視に使用できるイベントを生成できます。

JDBCドライバで定義されるoracle.jdbc.spi.TraceEventListenerProviderインタフェースを使用して、SPIメカニズムによりカスタムTraceEventListenerを登録できます。

たとえば、この機能を使用して、次のイベントをOpenTelemetryに公開するリスナーを登録できます。

問合せ実行時のデータベース・ラウンドトリップ
接続の確立中の仮想IPアドレスの再試行
アプリケーション・コンティニュイティ使用時におけるデータベース停止からのリカバリの開始
アプリケーション・コンティニュイティ使用時におけるデータベース停止からの正常なリカバリ

関連項目:

詳細は、「JDBC Javadoc」を参照してください。

10.4 クラウド・ベンダー用のJDBC拡張機能

Oracle JDBCドライバ拡張機能には、一元化された構成用のプロバイダや、データベースでの認証用のトークン・プロバイダが含まれています。

これらの拡張機能は、クラウド・コンピューティング・プラットフォームなどの広く使用されているサービスと統合するためのサービス・プロバイダ・インタフェース(SPI)の実装に役立ちます。拡張機能は、次のリンクにあるGitHubのオープン・ソースであり、アーティファクトはMaven Centralで使用できます:

https://github.com/oracle-samples/ojdbc-extensions/tree/main

一元化された構成プロバイダの場合、拡張機能には次のプロバイダが含まれます:

OCI DBTools接続
Azure App Configuration

リソース・プロバイダの場合、これらの拡張機能には次のプロバイダが含まれます:

Oracle Autonomous Database Serverlessを使用しながら、OCI IAM (Identity and Access Management)またはAzure AD (Active Directory)によって発行された認証トークン
OCI VaultシークレットまたはAzure Vaultシークレットに格納されているデータベース・パスワードまたはユーザー名
mTLS接続用のOracle Autonomous Database ServerlessからのJDBC URLおよびクライアント・ウォレット
OpenTelemetryに格納されているJDBCイベント

関連項目:

詳細は、GitHubのOracle JDBCドライバ拡張機能を参照してください

10 JDBCサービス・プロバイダ拡張機能

10.1 一元化された構成プロバイダ

10.1.1 Azure App Configuration

10.1.2 OCIオブジェクト・ストレージ

10.1.3 OCIデータベース・ツール

10.1.4 組込み構成プロバイダ

10.2 リソース・プロバイダ

10.3 トレース・イベント・リスナー・プロバイダ

10.4 クラウド・ベンダー用のJDBC拡張機能