Hubungkan ke Dataphin menggunakan JDBC | Dataphin - Dataphin

Topik ini menjelaskan cara menghubungkan ke Dataphin menggunakan driver Java Database Connectivity (JDBC).

Prasyarat

Dataphin JDBC menggunakan Dataphin OpenAPI untuk menjalankan kueri SQL. Sebelum menggunakan Dataphin JDBC, Anda harus mengaktifkan fitur Dataphin OpenAPI terlebih dahulu.

Ikhtisar fungsi

Dua mode autentikasi: Dataphin JDBC mendukung dua mode autentikasi: mode dasar dan modus proxy. Untuk informasi selengkapnya, lihat Authentication modes.
Konsistensi hasil eksekusi: Menjalankan pernyataan SQL melalui Dataphin JDBC setara dengan menjalankannya di UI Dataphin. Oleh karena itu, hasil eksekusi SQL konsisten dengan hasil yang ditampilkan di UI Dataphin. Konfigurasi di Dataphin—seperti izin, aturan penyamaran data, pengaturan keamanan, dan spesifikasi kode—juga memengaruhi hasil eksekusi melalui Dataphin JDBC.

Batasan

Dataphin tidak mendukung koneksi JDBC jika mesin komputasi adalah Databricks, SelectDB, atau Doris.
Saat Dataphin JDBC menjalankan pernyataan SQL, Dataphin melakukan operasi pra-pemrosesan seperti terjemahan SQL dan penyamaran data. Data hasil juga ditransmisikan dan diteruskan melalui Dataphin. Proses-proses ini menyebabkan degradasi performa sehingga kueri memerlukan waktu lebih lama dibandingkan kueri langsung ke mesin komputasi.
Dataphin JDBC menjalankan pernyataan SQL dengan mengirimkannya ke Dataphin melalui Dataphin OpenAPI. Dataphin kemudian memproses pernyataan tersebut dan meneruskannya ke mesin komputasi yang mendasari untuk dieksekusi. Sebelum menggunakan Dataphin JDBC, Anda harus menilai volume panggilan dan menentukan apakah perlu melakukan penskalaan kluster Dataphin serta mesin komputasi.
Catatan
Jika Anda tidak dapat menilai kapasitas sendiri, ajukan permintaan penilaian kapasitas untuk kluster Dataphin kepada tim Operasi dan Pemeliharaan (O&M) Dataphin. Permintaan ini tidak mencakup penilaian kapasitas untuk mesin komputasi.
Dataphin tidak mendukung pembatasan kecepatan atau kontrol konkurensi. Anda harus menilai dampaknya secara hati-hati.

Versi driver JDBC dan tautan unduhan

Hubungi insinyur O&M Dataphin untuk mendapatkan paket JAR driver.

Parameter koneksi

Catatan

Saat Dataphin JDBC menggunakan ID AccessKey dan Rahasia AccessKey platform (modus proxy), Anda dapat menggunakan sintaks set untuk menentukan 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. Anda harus menghapusnya saat menjalankan perintah.

