通過JDBC串連Dataphin - Dataphin

本文為您介紹如何使用JDBC Driver串連Dataphin。

前提條件

Dataphin JDBC使用Dataphin的OpenAPI實現SQL查詢能力，在使用Dataphin JDBC前需要開通Dataphin OpenAPI功能。

功能概述

兩種認證模式：Dataphin JDBC支援兩種認證模式：簡單模式和代理模式。更多資訊，請參見認證模式。
執行結果統一：因使用Dataphin JDBC執行SQL等同於在Dataphin中執行SQL，所以其SQL執行結果與在Dataphin中的介面執行結果一致。同時Dataphin中相關的功能配置，同樣也會影響到Dataphin JDBC的執行結果。例如，許可權、脫敏規則、安全設定、代碼規範等。

使用限制

當計算引擎使用Databricks、SelectDB、Doris時，不支援通過JDBC串連Dataphin。
Dataphin JDBC的SQL執行會通過Dataphin進行SQL翻譯、脫敏等預先處理，且結果資料通過Dataphin進行傳輸和轉寄，都會造成效能的損耗，因此相對於直接對計算引擎進行查詢的耗時更長。
Dataphin JDBC執行SQL會通過Dataphin OpenAPI提交到Dataphin進行處理，並最終提交到底層計算引擎去執行。因此在使用Dataphin JDBC前請合理評估調用量，並及時評估是否需要對Dataphin叢集和計算引擎進行擴容。
說明
若無法合理評估確認，您可以向Dataphin營運團隊提交Dataphin叢集的容量評估申請（不包含計算引擎的容量評估）。
Dataphin暫不支援流量控制、並發控制，請謹慎評估影響。

JDBC驅動版本及下載連結

驅動的JAR包您可以聯絡Dataphin營運人員擷取。

串連參數

說明

