Jalankan SQL di Dataphin melalui JDBC Driver dan OpenAPI - Dataphin - Alibaba Cloud - Dataphin

Pelajari cara menghubungkan ke Dataphin menggunakan driver JDBC.

Prasyarat

Sebelum menggunakan driver JDBC, Anda harus mengaktifkan fitur Dataphin OpenAPI.

Ikhtisar

Dua mode autentikasi: Driver JDBC Dataphin mendukung dua mode autentikasi: simple mode dan proxy mode. Untuk informasi lebih lanjut, lihat Authentication modes.
Hasil eksekusi konsisten: Menjalankan pernyataan SQL dengan driver JDBC Dataphin setara dengan menjalankannya di Konsol Dataphin. Oleh karena itu, hasil eksekusinya konsisten. Fitur-fitur yang dikonfigurasi di Dataphin, seperti izin, aturan desensitisasi, pengaturan keamanan, dan spesifikasi kode, juga memengaruhi hasil eksekusi driver JDBC Dataphin.

Batasan

Anda dapat menggunakan JDBC untuk terhubung ke Dataphin dari semua compute engine dan beberapa data source. Data source yang didukung meliputi MySQL, Oracle, MaxCompute, Hive, AnalyticDB for MySQL 3.0, StarRocks, AnalyticDB for PostgreSQL, dan Doris.
Saat Anda mengeksekusi pernyataan SQL dengan driver JDBC Dataphin, Dataphin melakukan pra-pemrosesan terhadap pernyataan tersebut untuk tugas-tugas seperti translation SQL dan desensitisasi data. Data hasil juga ditransmisikan dan diteruskan melalui Dataphin. Proses-proses ini dapat menimbulkan overhead performa, sehingga waktu kueri menjadi lebih lama dibandingkan dengan mengakses compute engine secara langsung.
Driver JDBC Dataphin mengirimkan pernyataan SQL ke Dataphin melalui OpenAPI untuk diproses, lalu diteruskan ke compute engine yang mendasarinya. Sebelum menggunakan driver JDBC Dataphin, Anda harus mengevaluasi volume panggilan yang diharapkan dan menentukan apakah perlu melakukan scale out kluster Dataphin dan compute engine Anda.
Catatan
Jika Anda tidak dapat melakukan evaluasi ini, Anda dapat mengajukan permintaan evaluasi kapasitas untuk kluster Dataphin Anda kepada tim O&M Dataphin. Ini tidak mencakup evaluasi kapasitas untuk compute engine.
Dataphin saat ini tidak mendukung traffic control atau concurrency control. Evaluasi dampak potensialnya secara cermat.

Versi driver JDBC dan tautan unduhan

Untuk mendapatkan paket JAR driver, hubungi tim O&M Dataphin.

Parameter koneksi

Catatan

Saat JDBC Dataphin menggunakan ID AccessKey dan AccessKey Secret platform (dalam proxy mode), Anda dapat menggunakan sintaksis set untuk mengatur pengguna akses.

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

Format URL JDBC: 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]

Penting

Nama parameter bersifat case-sensitive.
Tanda kurung siku ([]) hanya untuk ilustrasi dan harus dihilangkan dari string koneksi aktual.

