CData JDBC Driver for PingOne はじめに：インストールから接続まで

このガイドでは、CData JDBC Driver for PingOne を使い始めるために必要な情報をすべて説明します。ドライバーのインストール方法とライセンス認証の手順から、最初の接続設定、そして Java アプリケーションで PingOne のデータ を活用するための次のステップまでをご紹介します。

インストールとライセンス

ドライバーのインストール

1. CData の Web サイトから JDBC ドライバーのインストーラーをダウンロードします。
2. インストーラーを実行し、インストールウィザードに従って進めます。
3. ドライバーは次の場所にインストールされます： C:\Program Files\CData\CData JDBC Driver for PingOne 20xx\lib\
4. JAR ファイルの名前は cdata.jdbc.pingone.jar です。

インストールが完了したら、IDE やビルドツールを使用して、JAR ファイルを Java プロジェクトのクラスパスに追加できます。

ライセンスの有効化

CData Orders チームから送付されたメールでライセンスキーをお持ちのはずです。英数字のライセンスキーは次のような形式です：

Windows

Windows では、主なライセンス認証方法はライセンスファイルによる方法です。JDBC ドライバーをインストールすると、ライセンスファイルが自動的に作成され、ドライバーのインストールディレクトリに保存されます。アプリケーションで JAR がロードされると、ドライバーはこのライセンスファイルを自動的に検出して使用します。

ライセンスを手動で有効化または更新する必要がある場合は：

1. インストールディレクトリにあるライセンスファイルを見つけます。
2. ライセンスファイルをライセンスキーで更新します。
3. ドライバーは次回の接続時に更新されたライセンスを自動的に使用します。

macOS/Linux

JAR のインストールディレクトリに移動し、lib フォルダーで次のコマンドを実行します： java -jar cdata.jdbc.pingone.jar --license

プロンプトに従ってライセンスキーを入力します。これにより、インストールディレクトリにライセンスファイルが作成され、ドライバーがライセンス認証に使用します。

ライセンスファイルの設定方法について詳しくは、ヘルプドキュメントのGetting StartedサブページにあるLicensingセクションをご覧ください。

ライセンスに関するよくある質問

複数のマシンでライセンスを使用できますか？
はい、サブスクリプションのレベルによります。詳細については、注文確認書をご確認いただくか、担当営業にお問い合わせください。担当営業が不明な場合は、[email protected]までご連絡ください。

ライセンスキーを紛失しました。再発行は可能ですか？
注文番号を記載して[email protected]にメールをお送りください。ライセンスキーを再送いたします。

ライセンスを別のマシンに移行できますか？
はい、可能です。ライセンスを別のマシンに移行する際は、以下のリンクからライセンス移行リクエストを提出する必要があります：

https://jp.cdata.com/contact/

ライセンス移行リクエストが提出され、正常に処理されると、プロダクトキーに新しいアクティベーションが追加され、別のマシンで完全なライセンスを有効化できます。この処理が完了すると、以前のマシンのライセンスは無効になります。

ライセンスファイルの代わりに RTK を使用すべき場合は？
コンテナ、クラウドインスタンス、または複数のマシンにアプリケーションを配布する場合など、マシン/ノード ID が動的に変更される環境にデプロイする場合は RTK を使用してください。

ライセンスに関するその他のご質問は、[email protected]までお問い合わせください。ライセンスの確認とアップグレードは、セルフサービスポータル（portal.cdata.com）から行えるようになりました。

接続の設定

ドライバーのインストールとライセンス認証が完了したら、PingOne への接続を設定できます。JDBC 接続は、接続 URL（接続文字列とも呼ばれます）を使用して確立されます。

JDBC 接続 URL の理解

CData ドライバーの JDBC 接続 URL は次のパターンに従います：

接続 URL の構築

おすすめ：内蔵の接続文字列デザイナーを使用

JDBC ドライバーには、必要なすべての接続プロパティを含む正しい JDBC URL を構築するための接続文字列デザイナーツールが含まれています。

接続文字列デザイナーの起動方法：

1. ドライバーのインストールディレクトリに移動します： C:\Program Files\CData\CData JDBC Driver for PingOne 20xx\lib\
2. JAR ファイルをダブルクリックします：cdata.jdbc.pingone.jar
   または
   コマンドラインから実行します： java -jar cdata.jdbc.pingone.jar
