Bagikan melalui


Driver Microsoft JDBC untuk Microsoft Fabric Data Engineering (pratinjau)

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.

  1. Unduh file zip atau tar dari tautan di atas.
  2. Ekstrak file yang diunduh untuk mengakses file JAR driver.
  3. 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
  4. Tambahkan file JAR yang dipilih ke classpath aplikasi Anda.
  5. 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

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