Parameter	Wajib	Deskripsi	Contoh
host	Ya	Nama domain Dataphin OpenAPI. Anda dapat memperoleh nama domain dari bagian OpenAPI invocation address pada halaman AccessKey Management di Personal Center, seperti yang ditunjukkan pada gambar berikut:	dataphin-openapi.****.aliyun.com
port	Tidak	Port ditentukan berdasarkan apakah HTTPS diaktifkan untuk Dataphin OpenAPI. Jika HTTPS diaktifkan, port-nya adalah `443`. Jika tidak, port-nya adalah `80`, yang merupakan nilai default.	80
catalog	Ya	Cakupan kueri default. Untuk menggunakan tabel fisik Dataphin, tentukan nama bahasa Inggris proyek Dataphin (project_name). Jika Anda menggunakan tabel logis Dataphin, masukkan nama bahasa Inggris papan data Dataphin (dimulai dengan `LD_`). Untuk menggunakan tabel data source yang dikelola oleh Dataphin, masukkan kode data source yang dikonfigurasi di Dataphin (dimulai dengan `ds_`). Catatan Jika cakupan kueri default adalah data block, parameter compute_project wajib diisi. Jika cakupan kueri default adalah tabel dari data source yang dikelola oleh Dataphin, Anda tidak perlu menentukan compute_project.	Exprojectname
tenant_id	Ya	ID tenant yang akan dikueri.	111***111
ssl	Tidak	Menentukan apakah akan menggunakan HTTPS. True: Gunakan nama domain HTTPS. False: Gunakan nama domain HTTP. Nilai default-nya adalah False.	False
currentschema	Tidak	Skema dari data source. Jika catalog menggunakan tabel fisik atau tabel logis Dataphin, Anda tidak perlu menentukan parameter ini. Jika data source yang digunakan dalam catalog tidak mendukung skema, seperti MySQL, Anda tidak perlu menentukan parameter ini. Jika data source yang digunakan dalam catalog mendukung skema, seperti Oracle, parameter ini bersifat opsional. Jika Anda menentukan skema, data dari skema tersebut yang akan dikueri. Jika Anda tidak menentukan skema, skema default database yang akan dikueri.	information_schema
compute_project	Tidak	Tentukan nama bahasa Inggris proyek. Proyek ini yang akan mengeksekusi kueri SQL. Proyek dan compute engine-nya yang terikat harus memiliki izin baca pada tabel yang dikueri. Jika cakupan kueri yang ditentukan adalah proyek Dataphin, parameter ini bersifat opsional. Jika Anda tidak menentukan parameter ini, proyek yang ditentukan dalam cakupan kueri default akan digunakan untuk mengeksekusi pernyataan SQL. Jika cakupan kueri yang ditentukan adalah data block Dataphin, parameter ini wajib diisi. Jika cakupan kueri yang ditentukan adalah data source Dataphin, Anda tidak perlu menentukan parameter ini.	Exprojectname
user	Ya	ID AccessKey pengguna atau platform. Saat menggunakan proxy mode, tentukan ID AccessKey platform. Untuk memperoleh ID AccessKey platform, hubungi tim O&M Dataphin. Anda dapat memperoleh ID AccessKey pengguna dari halaman AccessKey Management di Personal Center.	kIB**********PT0
log_level	Tidak	Tingkat logging. Nilai yang valid: DEBUG INFO WARNING ERROR	DEBUG
password	Ya	AccessKey Secret untuk pengguna yang ditentukan. Untuk memperoleh AccessKey platform, hubungi tim O&M Dataphin. Anda dapat memperoleh ID AccessKey pengguna dari halaman AccessKey Management di Personal Center.	Cy**************r2T
delegation_uid	Tidak	Dalam proxy mode, parameter ini menentukan pengguna Dataphin yang akan di-impersonate. Untuk pengguna Dataphin yang diproksi, Anda harus memberikan ID akun yang sesuai berdasarkan account_type yang dipilih. Menyetel parameter ini mengaktifkan proxy mode.	999***999
account_type	Tidak	Saat menggunakan proxy mode untuk autentikasi, Anda harus menentukan jenis akun pengguna yang diproksi. ACCOUNT_NAME: Username di Dataphin. Mode ini direkomendasikan ketika username aplikasi sama dengan username Dataphin. USER_ID: ID internal unik di Dataphin. Mode ini umumnya tidak direkomendasikan. SOURCE_USER_ID: ID akun di sistem sumber. Tersedia ketika Dataphin dikonfigurasi untuk autentikasi Single Sign-On (SSO), seperti RAM, SAML, atau OAuth. Ini adalah akun pengguna di Identity Provider (IdP). Catatan Parameter ini wajib hanya jika delegation_uid disetel. Jika parameter ini tidak ditentukan, jenis default-nya adalah USER_ID. Jika terdapat pengguna duplikat, autentikasi gagal.	USER_ID
connect_timeout	Tidak	Timeout akuisisi koneksi, dalam detik. Lebih besar dari 0: Timeout dalam detik. Nilai minimum adalah 10. Kurang dari atau sama dengan 0: Tunggu tanpa batas.	10
engine	Tidak	Compute engine untuk proyek yang ditentukan oleh project_name dalam session atau string koneksi. Untuk compute engine Hadoop, engine default-nya adalah Hive, tetapi Anda dapat menggunakan parameter ini untuk mengaturnya ke Impala atau Spark. Jenis engine harus telah dikonfigurasi sebelumnya di compute engine. Jika engine yang ditentukan tidak didukung oleh proyek, pengaturan ini akan diabaikan dan peringatan akan dikembalikan. Nilai yang valid: MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark Catatan Parameter ini diabaikan saat Anda mengakses data source.	MaxCompute
acceleration_source	Tidak	Tentukan sumber akselerasi. Anda dapat memilih kode sumber akselerasi apa pun dalam penyewa.	starrocks_code
acceleration_resource_group	Tidak	Acceleration resource group. Anda dapat memilih resource group yang telah dikonfigurasi untuk acceleration source yang dipilih.	starrocks_resource_group

