Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Penting
Fitur ini sedang dalam tahap pratinjau.
JDBC (Java Database Connectivity) adalah standar yang diadopsi secara luas yang memungkinkan aplikasi klien untuk terhubung dan bekerja dengan data dari database dan platform big data.
Microsoft JDBC Driver for Fabric Data Engineering memungkinkan Anda menyambungkan, mengkueri, dan mengelola beban kerja Spark di Microsoft Fabric dengan keandalan dan kesederhanaan standar JDBC. Dibangun di api Livy Microsoft Fabric, driver menyediakan konektivitas Spark SQL yang aman dan fleksibel ke aplikasi Java dan alat BI Anda. Integrasi ini memungkinkan Anda untuk mengirimkan dan menjalankan kode Spark secara langsung tanpa perlu membuat artefak Notebook atau Definisi Pekerjaan Spark terpisah.
Fitur Utama
- Sesuai JDBC 4.2: Implementasi penuh spesifikasi JDBC 4.2
- Autentikasi ID Microsoft Entra: Beberapa alur autentikasi termasuk interaktif, kredensial klien, dan autentikasi berbasis sertifikat
- Pengumpulan Koneksi Perusahaan: Pengumpulan koneksi bawaan dengan pemantauan kesehatan dan pemulihan otomatis
- Dukungan Kueri Asli Spark SQL: Eksekusi langsung pernyataan Spark SQL tanpa terjemahan
- Dukungan Jenis Data Komprehensif: Dukungan untuk semua jenis data Spark SQL termasuk jenis kompleks (ARRAY, MAP, STRUCT)
- Pengambilan Awal Kumpulan Hasil Asinkron: Pemuatan data latar belakang untuk meningkatkan performa
- Pola Pemutus Sirkuit: Perlindungan terhadap kegagalan berantai dengan pengulangan otomatis
- Koneksi Ulang Otomatis: Pemulihan sesi transparan pada kegagalan koneksi
- Dukungan Proksi: Konfigurasi proksi HTTP dan SOCKS untuk lingkungan perusahaan
Prasyarat
Sebelum menggunakan Microsoft JDBC Driver untuk Microsoft Fabric Data Engineering, pastikan Anda memiliki:
- Java Development Kit (JDK): Versi 11 atau lebih tinggi (direkomendasikan Java 21)
- Microsoft Fabric Access: Akses ke ruang kerja Microsoft Fabric
- Kredensial ID Azure Entra: Kredensial yang sesuai untuk autentikasi
- ID Ruang Kerja dan Lakehouse: Pengidentifikasi GUID untuk ruang kerja Fabric dan lakehouse Anda
Unduhan dan Penginstalan
Microsoft JDBC Driver untuk Microsoft Fabric Data Engineering versi 1.0.0 adalah versi pratinjau publik dan mendukung Java 11, 17 dan 21. Kami terus meningkatkan dukungan konektivitas Java dan menyarankan Agar Anda bekerja dengan versi terbaru driver Microsoft JDBC.
- Unduh Driver Microsoft JDBC untuk Microsoft Fabric Data Engineering (zip)
- Unduh Driver Microsoft JDBC untuk Microsoft Fabric Data Engineering (tar)
- Unduh file zip atau tar dari tautan di atas.
- Ekstrak file yang diunduh untuk mengakses file JAR driver.
- Pilih file JAR yang cocok dengan versi JRE Anda:
- Untuk Java 11:
ms-sparksql-jdbc-1.0.0.jre11.jar - Untuk Java 17:
ms-sparksql-jdbc-1.0.0.jre17.jar - Untuk Java 21:
ms-sparksql-jdbc-1.0.0.jre21.jar
- Untuk Java 11:
- Tambahkan file JAR yang dipilih ke classpath aplikasi Anda.
- Untuk klien JDBC, konfigurasikan kelas driver JDBC:
com.microsoft.spark.livy.jdbc.LivyDriver
Contoh Mulai Cepat
Contoh ini menunjukkan cara menyambungkan ke Microsoft Fabric dan menjalankan kueri menggunakan Microsoft JDBC Driver untuk Microsoft Fabric Data Engineering. Sebelum menjalankan kode ini, pastikan Anda telah menyelesaikan prasyarat dan menginstal driver.
import java.sql.*;
public class QuickStartExample {
public static void main(String[] args) {
// Connection string with required parameters
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=2;" + // Azure CLI based authentication
"LogLevel=INFO";
try (Connection conn = DriverManager.getConnection(url)) {
// Execute a simple query
try (Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT 'Hello from Fabric!' as message")) {
if (rs.next()) {
System.out.println(rs.getString("message"));
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}
Format String Koneksi
String Koneksi Dasar
Microsoft JDBC Driver untuk Microsoft Fabric Data Engineering menggunakan format string koneksi berikut:
jdbc:fabricspark://<hostname>[:<port>][;<parameter1>=<value1>;<parameter2>=<value2>;...]
Komponen String Koneksi
| Komponen | Description | Example |
|---|---|---|
| Protocol | Pengidentifikasi protokol URL JDBC | jdbc:fabricspark:// |
| Host Name | Nama host titik akhir Microsoft Fabric | api.fabric.microsoft.com |
| Port | Nomor port opsional (default: 443) | :443 |
| Parameters | Pasangan kunci=nilai yang dipisahkan titik koma | FabricWorkspaceID=<guid> |
Contoh String Koneksi
Koneksi Dasar (Autentikasi Berbasis Browser Interaktif)
jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=1
Dengan Konfigurasi Sumber Daya Spark
jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2;AuthFlow=2
Dengan Properti Sesi Spark
jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;spark.sql.adaptive.enabled=true;spark.sql.shuffle.partitions=200;AuthFlow=2
Authentication
Microsoft JDBC Driver for Microsoft Fabric Data Engineering mendukung beberapa metode autentikasi melalui ID Microsoft Entra (sebelumnya Azure Active Directory). Autentikasi dikonfigurasi menggunakan AuthFlow parameter dalam string koneksi.
Alur Autentikasi
| AuthFlow | Metode Autentikasi | Kasus Penggunaan |
|---|---|---|
| 1 | Browser Interaktif | Autentikasi pengguna interaktif menggunakan OAuth 2.0 |
| 2 | Azure CLI (antarmuka baris perintah Azure) | Pengembangan menggunakan Azure CLI |
| 3 | Kredensial Rahasia Klien (Perwakilan Layanan) | Autentikasi otomatis/layanan-ke-layanan |
| 4 | Kredensial Sertifikat Klien | Autentikasi prinsipal layanan berbasis sertifikat |
| 5 | access_token | Token akses pembawa yang telah diperoleh sebelumnya |
Autentikasi Browser Interaktif
Terbaik untuk: Pengembangan dan aplikasi interaktif
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=1;" +
"AuthTenantID=<tenant-id>;" + // Optional
"LogLevel=INFO";
Connection conn = DriverManager.getConnection(url);
Parameter:
-
AuthFlow=1: Mengspesifikasi autentikasi peramban interaktif -
AuthTenantID(opsional): ID penyewa Azure -
AuthClientID(opsional): ID Aplikasi (klien)
Perilaku:
- Membuka jendela browser untuk autentikasi pengguna
- Kredensial disimpan dalam cache untuk koneksi berikutnya hingga kedaluwarsa
- Cocok untuk aplikasi pengguna tunggal
Kredensial Klien atau Autentikasi Perwakilan Layanan
Terbaik untuk: Layanan otomatis dan pekerjaan latar belakang
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=3;" +
"AuthClientID=<client-id>;" +
"AuthClientSecret=<client-secret>;" +
"AuthTenantID=<tenant-id>;" +
"LogLevel=INFO";
Connection conn = DriverManager.getConnection(url);
Parameter yang Diperlukan:
-
AuthFlow=3: Menentukan autentikasi kredensial klien -
AuthClientID: ID Aplikasi (klien) dari ID Microsoft Entra -
AuthClientSecret: Rahasia klien dari Microsoft Entra ID -
AuthTenantID: ID penyewa Azure
Praktik Terbaik:
- Menyimpan rahasia dengan aman (Azure Key Vault, variabel lingkungan)
- Gunakan identitas terkelola jika memungkinkan
- Memutar rahasia secara teratur
Autentikasi Berbasis Sertifikat
Terbaik untuk: Aplikasi perusahaan yang memerlukan autentikasi berbasis sertifikat
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=4;" +
"AuthClientID=<client-id>;" +
"AuthCertificatePath=/path/to/certificate.pfx;" +
"AuthCertificatePassword=<certificate-password>;" +
"AuthTenantID=<tenant-id>;" +
"LogLevel=INFO";
Connection conn = DriverManager.getConnection(url);
Parameter yang Diperlukan:
-
AuthFlow=4: Menentukan autentikasi berbasis sertifikat -
AuthClientID: ID Aplikasi (klien) -
AuthCertificatePath: Jalur ke file sertifikat PFX/PKCS12 -
AuthCertificatePassword: Kata sandi sertifikat -
AuthTenantID: ID penyewa Azure
Autentikasi Token Akses
Terbaik untuk: Skenario autentikasi kustom
// Acquire token through custom mechanism
String accessToken = acquireTokenFromCustomSource();
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=5;" + // Access token authentication
"AuthAccessToken=" + accessToken + ";" +
"LogLevel=INFO";
Connection conn = DriverManager.getConnection(url);
Penyimpanan Sementara Autentikasi
Driver secara otomatis menyimpan token autentikasi untuk meningkatkan performa:
// Enable/disable caching (enabled by default)
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=2;" +
"AuthEnableCaching=true;" + // Enable token caching
"AuthCacheTTLMS=3600000"; // Cache TTL: 1 hour
Connection conn = DriverManager.getConnection(url);
Parameter Konfigurasi
Parameter yang Diperlukan
Parameter ini harus ada di setiap string koneksi:
| Pengaturan | Tipe | Description | Example |
|---|---|---|---|
FabricWorkspaceID |
UUID (Pengidentifikasi Unik Universal) | Pengidentifikasi ruang kerja Microsoft Fabric | <workspace-id> |
FabricLakehouseID |
UUID (Pengidentifikasi Unik Universal) | Pengidentifikasi Microsoft Fabric lakehouse | <lakehouse-id> |
AuthFlow |
Integer | Jenis alur autentikasi (1-5) | 2 |
Parameter Pilihan
Konfigurasi Versi API
| Pengaturan | Tipe | Bawaan | Description |
|---|---|---|---|
FabricVersion |
String | v1 |
Versi Microsoft Fabric API |
LivyApiVersion |
String | 2023-12-01 |
Versi LIVY API |
Konfigurasi Lingkungan
| Pengaturan | Tipe | Bawaan | Description |
|---|---|---|---|
FabricEnvironmentID |
UUID (Pengidentifikasi Unik Universal) | None | Pengidentifikasi lingkungan fabric untuk mereferensikan item lingkungan untuk sesi Spark |
Konfigurasi Spark
Konfigurasi Sumber Daya Sesi
Konfigurasikan sumber daya sesi Spark untuk performa optimal:
| Pengaturan | Tipe | Bawaan | Description | Example |
|---|---|---|---|---|
DriverCores |
Integer | Default Spark | Jumlah inti CPU untuk driver | 4 |
DriverMemory |
String | Default Spark | Alokasi memori untuk driver | 4g |
ExecutorCores |
Integer | Default Spark | Jumlah inti CPU per eksekutor | 4 |
ExecutorMemory |
String | Default Spark | Alokasi memori untuk setiap eksekutor | 8g |
NumExecutors |
Integer | Default Spark | Jumlah pelaksana | 2 |
Example:
DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2
Properti Sesi Spark Khusus
Parameter apa pun dengan awalan spark. secara otomatis diterapkan ke sesi Spark:
Contoh Konfigurasi Spark:
spark.sql.adaptive.enabled=true
spark.sql.adaptive.coalescePartitions.enabled=true
spark.sql.shuffle.partitions=200
spark.sql.autoBroadcastJoinThreshold=10485760
spark.dynamicAllocation.enabled=true
spark.dynamicAllocation.minExecutors=1
spark.dynamicAllocation.maxExecutors=10
spark.executor.memoryOverhead=1g
Native Execution Engine (NEE):
spark.nee.enabled=true
Contoh Lengkap:
jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<guid>;FabricLakehouseID=<guid>;DriverMemory=4g;ExecutorMemory=8g;NumExecutors=2;spark.sql.adaptive.enabled=true;spark.nee.enabled=true;AuthFlow=2
Konfigurasi Kumpulan Koneksi HTTP
Konfigurasikan pengumpulan koneksi HTTP untuk performa jaringan yang optimal:
| Pengaturan | Tipe | Bawaan | Description |
|---|---|---|---|
HttpMaxTotalConnections |
Integer | 100 | Total koneksi HTTP maksimum |
HttpMaxConnectionsPerRoute |
Integer | 50 | Jumlah koneksi maksimum per rute |
HttpConnectionTimeoutInSeconds |
Integer | 30 | Batas waktu koneksi |
HttpSocketTimeoutInSeconds |
Integer | 60 | Batas waktu baca soket |
HttpReadTimeoutInSeconds |
Integer | 60 | Batas waktu baca HTTP |
HttpConnectionRequestTimeoutSeconds |
Integer | 30 | Batas waktu permintaan koneksi dari kumpulan |
HttpEnableKeepAlive |
Boolean | true | Aktifkan HTTP keep-alive |
HttpKeepAliveTimeoutSeconds |
Integer | 60 | Waktu tunggu koneksi tetap aktif |
HttpFollowRedirects |
Boolean | true | Ikuti pengalihan HTTP |
HttpUseAsyncIO |
Boolean | false | Gunakan I/O HTTP asinkron |
Example:
HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60
Konfigurasi Proksi
Konfigurasikan pengaturan proksi HTTP dan SOCKS untuk lingkungan perusahaan:
| Pengaturan | Tipe | Bawaan | Description |
|---|---|---|---|
UseProxy |
Boolean | false | Aktifkan proksi |
ProxyTransport |
String | http |
Jenis transport proksi (http/tcp) |
ProxyHost |
String | None | Nama host proksi |
ProxyPort |
Integer | None | Port proxy |
ProxyAuthEnabled |
Boolean | false | Mengaktifkan autentikasi proksi |
ProxyUsername |
String | None | Nama pengguna autentikasi proksi |
ProxyPassword |
String | None | Kata sandi autentikasi proksi |
ProxyAuthScheme |
String | basic |
Skema autentikasi (basic/digest/ntlm) |
ProxySocksVersion |
Integer | 5 | Versi SOCKS (4/5) |
Contoh Proksi HTTP:
UseProxy=true;ProxyTransport=http;ProxyHost=proxy.company.com;ProxyPort=8080;ProxyAuthEnabled=true;ProxyUsername=user;ProxyPassword=pass
Contoh Proksi SOCKS:
UseProxy=true;ProxyTransport=tcp;ProxyHost=socks.company.com;ProxyPort=1080;ProxySocksVersion=5
Konfigurasi Pengelogan
| Pengaturan | Tipe | Bawaan | Description |
|---|---|---|---|
LogLevel |
String | INFO |
Tingkat pengelogan: TRACE, DEBUG, INFO, PERINGATAN, KESALAHAN |
Example:
LogLevel=DEBUG
Lokasi Log Default:
${user.home}/.microsoft/livy-jdbc-driver/driver.log
Konfigurasi Log Kustom: Gunakan kustom log4j2.xml atau logback.xml file di classpath Anda.
Contoh Penggunaan
Koneksi Dasar
import java.sql.*;
public class BasicConnectionExample {
public static void main(String[] args) {
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
"FabricWorkspaceID=<workspace-id>;" +
"FabricLakehouseID=<lakehouse-id>;" +
"AuthFlow=2";
try (Connection conn = DriverManager.getConnection(url)) {
System.out.println("Connected successfully!");
System.out.println("Database: " + conn.getMetaData().getDatabaseProductName());
System.out.println("Driver: " + conn.getMetaData().getDriverName());
System.out.println("Driver Version: " + conn.getMetaData().getDriverVersion());
} catch (SQLException e) {
System.err.println("Connection failed: " + e.getMessage());
e.printStackTrace();
}
}
}
Menjalankan Pertanyaan
Kueri Sederhana
public void executeSimpleQuery(Connection conn) throws SQLException {
String sql = "SELECT current_timestamp() as now";
try (Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
if (rs.next()) {
Timestamp now = rs.getTimestamp("now");
System.out.println("Current timestamp: " + now);
}
}
}
Kueri dengan Filter
public void executeQueryWithFilter(Connection conn) throws SQLException {
String sql = "SELECT * FROM sales WHERE amount > 1000 ORDER BY amount DESC";
try (Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
while (rs.next()) {
int id = rs.getInt("id");
double amount = rs.getDouble("amount");
Date date = rs.getDate("sale_date");
System.out.printf("ID: %d, Amount: %.2f, Date: %s%n",
id, amount, date);
}
}
}
Kueri dengan Batas
public void executeQueryWithLimit(Connection conn) throws SQLException {
String sql = "SELECT * FROM customers LIMIT 10";
try (Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
ResultSetMetaData metaData = rs.getMetaData();
int columnCount = metaData.getColumnCount();
// Print column names
for (int i = 1; i <= columnCount; i++) {
System.out.print(metaData.getColumnName(i) + "\t");
}
System.out.println();
// Print rows
while (rs.next()) {
for (int i = 1; i <= columnCount; i++) {
System.out.print(rs.getString(i) + "\t");
}
System.out.println();
}
}
}
Bekerja dengan Tataan Hasil
Menavigasi Tataan Hasil
public void navigateResultSet(Connection conn) throws SQLException {
String sql = "SELECT id, name, amount FROM orders";
try (Statement stmt = conn.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_READ_ONLY);
ResultSet rs = stmt.executeQuery(sql)) {
// Move to first row
if (rs.first()) {
System.out.println("First row: " + rs.getString("name"));
}
// Move to last row
if (rs.last()) {
System.out.println("Last row: " + rs.getString("name"));
System.out.println("Total rows: " + rs.getRow());
}
// Move to specific row
if (rs.absolute(5)) {
System.out.println("Row 5: " + rs.getString("name"));
}
}
}
Memproses Tataan Hasil Besar
public void processLargeResultSet(Connection conn) throws SQLException {
String sql = "SELECT * FROM large_table";
try (Statement stmt = conn.createStatement()) {
// Set fetch size for efficient memory usage
stmt.setFetchSize(1000);
try (ResultSet rs = stmt.executeQuery(sql)) {
int rowCount = 0;
while (rs.next()) {
// Process row
processRow(rs);
rowCount++;
if (rowCount % 10000 == 0) {
System.out.println("Processed " + rowCount + " rows");
}
}
System.out.println("Total rows processed: " + rowCount);
}
}
}
private void processRow(ResultSet rs) throws SQLException {
// Process individual row
}
Menggunakan Pernyataan yang Disiapkan
public void usePreparedStatement(Connection conn) throws SQLException {
String sql = "SELECT * FROM products WHERE category = ? AND price > ?";
try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
// Set parameters
pstmt.setString(1, "Electronics");
pstmt.setDouble(2, 100.0);
try (ResultSet rs = pstmt.executeQuery()) {
while (rs.next()) {
String name = rs.getString("name");
double price = rs.getDouble("price");
System.out.printf("Product: %s, Price: $%.2f%n", name, price);
}
}
}
}
Operasi Batch
public void executeBatchInsert(Connection conn) throws SQLException {
String sql = "INSERT INTO logs (timestamp, level, message) VALUES (?, ?, ?)";
try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
conn.setAutoCommit(false); // Disable auto-commit for batch
// Add multiple statements to batch
for (int i = 0; i < 1000; i++) {
pstmt.setTimestamp(1, new Timestamp(System.currentTimeMillis()));
pstmt.setString(2, "INFO");
pstmt.setString(3, "Log message " + i);
pstmt.addBatch();
// Execute batch every 100 statements
if (i % 100 == 0) {
pstmt.executeBatch();
pstmt.clearBatch();
}
}
// Execute remaining statements
pstmt.executeBatch();
conn.commit();
System.out.println("Batch insert completed successfully");
} catch (SQLException e) {
conn.rollback();
throw e;
} finally {
conn.setAutoCommit(true);
}
}
Pemetaan Tipe Data
Driver memetakan jenis data Spark SQL ke jenis JDBC SQL dan jenis Java:
| Jenis Spark SQL | Jenis JDBC SQL | Jenis Java | Catatan |
|---|---|---|---|
BOOLEAN |
BOOLEAN |
Boolean |
|
BYTE |
TINYINT |
Byte |
|
SHORT |
SMALLINT |
Short |
|
INT |
INTEGER |
Integer |
|
LONG |
BIGINT |
Long |
|
FLOAT |
FLOAT |
Float |
|
DOUBLE |
DOUBLE |
Double |
|
DECIMAL |
DECIMAL |
BigDecimal |
Presisi dan skala dipertahankan |
STRING |
VARCHAR |
String |
|
VARCHAR(n) |
VARCHAR |
String |
|
CHAR(n) |
CHAR |
String |
|
BINARY |
BINARY |
byte[] |
|
DATE |
DATE |
java.sql.Date |
|
TIMESTAMP |
TIMESTAMP |
java.sql.Timestamp |
|
ARRAY |
VARCHAR |
String |
Diserialisasikan sebagai JSON |
MAP |
VARCHAR |
String |
Diserialisasikan sebagai JSON |
STRUCT |
VARCHAR |
String |
Diserialisasikan sebagai JSON |