3. 接続文字列デザイナーが起動します。
4. 表示されるフィールドに接続プロパティを入力します。
5. Test Connectionをクリックして設定を確認します。
6. デザイナーから生成された JDBC URL をコピーします。

接続文字列デザイナーを使用すると、正しい構文で記述でき、PingOne で使用可能なすべての接続プロパティを確認できます。

ドライバークラス名

IntelliJ IDEA、Eclipse、DBeaver などの IDE やその他のツールで JDBC ドライバーを設定する際には、ドライバークラス名を指定する必要があります：

接続プロパティの設定

必要な接続プロパティは、データソースによって異なります。

PingOne に接続するには以下のプロパティを設定します。

• Region：自身のPingOne 組織のデータがホスティングされている地域。
• AuthScheme：PingOne に接続する際に使用する認証の種類。
• WorkerAppEnvironmentId （デフォルトのPingOne ドメインを使用する場合に必要）、またはAuthorizationServerURL のいずれかで、下で説明するように設定します。

WorkerAppEnvironmentId の設定

WorkerAppEnvironmentId は、Worker アプリケーションが存在するPingOne 環境のID です。 このパラメータは、環境がデフォルトのPingOne ドメイン（auth.pingone）を利用している場合のみ使用されます。 これは、ヘルプドキュメントのカスタムOAuth アプリケーションの作成で説明するように、PingOne への認証に使用するカスタムOAuth アプリケーションを作成した後に設定します。

はじめに、このプロパティの値を見つけます。

1. 自身のPingOne 組織のホームページからナビゲーションサイドバーに移動し、Environments をクリックします。
2. OAuth / Worker のカスタムアプリケーションを作成した環境（通常はAdministrators）を見つけ、Manage Environment をクリックします。 環境のホームページが表示されます。
3. 環境のホームページのナビゲーションサイドバーで、Applications をクリックします。
4. リストから、OAuth またはWorker アプリケーションの詳細を見つけます。
5. Environment ID フィールドの値をコピーします。 以下の例に似たものになるはずです：
   

   WorkerAppEnvironmentId='11e96fc7-aa4d-4a60-8196-9acf91424eca'

次に、WorkerAppEnvironmentId をEnvironment ID フィールドの値に設定します。

AuthorizationServerURL の設定

AuthorizationServerURL は、お使いのアプリケーションが配置されている環境のPingOne 認可サーバーのベースURL です。 このプロパティは、PingOne プラットフォームAPI ドキュメントで説明されているように、環境にカスタムドメインを設定した場合にのみ使用されます。 Custom Domains を参照してください。

OAuth でのPingOne への認証

PingOne はOAuth とOAuthClient 認証の両方をサポートしています。 上述の設定手順に加え、OAuth またはOAuthCliet 認証をサポートするために、さらに2つの手順を完了する必要があります。

• ヘルプドキュメントのカスタムOAuth アプリケーションの作成で説明するように、カスタムOAuth アプリケーションを作成して設定します。
• ドライバーがデータモデル内のエンティティにアクセスできるようにするには、ヘルプドキュメントのAdministrator Roles での説明のとおり、使用するアドミンユーザー / ワーカーアプリケーションに対して正しいロールを設定していることを確認してください。
• 以下のサブセクションで説明されているように、選択した認証スキームと認証フローに適切なプロパティを設定します。

OAuth（認可コードグラント）

AuthScheme をOAuth に設定します。

デスクトップアプリケーション

OAuth アクセストークンの取得およびリフレッシュ

以下を設定して、接続してください。

• InitiateOAuth：GETANDREFRESH。繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要をなくすには、InitiateOAuth を使用します。
• OAuthClientId：カスタムOAuth アプリケーションを作成した際に取得したClient ID。
• OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に取得したClient Secret。
• CallbackURL：カスタムOAuth アプリケーションの登録時に定義したリダイレクトURI。例：https://localhost:3333

接続すると、CData 製品 はデフォルトブラウザでPingOne のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。 ドライバーはこれでOAuth プロセスを完了します。

1. ドライバーはPingOne からアクセストークンを取得し、それを使ってデータをリクエストします。
2. OAuth 値はOAuthSettingsLocation で指定された場所に保存され、接続間で永続化されるようにします。

ドライバーはアクセストークンの期限が切れると自動的にリフレッシュします。

Web アプリケーションやヘッドレスマシン、クライアントクレデンシャルグラントを含むその他のOAuth メソッドについては、ヘルプドキュメントを参照してください。