Parameter	Wajib	Deskripsi	Contoh
host	Ya	Nama domain Dataphin OpenAPI. Anda dapat memperoleh nama domain Dataphin dari OpenAPI Call Address di Personal Center > AccessKey Management. Gambar berikut menunjukkan contohnya.	dataphin-openapi.****.aliyun.com
port	Tidak	Nomor port bergantung pada apakah HTTPS diaktifkan untuk Dataphin OpenAPI. Jika HTTPS diaktifkan, port-nya adalah `443`. Jika HTTPS tidak diaktifkan, port-nya adalah `80`. Nilai default-nya adalah 80.	80
catalog	Ya	Cakupan data yang dapat dikueri secara default. Untuk menggunakan tabel fisik Dataphin, masukkan nama bahasa Inggris proyek Dataphin (project_name). Untuk menggunakan tabel logis Dataphin, masukkan nama bahasa Inggris domain data Dataphin. Nama tersebut harus diawali dengan `LD_`. Untuk menggunakan tabel sumber data yang dikelola oleh Dataphin, masukkan kode sumber data yang dikonfigurasi di Dataphin. Kode tersebut harus diawali dengan `ds_`. Catatan Jika cakupan kueri default adalah domain data, compute_project wajib ditentukan. Jika cakupan kueri default adalah tabel sumber data yang dikelola oleh Dataphin, Anda tidak perlu menentukan compute_project.	Exprojectname
tenant_id	Ya	ID penyewa untuk kueri.	111***111
ssl	Tidak	Menentukan apakah akan menggunakan HTTPS. True: Gunakan nama domain HTTPS. False: Gunakan nama domain HTTP. Ini adalah nilai default.	False
currentschema	Tidak	Skema sumber data. Jika Anda menggunakan tabel fisik atau logis Dataphin dalam catalog, Anda tidak perlu menentukan parameter ini. Jika tipe sumber data yang digunakan dalam catalog tidak mendukung skema, seperti MySQL, Anda tidak perlu menentukan parameter ini. Jika tipe sumber data yang digunakan dalam catalog mendukung skema, seperti Oracle, parameter ini bersifat opsional. Jika Anda menentukan skema, data dalam skema yang ditentukan akan dikueri. Jika Anda tidak menentukan skema, skema default database akan dikueri.	information_schema
compute_project	Tidak	Nama bahasa Inggris proyek. Proyek ini digunakan untuk menjalankan kueri SQL. Proyek dan mesin komputasi yang terhubung dengannya 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 menjalankan pernyataan SQL. Jika cakupan kueri yang ditentukan adalah domain data Dataphin, parameter ini wajib ditentukan. Jika cakupan kueri yang ditentukan adalah sumber data Dataphin, Anda tidak perlu menentukan parameter ini.	Exprojectname
user	Ya	ID AccessKey pengguna atau platform. Dalam modus proxy, gunakan ID AccessKey platform. Hubungi tim O&M Dataphin untuk mendapatkan ID AccessKey platform. Anda dapat memperoleh ID AccessKey pengguna di Personal Center > AccessKey Management.	kIB**********PT0
log_level	Tidak	Tingkat logging. Nilai yang valid: DEBUG INFO WARNING ERROR	DEBUG
password	Ya	Rahasia AccessKey pengguna akses. Hubungi tim O&M Dataphin untuk mendapatkan AccessKey platform. Anda dapat memperoleh ID AccessKey pengguna di Personal Center > AccessKey Management.	Cy**************r2T
delegation_uid	Tidak	Saat Anda menggunakan AccessKey platform, Anda dapat bertindak sebagai proxy untuk pengguna lain guna membuat koneksi dan mengakses Dataphin. Parameter ini menentukan pengguna Dataphin yang akan diproksi. Untuk pengguna Dataphin yang akan diproksi, Anda harus meneruskan ID akun yang sesuai berdasarkan account_type yang dipilih. Setelah Anda menyetel parameter ini, modus proxy akan digunakan untuk autentikasi.	999***999
account_type	Tidak	Saat Anda menggunakan modus proxy untuk autentikasi, Anda harus menentukan tipe akun pengguna yang diproksi. ACCOUNT_NAME: Username di Dataphin. Mode ini direkomendasikan jika username aplikasi sama dengan username Dataphin. USER_ID: ID unik di Dataphin. Mode ini tidak direkomendasikan. SOURCE_USER_ID: ID akun sistem sumber. Ini dapat digunakan ketika Dataphin dikonfigurasi dengan autentikasi single sign-on (SSO), seperti Resource Access Management (RAM), Security Assertion Markup Language (SAML), atau autentikasi OAuth. Ini adalah akun pengguna di penyedia identitas (IDP). Catatan Anda hanya perlu mengonfigurasi parameter ini saat delegation_uid disetel. Jika Anda tidak menentukan parameter ini, tipe default-nya adalah USER_ID. Jika terdapat pengguna duplikat, autentikasi gagal.	USER_ID
connect_timeout	Tidak	Periode timeout maksimum untuk mendapatkan koneksi, dalam detik. Lebih besar dari 0: Periode timeout. Nilai minimum adalah 10 detik. Kurang dari atau sama dengan 0: Tunggu tanpa batas.	10
engine	Tidak	Mesin offline untuk proyek yang ditentukan oleh project_name dalam session atau string koneksi. Jika merupakan sumber komputasi Hadoop, mesin default-nya adalah Hive. Anda dapat menyetel parameter ini ke Impala atau Spark. Untuk menyetel tipe mesin, Anda harus mengonfigurasinya terlebih dahulu di sumber komputasi. Jika mesin yang ditentukan tidak didukung oleh proyek, pengaturan tersebut akan diabaikan, tetapi peringatan akan dilaporkan. Nilai yang valid: MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark Catatan Parameter ini diabaikan saat Anda mengakses sumber data.	MaxCompute
acceleration_source	Tidak	Menentukan sumber akselerasi. Anda dapat memilih kode sumber akselerasi apa pun dalam penyewa tersebut.	starrocks_code
acceleration_resource_group	Tidak	Kelompok sumber daya akselerasi. Anda dapat memilih kelompok sumber daya yang telah dikonfigurasi untuk sumber akselerasi yang dipilih.	starrocks_resource_group