Mode autentikasi

Simple mode

Atur username ke ID AccessKey pengguna dan password ke AccessKey Secret pengguna. Hal ini mengotentikasi koneksi sebagai pengguna tersebut. Untuk melihat AccessKey Anda, lihat Dataphin OpenAPI AccessKey Management.

Saat Anda mengakses Dataphin melalui driver JDBC, Dataphin mengotentikasi AccessKey dan memberikan otorisasi kepada pengguna untuk resource atau pernyataan SQL yang diminta. Dataphin kemudian mengeksekusi pernyataan SQL sebagai pengguna tersebut.

Proxy mode

Penting

Sebelum menggunakan proxy mode, Anda harus menghubungi tim O&M Dataphin untuk mengaktifkan dan mengonfigurasi fitur ini.

Proxy mode biasanya digunakan untuk integrasi tingkat sistem dengan Dataphin. Metode ini menghindari distribusi atau konfigurasi AccessKey untuk pengguna individu. Anda dapat menentukan pengguna yang diproksi dalam string koneksi (URL JDBC) untuk memastikan operasi diotorisasi berdasarkan izin pengguna tersebut. AccessKey tingkat platform memiliki hak istimewa tinggi dan dapat memproksi pengguna mana pun. Misalnya, jika client menggunakan AccessKey platform, atur delegation_uid=userA saat userA terhubung. Dataphin kemudian akan meng-impersonate userA untuk koneksi tersebut dan melakukan pemeriksaan izin berdasarkan profil pengguna tersebut.

Driver Dataphin

com.aliyun.dataphin.jdbc.DataphinDriver

API	Deskripsi	Definisi
connect	Membuat koneksi database.	`Connection connect (String url, Properties info) throws SQLException;`
acceptsURL	Memeriksa apakah URL didukung.	`boolean acceptsURL(String url) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinConnection

API

Deskripsi

Definisi

createStatement

Membuat objek Statement.

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

prepareStatement

Membuat objek 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	Deskripsi	Definisi
executeQuery	Menjalankan pernyataan SQL dan mengembalikan objek ResultSet.	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	Menentukan jumlah baris yang diambil dari database dalam satu batch. Jika parameter ini tidak disetel atau disetel ke 0, nilai default 1000 yang digunakan.	`void setFetchSize(int rows) throws SQLException`
cancel	Mencoba membatalkan eksekusi objek `Statement`.	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

API	Deskripsi	Definisi
executeQuery	Menjalankan pernyataan SQL dan mengembalikan objek ResultSet.	`ResultSet executeQuery (String sql) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