PingOne で使用可能なすべての接続プロパティの詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。

接続のテスト

接続は次の方法でテストできます：

接続文字列デザイナーでのテスト

プロパティを入力後、Test Connectionボタンをクリックします。テストが成功すれば、認証情報と接続設定が正しいことが確認できます。

アプリケーションでのテスト

アプリケーションでドライバー JAR を特定の場所に移動する必要がある場合は、今すぐ移動し、JAR がアプリケーションのクラスパスに含まれていることを確認してください。また、ライセンス認証のために .lic ファイルも同じ場所に移動してください。

注意： DBeaver などの多くの JDBC 対応ツールでは、Test Connection 機能を使用する際にプロバイダーへのライブリクエストは実際には送信されません。 これは表面的なテストのみで、基本的に JAR ファイルが基本レベルで機能することをチェックするだけです。 JDBC 対応ツールを使用する場合は、有効な接続テストを確認するために ConnectOnOpen プロパティを True に設定する必要があります。

IDE で JDBC ドライバーを使用している場合は、簡単なクエリを実行して接続を確認できます：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

String url = "jdbc:pingone:AuthScheme=OAuth;WorkerAppEnvironmentId=eebc33a8-xxxx-4f3a-yyyy-d3e5262fd49e;Region=NA;OAuthClientId=client_id;OAuthClientSecret=client_secret;
Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM [CData].[Administrators].Users LIMIT 1");

if (rs.next()) {
    System.out.println("Connection successful!");
}

接続エラーが発生した場合は：

1. 接続文字列デザイナーを使用して、接続プロパティが正しいことを確認します。
2. ドライバー JAR がアプリケーションのクラスパスに含まれていることを確認します。
3. エラーメッセージを確認し、具体的なガイダンスを参照します。
4. トラブルシューティングのサポートが必要な場合は、エラーの詳細を添えて[email protected]にお問い合わせください。

よくある接続の問題

ドライバーが見つからない / ClassNotFoundException

解決方法：JDBC ドライバー JAR（cdata.jdbc.pingone.jar）がプロジェクトのクラスパスに正しく追加されていることを確認してください。設定方法は IDE やビルドツールによって異なります。開発環境のドキュメントを参照するか、[email protected]にサポートをお問い合わせください。

認証エラー

解決方法：認証情報が正しく、最新であることを確認してください。接続文字列デザイナーを使用して、アプリケーションに追加する前に認証情報をテストしてください。PingOne の認証要件の詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。

ネットワーク接続の問題

解決方法：ファイアウォールが必要なポートでの送信接続を許可していることを確認してください。データソースの具体的なポートとファイアウォール要件については、[email protected]にお問い合わせください。

無効な接続文字列フォーマット

解決方法：接続文字列デザイナーを使用して、正しい形式の JDBC URL を生成してください。デザイナーは正しい構文とプロパティ名を保証します。

その他のトラブルシューティングについては、具体的なエラーメッセージを添えて[email protected]にお問い合わせください。

次のステップ

ドライバーのインストール、ライセンス認証、設定が完了したので、CData JDBC ドライバーを活用する次のシナリオをご覧ください：

サポート

サポートが必要な場合は、以下までお問い合わせください：

• テクニカルサポート： [email protected]
• ナレッジベース： CData ナレッジベース
• コミュニティフォーラム： CData コミュニティサイト
• ヘルプドキュメント： ローカルにインストール済み、およびオンラインでも利用可能

よくある質問

インストールとライセンス

• JDBC ドライバーはどこにインストールされますか？
  デフォルトのインストールディレクトリは以下のとおりです：
  Windows： C:\Program Files\CData\CData JDBC Driver for PingOne \lib
  Mac： /Application/CData JDBC Driver for PingOne /lib
  Linux： /home//CData/CData JDBC Driver for PingOne /lib
• ライセンスキーを取得するには？
  ライセンスキーはご購入時にメールで送信されます。再送が必要な場合は、注文番号を添えて[email protected]にお問い合わせください。
• 複数のアプリケーションでライセンスを使用できますか？
  はい、可能です。ライセンスファイルは、マシン上でドライバーを使用するすべての Java アプリケーションで機能します。
• RTK（Runtime Key）を使用すべき場合は？
  コンテナ（Docker/Kubernetes）、クラウドインスタンス、または複数のマシンにアプリケーションを配布する場合など、マシン/ノード ID が動的に変更される環境にデプロイする場合は RTK を使用してください。RTK が必要な場合は、担当営業にお問い合わせください。