Mode autentikasi

Mode dasar

Anda dapat menyetel username ke ID AccessKey pengguna dan password ke Rahasia AccessKey pengguna. Akses akan diidentifikasi sebagai pengguna tersebut. Untuk informasi selengkapnya tentang cara melihat AccessKey, lihat Dataphin OpenAPI AccessKey management.

Saat mengakses Dataphin melalui driver JDBC, Dataphin mengautentikasi AccessKey dan memberikan otorisasi kepada pemilik AccessKey tersebut untuk mengakses resource atau menjalankan pernyataan SQL. Dataphin kemudian mengidentifikasi pengguna yang menjalankan pernyataan SQL tersebut.

Modus proxy

Penting

Sebelum menggunakan modus proxy, hubungi tim O&M Dataphin untuk mengaktifkan dan mengonfigurasi fitur ini.

Modus proxy biasanya digunakan untuk integrasi antara sistem dan Dataphin. Metode ini menghindari kebutuhan untuk mendistribusikan atau mengonfigurasi AccessKey bagi setiap pengguna. Dengan menentukan pengguna proxy dalam string koneksi JDBC (URL JDBC), operasi akan diotorisasi berdasarkan pengguna yang ditentukan. AccessKey tingkat platform memiliki izin tinggi dan dapat bertindak sebagai proxy untuk semua pengguna. Seperti yang ditunjukkan pada gambar berikut, klien dikonfigurasi dengan AccessKey platform. Saat userA mengakses klien, Anda harus menentukan delegation_uid=userA untuk menunjukkan bahwa akses tersebut merupakan proxy untuk userA. Izin fungsi dan izin data userA kemudian digunakan untuk verifikasi izin.

Detail driver Dataphin

com.aliyun.dataphin.jdbc.DataphinDriver

Antarmuka	Deskripsi fungsi	Definisi antarmuka
connect	Mendapatkan 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

Antarmuka

Deskripsi

Definisi antarmuka

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

Antarmuka	Deskripsi	Definisi antarmuka
executeQuery	Menjalankan pernyataan SQL dan mengembalikan objek ResultSet.	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	Mengambil data hasil secara batch berdasarkan jumlah baris yang ditentukan. Jika parameter ini tidak disetel atau disetel ke 0, nilai default-nya adalah 1.000.	`void setFetchSize(int rows) throws SQLException`
cancel	Membatalkan eksekusi objek Statement.	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

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

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

