JDBC を使用した Dataphin への接続 | Dataphin - Dataphin - Alibaba Cloud ドキュメントセンター

このトピックでは、Java Database Connectivity (JDBC) ドライバーを使用して Dataphin に接続する方法について説明します。

前提条件

Dataphin JDBC は、Dataphin OpenAPI を使用して SQL クエリを実行します。Dataphin JDBC を使用する前に、Dataphin OpenAPI 機能を有効にする必要があります。

機能概要

2 つの認証モード：Dataphin JDBC は、基本モードとプロキシモードの 2 つの認証モードをサポートしています。詳細については、「認証モード」をご参照ください。
一貫した実行結果：Dataphin JDBC を使用して SQL 文を実行することは、Dataphin で SQL 文を実行することと同じです。そのため、SQL の実行結果は Dataphin UI の結果と一致します。権限、データマスキングルール、セキュリティ設定、コード仕様などの Dataphin の設定も、Dataphin JDBC の実行結果に影響します。

制限事項

コンピュートエンジンが Databricks、SelectDB、または Doris の場合、Dataphin は JDBC 接続をサポートしません。
Dataphin JDBC が SQL 文を実行すると、Dataphin は SQL 変換やデータマスキングなどの前処理操作を実行します。結果データも Dataphin を介して送信および転送されます。これらのプロセスにより、パフォーマンスが低下します。そのため、クエリはコンピュートエンジンへの直接クエリよりも時間がかかります。
Dataphin JDBC は、Dataphin OpenAPI を介して Dataphin に SQL 文を送信することで実行します。その後、Dataphin は文を処理し、実行のために基盤となるコンピュートエンジンに送信します。Dataphin JDBC を使用する前に、呼び出し回数を評価し、Dataphin クラスターとコンピュートエンジンをスケールアウトする必要があるかどうかを判断する必要があります。
説明
容量を評価できない場合は、Dataphin クラスターの容量評価リクエストを Dataphin 運用保守 (O&M) チームに送信できます。このリクエストには、コンピュートエンジンの容量評価は含まれません。
Dataphin は速度制限や同時実行制御をサポートしていません。影響を慎重に評価する必要があります。

JDBC ドライバーのバージョンとダウンロードリンク

ドライバーの JAR パッケージを入手するには、Dataphin の O&M エンジニアにお問い合わせください。

接続パラメーター

説明

Dataphin JDBC がプラットフォームの AccessKey ID と AccessKey Secret (プロキシモード) を使用する場合、set 構文を使用してアクセスユーザーを指定できます。

set dp_delegation_uid = 'target_source_user_uid';
set dp_delegation_name = 'target_user_name';

JDBC URL フォーマット：jdbc:dataphin://host:port/catalog?[tenant_id=TenantID][&ssl=true][&log_level=Log_Level][&user=UserName][&password=PassWord][&delegation_uid=DelegationUid][&account_type=AccountType][&connect_timeout=ConnectTimeout][&engine=engine_type][compute_project=ProjectName]

重要

パラメーター名では大文字と小文字が区別されます。
角括弧 ([]) は説明のためだけに使用されています。コマンドを実行する際には、これらを削除する必要があります。