API	Deskripsi	Definisi
getColumnCount	Mendapatkan jumlah kolom dalam result set.	`int getColumnCount() throws SQLException;`
getColumnName	Mendapatkan nama kolom dalam result set.	`String getColumnName(int column) throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

API	Deskripsi	Definisi
next	Memindahkan kursor ke baris berikutnya dalam objek `ResultSet`.	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

API

Deskripsi

Definisi

getTables

Mendapatkan informasi tabel.

Parameter:
- catalog: Nilai default-nya adalah default.
- schemaPattern: Nama proyek atau nama data block.
- tableNamePattern: Nama tabel. Mendukung pencocokan fuzzy. Ekspresi reguler tidak didukung.
- types: Parameter ini tidak didukung.
Hasil:
- Hasilnya adalah objek ResultSet.
- Setiap baris dalam ResultSet menggambarkan sebuah tabel. Anda dapat mengiterasi ResultSet menggunakan next(). Hanya nama tabel yang dapat diambil dari setiap baris.
Ambil nama tabel:
- resultSet.getString("table_name")

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

getColumns

Mendapatkan informasi kolom untuk sebuah tabel.

Parameter:
- catalog: Nama proyek atau nama data block.
- schemaPattern: Parameter ini tidak didukung.
- tableNamePattern: Nama lengkap tabel. Pencocokan fuzzy dan ekspresi reguler tidak didukung.
- columnNamePattern: Parameter ini tidak didukung.
Hasil:
- Hasilnya adalah objek ResultSet.
- Setiap baris dalam ResultSet menggambarkan kolom tabel. Anda dapat mengiterasi ResultSet menggunakan next(). Hanya nama kolom dan tipe data yang dapat diambil dari setiap baris.
Ambil nama kolom: resultSet.getString("column_name").
Ambil tipe data kolom: resultSet.getString("data_type").

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

Contoh

Anda dapat memperoleh informasi catalog dengan menggunakan driver JDBC Dataphin.

1. Daftar tabel

Menampilkan daftar tabel fisik dan tampilan fisik dalam sebuah proyek.

Sintaksis

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

Parameter

db_name:

Nama proyek Dataphin: Menampilkan tabel fisik dalam proyek tersebut.
Untuk proyek pengembangan dan data block, Anda harus secara eksplisit menambahkan akhiran _Dev.
Jika db_name tidak ditentukan, nilai default-nya adalah project_name yang ditentukan dalam string koneksi.

Hasil

Nama	Tipe	Deskripsi
dim_user	Tabel logis	Tabel pengguna.
ods_user	Tabel fisik	Tabel sumber pengguna.
ods_user_logical_view	Tampilan logis	Tampilan logis.
ods_user_physical_view2	Tampilan fisik	Tampilan fisik.

2. Dapatkan skema tabel

Menampilkan skema tabel fisik atau tampilan fisik.

Sintaksis

{DESCRIBE | DESC} table_name;

Catatan

Perintah ini hanya mendukung tabel fisik dan tampilan fisik.

Parameter

table_name: Nama tabel fisik atau tampilan fisik.

Hasil

Nama	Tipe	Deskripsi
ID	BigInt	ID pengguna.
Name	String	Nama pengguna.
DS	String	Waktu partisi.

Kontrol koneksi sisi server

Jumlah maksimum koneksi: Nilai default-nya adalah 100.
Timeout koneksi: Nilai default-nya adalah 288.000 detik (2 jam). Jika koneksi yang telah terbentuk tetap idle, koneksi tersebut akan terputus secara otomatis setelah periode ini. Jika Anda mencoba melakukan operasi pada koneksi yang terputus, error atau close exception akan dikembalikan. Ini sesuai dengan Connection_Idle_Timeout dalam URL JDBC.

Metadata untuk tugas JDBC di MaxCompute

Saat tugas JDBC dikirimkan dari Dataphin ke instans eksekusi MaxCompute, metadata berikut disertakan dalam pengiriman:

Parameter	Deskripsi
logical_project	Nama proyek Dataphin tempat tugas JDBC dieksekusi.
EXT_JDBC_TASKRUN_ID	ID tugas JDBC.
EXT_DPN_TENANT_ID	ID tenant Dataphin tempat tugas JDBC dieksekusi.
EXT_PLATFORM_ID	ID platform lapisan atas yang mengirimkan tugas ke MaxCompute. Nilai default-nya adalah Dataphin.
biz_id	ID pengguna Dataphin yang mengeksekusi tugas JDBC.
odps.idata.userenv	Informasi lingkungan pengguna. Ini mencakup versi Java SDK, versi Java, alamat IP, dan informasi MAC perangkat. Contoh: `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11...,MAC:00----*-25`.

Anda dapat menggunakan informasi ini untuk kasus penggunaan seperti menganalisis tagihan MaxCompute dan melihat durasi pekerjaan. Untuk informasi lebih lanjut, lihat Collect statistics on accounts of top N costs and time-consuming jobs of MaxCompute projects.