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

JDBC ドライバーを使用して Dataphin に接続する方法について説明します。

前提条件

JDBC ドライバーを使用する前に、Dataphin OpenAPI 機能を有効化する必要があります。

概要

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

制限事項

JDBC を使用して、すべてのコンピュートエンジンおよび一部のデータソースから Dataphin に接続できます。サポートされているデータソースには、MySQL、Oracle、MaxCompute、Hive、AnalyticDB for MySQL 3.0、StarRocks、AnalyticDB for PostgreSQL、Doris が含まれます。
Dataphin JDBC ドライバーで SQL ステートメントを実行すると、Dataphin は SQL 変換やデータマスキングなどのタスクのためにステートメントを前処理します。結果データも Dataphin を介して転送されます。これらのプロセスはパフォーマンスオーバーヘッドを引き起こす可能性があり、コンピュートエンジンを直接クエリする場合と比較してクエリ時間が長くなることがあります。
Dataphin JDBC ドライバーは、処理のために OpenAPI を介して 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 のドメイン名。ドメイン名は、[個人センター] の [AccessKey 管理] ページにある [OpenAPI 呼び出しアドレス] セクションから取得できます。次の図をご参照ください。	dataphin-openapi.****.aliyun.com
port	いいえ	ポートは、Dataphin OpenAPI で HTTPS が有効になっているかどうかによって決まります。HTTPS が有効な場合、ポートは `443` です。それ以外の場合、ポートはデフォルトの `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 です。	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	いいえ	プロキシモードでは、このパラメーターは代理実行する Dataphin ユーザーを指定します。代理実行される Dataphin ユーザーについては、選択した account_type に基づいて対応するアカウント ID を提供する必要があります。このパラメーターを設定すると、プロキシモードが有効になります。	999***999
account_type	いいえ	プロキシモードで認証を使用する場合、代理実行されるユーザーのアカウントタイプを指定する必要があります。 ACCOUNT_NAME：Dataphin のユーザー名。アプリケーションのユーザー名が Dataphin のユーザー名と同じ場合に推奨されるモードです。 USER_ID：Dataphin の一意の内部 ID。このモードは通常推奨されません。 SOURCE_USER_ID：ソースシステムのアカウント ID。これは、Dataphin が RAM、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 を認証し、要求されたリソースまたは SQL ステートメントに対してユーザーを承認します。その後、Dataphin はそのユーザーとして SQL ステートメントを実行します。

プロキシモード

重要

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

プロキシモードは通常、Dataphin とのシステムレベルの統合に使用されます。この方法では、個人ユーザーの AccessKey を配布または設定する必要がありません。接続文字列 (JDBC URL) で代理実行されるユーザーを指定して、そのユーザーの権限に基づいて操作が承認されるようにすることができます。プラットフォームレベルの AccessKey は高い権限を持ち、任意のユーザーを代理実行できます。たとえば、クライアントがプラットフォームの AccessKey を使用する場合、userA が接続するときに delegation_uid=userA を設定します。Dataphin は、その接続に対して userA を代理実行し、そのユーザーのプロファイルに基づいて権限チェックを実行します。

Dataphin ドライバー

com.aliyun.dataphin.jdbc.DataphinDriver

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

com.aliyun.dataphin.jdbc.DataphinConnection

API

説明

定義

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

API	説明	定義
executeQuery	SQL ステートメントを実行し、ResultSet オブジェクトを返します。	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	1 回のバッチでデータベースからフェッチする行数を指定します。このパラメーターが設定されていないか、0 に設定されている場合、デフォルト値の 1000 が使用されます。	`void setFetchSize(int rows) throws SQLException`
cancel	`Statement` オブジェクトの実行をキャンセルしようとします。	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

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

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

API	説明	定義
getColumnCount	結果セットの列数を取得します。	`int getColumnCount() throws SQLException;`
getColumnName	結果セットの列名を取得します。	`String getColumnName(int column) throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

API	説明	定義
next	カーソルを `ResultSet` オブジェクトの次の行に移動します。	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

API

説明

定義

getTables

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

パラメーター：
- catalog：デフォルト値は default です。
- schemaPattern：プロジェクト名またはデータブロック名。
- tableNamePattern：テーブル名。あいまい一致がサポートされています。正規表現はサポートされていません。
- types：このパラメーターはサポートされていません。
結果：
- 結果は ResultSet オブジェクトです。
- ResultSet の各行はテーブルを記述します。ResultSet は next() を使用して反復処理できます。各行から取得できるのはテーブル名のみです。
テーブル名の取得：
- resultSet.getString("table_name")

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

getColumns

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

パラメーター：
- catalog：プロジェクト名またはデータブロック名。
- schemaPattern：このパラメーターはサポートされていません。
- tableNamePattern：テーブルの完全名。あいまい一致および正規表現はサポートされていません。
- columnNamePattern：このパラメーターはサポートされていません。
結果：
- 結果は ResultSet オブジェクトです。
- ResultSet の各行はテーブルの列を記述します。ResultSet は next() を使用して反復処理できます。各行から取得できるのは、列名とデータ型のみです。
列名の取得： 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 が指定されていない場合、デフォルトで接続文字列で指定された project_name になります。

結果

名前	タイプ	説明
dim_user	論理テーブル	ユーザーテーブル。
ods_user	物理テーブル	ユーザーソーステーブル。
ods_user_logical_view	論理ビュー	論理ビュー。
ods_user_physical_view2	物理ビュー	物理ビュー。

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

物理テーブルまたは物理ビューのスキーマを表示します。

構文

{DESCRIBE | DESC} table_name;

説明

このコマンドは、物理テーブルと物理ビューのみをサポートします。

パラメーター

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

結果

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

サーバーサイドの接続制御

最大接続数：デフォルト値は 100 です。
接続タイムアウト：デフォルト値は 288000 秒 (2 時間) です。確立された接続がアイドル状態のままである場合、この期間が経過すると自動的に切断されます。切断された接続で操作を実行しようとすると、エラーまたはクローズ例外が返されます。これは、JDBC URL の Connection_Idle_Timeout に対応します。

MaxCompute における JDBC タスクのメタデータ

JDBC タスクが Dataphin から MaxCompute 実行インスタンスに送信されると、次のメタデータが送信に含まれます。

パラメーター	説明
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 個のコストと時間のかかるジョブのアカウントに関する統計を収集する」をご参照ください。