パラメーター	必須	説明	例
host	はい	Dataphin OpenAPI のドメイン名。 Dataphin のドメイン名は、[個人センター] > [AccessKey 管理] の [OpenAPI 呼び出しアドレス] から取得できます。次の図に例を示します。	dataphin-openapi.****.aliyun.com
port	いいえ	ポート番号は、Dataphin OpenAPI で HTTPS が有効になっているかどうかによって異なります。HTTPS が有効な場合、ポートは `443` です。HTTPS が有効でない場合、ポートは `80` です。デフォルト値は 80 です。	80
catalog	はい	デフォルトのクエリ可能なデータ範囲。 Dataphin 物理テーブルを使用するには、Dataphin プロジェクトの英語名 (project_name) を入力します。 Dataphin 論理テーブルを使用するには、Dataphin データドメインの英語名を入力します。名前は `LD_` で始まる必要があります。 Dataphin が管理するデータソーステーブルを使用するには、Dataphin で設定されているデータソースのコードを入力します。コードは `ds_` で始まる必要があります。説明デフォルトのクエリ可能な範囲がデータドメインの場合、compute_project は必須です。デフォルトのクエリ可能な範囲がDataphin が管理するデータソーステーブルの場合、compute_project を指定する必要はありません。	Exprojectname
tenant_id	はい	クエリ対象のテナントの ID。	111***111
ssl	いいえ	HTTPS を使用するかどうかを指定します。 True：HTTPS ドメイン名を使用します。 False：HTTP ドメイン名を使用します。これはデフォルト値です。	False
currentschema	いいえ	データソースのスキーマ。カタログで Dataphin の物理テーブルまたは論理テーブルを使用する場合、このパラメーターを指定する必要はありません。カタログで使用されるデータソースタイプが MySQL のようにスキーマをサポートしていない場合、このパラメーターを指定する必要はありません。カタログで使用されるデータソースタイプが Oracle のようにスキーマをサポートしている場合、このパラメーターはオプションです。スキーマを指定すると、指定されたスキーマ内のデータがクエリされます。スキーマを指定しない場合、データベースのデフォルトスキーマがクエリされます。	information_schema
compute_project	いいえ	プロジェクトの英語名。このプロジェクトは SQL クエリの実行に使用されます。プロジェクトとそのアタッチされたコンピュートエンジンには、クエリ対象のテーブルに対する読み取り権限が必要です。指定されたクエリ範囲が Dataphin プロジェクトの場合、このパラメーターはオプションです。このパラメーターを指定しない場合、デフォルトのクエリ範囲で指定されたプロジェクトが SQL 文の実行に使用されます。指定されたクエリ範囲が Dataphin データドメインの場合、このパラメーターは必須です。指定されたクエリ範囲が Dataphin データソースの場合、このパラメーターを指定する必要はありません。	Exprojectname
user	はい	ユーザーまたはプラットフォームの AccessKey ID。プロキシモードでは、プラットフォームの AccessKey ID を使用します。プラットフォームの AccessKey ID を取得するには、Dataphin の O&M チームにお問い合わせください。ユーザーの AccessKey ID は、[個人センター] > [AccessKey 管理] で取得できます。	kIB**********PT0
log_level	いいえ	ログレベル。有効な値： DEBUG INFO WARNING ERROR	DEBUG
password	はい	アクセスユーザーの AccessKey Secret。プラットフォームの AccessKey を取得するには、Dataphin の O&M チームにお問い合わせください。ユーザーの AccessKey ID は、[個人センター] > [AccessKey 管理] で取得できます。	Cy**************r2T
delegation_uid	いいえ	プラットフォームの AccessKey を使用する場合、他のユーザーのプロキシとして機能し、接続を確立して Dataphin にアクセスできます。このパラメーターは、プロキシされる Dataphin ユーザーを指定します。プロキシされる Dataphin ユーザーについては、選択した account_type に基づいて対応するアカウント ID を渡す必要があります。このパラメーターを設定すると、認証にプロキシモードが使用されます。	999***999
account_type	いいえ	認証にプロキシモードを使用する場合、プロキシされるユーザーのアカウントタイプを指定する必要があります。 ACCOUNT_NAME：Dataphin のユーザー名。アプリケーションのユーザー名が Dataphin のユーザー名と同じ場合に推奨されるモードです。 USER_ID：Dataphin の一意の ID。このモードは推奨されません。 SOURCE_USER_ID：ソースシステムのアカウント ID。これは、Dataphin が Resource Access Management (RAM)、Security Assertion Markup Language (SAML)、または OAuth 認証などのシングルサインオン (SSO) 認証で構成されている場合に使用できます。これは、ID プロバイダー (IDP) のユーザーアカウントです。説明このパラメーターは、delegation_uid が設定されている場合にのみ設定する必要があります。このパラメーターを指定しない場合、デフォルトのタイプは USER_ID です。重複するユーザーが存在する場合、認証は失敗します。	USER_ID
connect_timeout	いいえ	接続を取得するための最大タイムアウト期間 (秒単位)。 0 より大きい：タイムアウト期間。最小値は 10 秒です。 0 以下：無期限に待機します。	10
engine	いいえ	セッションまたは接続文字列の project_name で指定されたプロジェクトのオフラインエンジン。Hadoop コンピュートソースの場合、デフォルトのエンジンは Hive です。このパラメーターを Impala または Spark に設定できます。エンジンタイプを設定するには、事前にコンピュートソースで設定する必要があります。指定されたエンジンがプロジェクトでサポートされていない場合、設定は無視されますが、アラートが報告されます。有効な値： MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark 説明このパラメーターは、データソースにアクセスする際には無視されます。	MaxCompute
acceleration_source	いいえ	アクセラレーションソースを指定します。テナント内の任意のアクセラレーションソースのコードを選択できます。	starrocks_code
acceleration_resource_group	いいえ	アクセラレーションリソースグループ。選択したアクセラレーションソース用に設定されたリソースグループを選択できます。	starrocks_resource_group