接続

• JDBC 接続 URL はどのように構築しますか？
  内蔵の接続文字列デザイナーツールを使用してください。ドライバー JAR をダブルクリックするか、java -jar cdata.jdbc.pingone.jar を実行してデザイナーを起動します。正しい形式の接続 URL の構築をサポートします。
• ドライバークラス名は何ですか？
  ドライバークラスは次のパターンに従います：cdata.jdbc.pingone.PingOneDriver
  IntelliJ IDEA、Eclipse、DBeaver などの IDE でドライバーを設定する際に必要です。
• PingOne に必要な接続プロパティは何ですか？
  PingOne の必須およびオプションの接続プロパティの詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。接続文字列デザイナーでも利用可能なすべてのプロパティを確認できます。
• 複数の PingOne アカウントに接続するには？
  アカウントごとに異なる認証情報を使用して、個別の接続 URL を作成します。アプリケーション内で複数の接続を管理できます。
• 認証情報を安全に保存するには？
  環境変数、設定ファイル、またはシークレット管理システム（AWS Secrets Manager や Azure Key Vault など）を使用してください。認証情報をソースコードにハードコードしないでください。

使用方法と開発

• どの SQL 操作がサポートされていますか？
  サポートされている SQL 操作の一覧については、ヘルプドキュメントのSQL Compliance章をご覧ください。
• マルチスレッドアプリケーションでドライバーを使用できますか？
  はい、可能です。スレッドセーフのための標準的な JDBC のベストプラクティスに従ってください。同時アクセスには接続プーリングを使用してください。
• IDE にドライバーを追加するには？
  JAR ファイル（cdata.jdbc.pingone.jar）をプロジェクトのクラスパスに追加します。外部 JAR の追加については、IDE のドキュメントを参照してください。ドライバークラス名は：cdata.jdbc.pingone.PingOneDriver

パフォーマンスとトラブルシューティング

• クエリが遅いのはなぜですか？
  以下を確認してください：
  • 接続プーリングを使用します。
  • フィルター（WHERE 句）を追加して結果セットのサイズを減らします。
  • クエリの最適化のサポートについては、[email protected]にお問い合わせください。
• トラブルシューティングのためにログを有効にするには？
  接続文字列にログプロパティを追加するか、Logfile プロパティを有効なファイルパスに設定し、Verbosity プロパティを目的のログレベルに設定して、アプリケーションでログを設定します（HTTP リクエストとレスポンスをキャプチャするには Verbosity=3 を推奨します）。ログ設定の詳細については、ヘルプドキュメントのAdvanced Featuresセクションをご覧ください。トラブルシューティングのサポートについては、[email protected]にお問い合わせください。
• どのファイアウォールポートを開く必要がありますか？
  ポート要件はデータソースによって異なります。ほとんどのクラウドアプリケーションは HTTPS（ポート 443）を使用します。必要に応じて、ヘルプドキュメントのAdvanced FeaturesセクションでFirewall & Proxy設定を参照してください。PingOne の具体的なファイアウォール要件については、[email protected]にお問い合わせください。
• Docker でドライバーをデプロイするには？
  Docker イメージにドライバー JAR を含め、接続文字列で RTK（Runtime Key）を使用してライセンス認証を行います。これにより、動的なコンテナのノード ID が処理されます。
• ClassNotFoundException が発生します。どうすれば修正できますか？
  これは、ドライバー JAR がクラスパスにないことを意味します。JAR ファイルの場所を確認し、IDE またはビルド設定でプロジェクトのクラスパスに追加されていることを確認してください。

全般

• ヘルプドキュメントはどこにありますか？
  ヘルプドキュメントは、インストールディレクトリ内のドライバーとともにインストールされており、CData の Web サイトでも利用可能です。
• ドライバーはどのくらいの頻度で更新されますか？
  CData は年に一度、ドライバーのメジャーバージョンアップデートをリリースしています。最新バージョンについては、アカウントポータルを確認するか、[email protected]にお問い合わせください。
• 特定のユースケースのコード例はありますか？
  はい、あります。ヘルプドキュメントには多数のコード例が含まれています。特定のシナリオの例が必要な場合は、[email protected]にお問い合わせください。

この FAQ で取り上げられていないご質問は、[email protected]にお問い合わせください。