當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的網域名稱。如下圖所示：	dataphin-openapi.****.aliyun.com
port	否	連接埠根據Dataphin OpenAPI是否開啟HTTPS決定，如果開啟HTTPS連接埠為`443`，未開啟為`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。	False
currentschema	否	資料來源的schema。若catalog中使用的是Dataphin物理表/邏輯表，則無需填寫此參數。若catalog中使用的資料來源為不支援Schema的資料來源類型（例如MySQL），則無需填寫此參數。若catalog中使用的資料來源為支援Schema的資料來源類型（例如Oracle），則此參數為非必填。若輸入指定的Schema，則查詢指定Schema下的資料。若未輸入Schema，則查詢資料庫的預設Schema。	information_schema
compute_project	否	輸入專案的英文名，此專案作為查詢SQL的執行專案，需要該專案及綁定的計算源有查詢表的讀許可權。若指定的查詢範圍是Dataphin專案，則此參數為非必填，若未填寫則使用預設查詢範圍指定的專案作為SQL執行專案。若指定的查詢範圍是Dataphin板塊，則此參數為必填。若指定的查詢範圍是Dataphin資料來源，則無需填寫此參數。	Exprojectname
user	是	使用者的AccessKey ID或者平台的AccessKey ID。使用代理模式時，請使用平台的AccessKey ID。平台AccessKey ID可聯絡Dataphin營運團隊擷取。使用者的AccessKey ID可在個人中心 > AccessKey管理中擷取。	kIB**********PT0
log_level	否	日誌記錄層級。取值為： DEBUG INFO WARNING ERROR	DEBUG
password	是	訪問使用者的AccessKey Secret。平台AccessKey可聯絡Dataphin營運團隊擷取使用者的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配置了SSO認證（如RAM、SAML、oAuth認證等）時可用，該帳號使用者在IDP的帳號。說明僅當設定了delegation_uid時，需要配置此參數。若未填寫此參數，則預設類型為USER_ID。若存在相同的使用者，則認證不通過。	USER_ID
connect_timeout	否	擷取串連時最長的逾時時間，單位為秒。大於0：逾時時間，最小值為10s。小於等於0：一直等待。	10
engine	否	session中或串連串中指定專案的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 Driver訪問Dataphin，Dataphin對AccessKey進行認證和對該AccessKey的使用者進行訪問資源或SQL的鑒權後，Dataphin即識別該使用者進行SQL的執行。

代理模式

重要

在使用代理模式前，需要提前聯絡Dataphin營運團隊開通和配置該功能。

代理模式通常用於系統與Dataphin之間的整合。這種方式避免了需要對不同的使用者分發或配置AccessKey，在JDBC串連串（JDBC URL）中指定代理的使用者即可保證對操作按照指定的使用者進行鑒權。平台層級的AccessKey具有很高的許可權，可代理所有的使用者。如下圖所示，用戶端配置了平台AccessKey，使用者userA通過用戶端訪問時，需要指定delegation_uid=userA指定此次訪問為代理userA的訪問，需要用userA的功能許可權及資料許可權進行許可權校正。

Dataphin Driver詳細說明

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

建立PrepareStatement對象。

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，則預設為1000。	`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	擷取結果Schema的列數目。	`int getColumnCount() throws SQLException;`
getColumnName	擷取結果Schema的列名稱。	`int getColumnCount() throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

介面	說明	介面定義
next	逐條擷取SQL執行結果資料。	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

介面

說明

介面定義

getTables

擷取表資訊。

參數說明：
- catalog：預設為default。
- schemaPattern：專案名稱或者板塊名稱。
- tableNamePattern：表名稱，支援模糊比對，不支援Regex。
- types：暫不支援此參數。
返回結果：
- 返回結果為ResultSet。
- 可以通過next逐條擷取SQL執行結果資料，每條資料為單個表的中繼資料（僅支援擷取表名）。
擷取表名：
- resultSet.getString("table_name")

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

getColumns

擷取表的欄位資訊。

參數說明：
- catalog：專案名稱或者板塊名稱。
- schemaPattern：暫不支援此參數。
- tableNamePattern：表名稱，表的全名，不支援模糊比對，不支援Regex。
- columnNamePattern：暫不支援此參數。
返回結果：
- 返回結果為ResultSet。
- 可以通過next逐條擷取SQL執行結果資料，每條資料為表的一個欄位的中繼資料（僅支援列名、資料類型）。
擷取列名：resultSet.getString("column_name")。
擷取列的資料類型：resultSet.getString("data_type")。

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

樣本

可通過Dataphin JDBC Driver擷取Catalog資訊。

1. 擷取表列表

擷取專案下的物理表及物理視圖列表。

文法

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

參數說明

db_name：

Dataphin專案名：展示該專案下的物理表。
開發專案及資料板塊需要顯式地增加_Dev。
db_name不傳入時，預設展示URL中設定的project_name下的表。

返回結果

表名稱（Name）	表類型（Type）	說明（Comment）
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：物理表及物理視圖的名稱。

返回結果

參數名稱（Name）	參數類型（Type）	說明（Comment）
ID	BigInt	使用者ID。
Name	String	使用者名稱稱。
DS	String	分區時間。

伺服器端串連控制

最大串連數：預設為100。
連線逾時：預設為288000s（2小時）。服務串連到資料庫但對其不做任何操作時，等待一定時間之後，串連自動斷開。通過該串連進行操作時，服務會報錯或者關閉異常，對應的是Connection URL的Connection_Idle_Timeout。

Dataphin JDBC任務提交到MaxCompute執行執行個體的資訊

提交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	使用者環境資訊。包括JavaSDK版本、Java版本、IP以及裝置MAC資訊。例如： `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11...,MAC:00----*-25`。

對於提交的資訊，您可以用於分析在MaxCompute的賬單及查看作業的耗時情況等情境。具體操作，請參見統計MaxCompute TOPN費用帳號及耗時作業。