認証モード

基本モード

ユーザー名をユーザーの AccessKey ID に、パスワードをユーザーの AccessKey Secret に設定できます。現在のアクセスは、そのユーザーとして識別されます。AccessKey の表示方法の詳細については、「Dataphin OpenAPI AccessKey 管理」をご参照ください。

JDBC ドライバーを使用して Dataphin にアクセスすると、Dataphin は AccessKey を認証し、AccessKey のユーザーにリソースへのアクセスまたは SQL 文の実行を許可します。その後、Dataphin は SQL 文を実行するユーザーを識別します。

プロキシモード

重要

プロキシモードを使用する前に、この機能を有効にして設定するために Dataphin の O&M チームに連絡する必要があります。

プロキシモードは通常、システムと Dataphin の統合に使用されます。この方法により、異なるユーザーに AccessKey を配布または設定する必要がなくなります。JDBC 接続文字列 (JDBC URL) でプロキシユーザーを指定することで、指定されたユーザーに基づいて操作が承認されることを保証できます。プラットフォームレベルの AccessKey は高い権限を持ち、すべてのユーザーのプロキシとして機能できます。次の図に示すように、クライアントはプラットフォームの AccessKey で設定されています。userA がクライアントにアクセスする場合、このアクセスが userA のプロキシであることを示すために delegation_uid=userA を指定する必要があります。その後、userA の関数権限とデータ権限が権限検証に使用されます。

Dataphin ドライバーの詳細

com.aliyun.dataphin.jdbc.DataphinDriver

インターフェース	機能説明	インターフェース定義
connect	データベース接続を取得します。	`Connection connect (String url, Properties info) throws SQLException;`
acceptsURL	URL がサポートされているかどうかを確認します。	`boolean acceptsURL(String url) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinConnection

インターフェース

説明

インターフェース定義

createStatement

Statement オブジェクトを作成します。

Statement createStatement
(int resultSetType, 
int resultSetConcurrency)
throws SQLException;

prepareStatement

PreparedStatement オブジェクトを作成します。

PreparedStatement prepareStatement(String sql, int resultSetType,int resultSetConcurrency)throws SQLExcept;
PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability);

com.aliyun.dataphin.jdbc.DataphinStatement

インターフェース	説明	インターフェース定義
executeQuery	SQL 文を実行し、ResultSet オブジェクトを返します。	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	指定された行数に基づいて結果データをバッチで取得します。このパラメーターが設定されていないか、0 に設定されている場合、デフォルト値は 1,000 です。	`void setFetchSize(int rows) throws SQLException`
cancel	Statement オブジェクトの実行をキャンセルします。	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

インターフェース	説明	インターフェース定義
executeQuery	SQL 文を実行し、ResultSet オブジェクトを返します。	`ResultSet executeQuery (String sql) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