Antarmuka	Deskripsi	Definisi antarmuka
getColumnCount	Mendapatkan jumlah kolom dalam skema hasil.	`int getColumnCount() throws SQLException;`
getColumnName	Mendapatkan nama kolom dari skema hasil.	`int getColumnCount() throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

Antarmuka	Deskripsi	Definisi antarmuka
next	Mengambil data hasil eksekusi SQL baris demi baris.	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

Antarmuka

Deskripsi

Definisi antarmuka

getTables

Mendapatkan informasi tabel.

Deskripsi parameter:
- catalog: Nilai default-nya adalah default.
- schemaPattern: Nama proyek atau nama domain data.
- tableNamePattern: Nama tabel. Mendukung pencocokan fuzzy. Ekspresi reguler tidak didukung.
- types: Parameter ini tidak didukung.
Hasil pengembalian:
- Objek ResultSet dikembalikan.
- Anda dapat memanggil metode next untuk mengambil data hasil eksekusi SQL baris demi baris. Setiap baris berisi metadata satu tabel. Hanya nama tabel yang dapat diperoleh.
Mendapatkan nama tabel:
- resultSet.getString("table_name")

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

getColumns

Mendapatkan informasi bidang suatu tabel.

Deskripsi parameter:
- catalog: Nama proyek atau nama domain data.
- schemaPattern: Parameter ini tidak didukung.
- tableNamePattern: Nama lengkap tabel. Pencocokan fuzzy dan ekspresi reguler tidak didukung.
- columnNamePattern: Parameter ini tidak didukung.
Hasil pengembalian:
- Objek ResultSet dikembalikan.
- Anda dapat memanggil metode next untuk mengambil data hasil eksekusi SQL baris demi baris. Setiap baris berisi metadata satu bidang dalam tabel. Hanya nama kolom dan tipe data yang dapat diperoleh.
Mendapatkan nama kolom: resultSet.getString("column_name").
Mendapatkan tipe data kolom: resultSet.getString("data_type").

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

Contoh

Anda dapat mengambil informasi catalog menggunakan driver Dataphin JDBC.

1. Mendapatkan daftar tabel

Operasi ini mengambil daftar tabel fisik dan tampilan fisik dalam suatu proyek.

Sintaks

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

Deskripsi parameter

db_name:

Nama proyek Dataphin. Tabel fisik dalam proyek yang ditentukan akan ditampilkan.
Untuk proyek pengembangan dan domain data, Anda harus secara eksplisit menambahkan _Dev.
Jika Anda tidak menentukan db_name, tabel dalam proyek yang ditentukan oleh project_name dalam URL akan ditampilkan secara default.

Hasil pengembalian

Nama	Tipe	Komentar
dim_user	LOGICAL TABLE	Tabel pengguna.
ods_user	PHYSICAL TABLE	Tabel sumber pengguna.
ods_user_logical_view	LOGICAL_VIEW	Tampilan logis.
ods_user_physical_view2	PHYSICAL_VIEW	Tampilan fisik.

2. Mendapatkan skema tabel

Operasi ini mengambil detail bidang tabel fisik atau tampilan fisik.

Sintaks

{DESCRIBE | DESC} table_name;

Catatan

Hanya tabel fisik dan tampilan fisik yang didukung.

Deskripsi parameter

table_name: Nama tabel fisik atau tampilan fisik.

Hasil pengembalian

Nama	Tipe	Komentar
ID	BigInt	ID pengguna.
Name	String	Username.
DS	String	Waktu partisi.

Kontrol koneksi sisi server

Koneksi maksimum: Nilai default-nya adalah 100.
Timeout koneksi: Nilai default-nya adalah 288.000 detik (2 jam). Jika suatu layanan terhubung ke database tetapi tetap idle selama periode tertentu, koneksi akan diputus secara otomatis. Jika Anda melakukan operasi melalui koneksi ini, error akan dilaporkan atau koneksi ditutup secara tak terduga. Hal ini berkaitan dengan parameter Connection_Idle_Timeout dalam URL koneksi.

Informasi tentang pekerjaan Dataphin JDBC yang dikirimkan ke instans MaxCompute untuk eksekusi

Saat Anda mengirimkan pekerjaan Dataphin JDBC ke instans MaxCompute untuk dieksekusi, sistem juga mengirimkan informasi terkait Dataphin. Tabel berikut menjelaskan informasi tersebut.

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

Anda dapat menggunakan informasi yang dikirimkan untuk menganalisis tagihan MaxCompute dan melihat waktu yang dikonsumsi oleh pekerjaan. Untuk informasi selengkapnya, lihat Collect statistics on accounts of top N costs and time-consuming jobs of MaxCompute projects.