インターフェース	説明	インターフェース定義
getColumnCount	結果スキーマの列数を取得します。	`int getColumnCount() throws SQLException;`
getColumnName	結果スキーマの列名を取得します。	`int getColumnCount() throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

インターフェース	説明	インターフェース定義
next	SQL 実行結果のデータを 1 行ずつ取得します。	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

インターフェース

説明

インターフェース定義

getTables

テーブル情報を取得します。

パラメーターの説明：
- catalog：デフォルト値は default です。
- schemaPattern：プロジェクト名またはデータドメイン名。
- tableNamePattern：テーブル名。あいまい一致がサポートされています。正規表現はサポートされていません。
- types：このパラメーターはサポートされていません。
戻り結果：
- ResultSet オブジェクトが返されます。
- next メソッドを呼び出して、SQL 実行結果のデータを 1 行ずつ取得できます。各行には、単一のテーブルのメタデータが含まれています。テーブル名のみ取得できます。
テーブル名の取得：
- resultSet.getString("table_name")

getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException

getColumns

テーブルのフィールド情報を取得します。

パラメーターの説明：
- catalog：プロジェクト名またはデータドメイン名。
- schemaPattern：このパラメーターはサポートされていません。
- tableNamePattern：テーブルの完全名。あいまい一致と正規表現はサポートされていません。
- columnNamePattern：このパラメーターはサポートされていません。
戻り結果：
- ResultSet オブジェクトが返されます。
- next メソッドを呼び出して、SQL 実行結果のデータを 1 行ずつ取得できます。各行には、テーブル内の単一のフィールドのメタデータが含まれています。列名とデータの型のみ取得できます。
列名の取得： resultSet.getString("column_name")。
列のデータの型の取得： resultSet.getString("data_type")。

ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern)

例

Dataphin JDBC ドライバーを使用してカタログ情報を取得できます。

1. テーブルのリストの取得

この操作では、プロジェクト内の物理テーブルと物理ビューのリストを取得します。

構文

SHOW TABLES
    [FROM db_name]
    [LIKE 'pattern']

パラメーターの説明

db_name：

Dataphin プロジェクトの名前。指定されたプロジェクトの物理テーブルが表示されます。
開発プロジェクトとデータドメインの場合、明示的に _Dev を追加する必要があります。
db_name を指定しない場合、URL の project_name で指定されたプロジェクトのテーブルがデフォルトで表示されます。

戻り結果

名前	タイプ	コメント
dim_user	LOGICAL TABLE	ユーザーテーブル。
ods_user	PHYSICAL TABLE	ユーザーソーステーブル。
ods_user_logical_view	LOGICAL_VIEW	論理ビュー。
ods_user_physical_view2	PHYSICAL_VIEW	物理ビュー。

2. テーブルのスキーマの取得

この操作では、物理テーブルまたは物理ビューのフィールド詳細を取得します。

構文

{DESCRIBE | DESC} table_name;

説明

物理テーブルと物理ビューのみがサポートされています。

パラメーターの説明

table_name：物理テーブルまたは物理ビューの名前。

戻り結果

名前	タイプ	コメント
ID	BigInt	ユーザー ID。
Name	String	ユーザー名。
DS	String	パーティション時間。

サーバー側の接続制御

最大接続数：デフォルト値は 100 です。
接続タイムアウト：デフォルト値は 288,000 秒 (2 時間) です。サービスがデータベースに接続しても一定期間アイドル状態が続くと、接続は自動的に切断されます。この接続で操作を実行すると、エラーが報告されるか、接続が予期せず閉じられます。これは、接続 URL の Connection_Idle_Timeout パラメーターに対応します。

MaxCompute インスタンスに実行のために送信された Dataphin JDBC ジョブに関する情報

Dataphin JDBC ジョブを MaxCompute インスタンスに実行のために送信すると、システムは Dataphin 関連の情報も送信します。次の表に、その情報を示します。

パラメーター	説明
logical_project	JDBC ジョブが実行される Dataphin プロジェクトの名前。
EXT_JDBC_TASKRUN_ID	JDBC ジョブの ID。
EXT_DPN_TENANT_ID	JDBC ジョブが実行される Dataphin テナントの ID。
EXT_PLATFORM_ID	ジョブを MaxCompute に送信する上位プラットフォームの ID。デフォルト値は Dataphin です。
biz_id	JDBC ジョブを実行する Dataphin メンバーの ID。
odps.idata.userenv	ユーザー環境情報。これには、Java SDK のバージョン、Java のバージョン、IP アドレス、およびデバイスの MAC アドレスが含まれます。例： `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11...,MAC:00----*-25`。

送信された情報を使用して、MaxCompute の請求書を分析し、ジョブで消費された時間を確認できます。詳細については、「MaxCompute プロジェクトの上位 N 個のコストと時間のかかるジョブのアカウントに関する統計を収集する」をご参照ください。