Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering (Vorschau)

JDBC (Java Database Connectivity) ist ein weit verbreiteter Standard, der es Clientanwendungen ermöglicht, eine Verbindung zu Datenbanken und Big-Data-Plattformen herzustellen und mit diesen zu arbeiten.

Mit dem Microsoft JDBC-Treiber für Fabric Data Engineering können Sie eine Verbindung zu Spark-Workloads in Microsoft Fabric herstellen, sie abfragen und verwalten – basierend auf der Zuverlässigkeit und Einfachheit des JDBC-Standards. Basierend auf den Livy-APIs von Microsoft Fabric bietet der Treiber sichere und flexible Spark SQL-Konnektivität zu Ihren Java-Anwendungen und BI-Tools. Mit dieser Integration können Sie Spark-Code direkt übermitteln und ausführen, ohne separate Notizbuch- oder SparkAuftragsdefinitionsartefakte erstellen zu müssen.

Wichtige Merkmale

• JDBC 4.2 konform: Vollständige Implementierung der JDBC 4.2-Spezifikation
• Microsoft Entra ID-Authentifizierung: Mehrere Authentifizierungsflüsse, einschließlich interaktiver, Clientanmeldeinformationen und zertifikatbasierter Authentifizierung
• Enterprise-Verbindungspooling: Ein integriertes Verbindungspooling mit Gesundheitsüberwachung und automatischer Wiederherstellung
• Spark SQL Native Query-Unterstützung: Direkte Ausführung von Spark SQL-Anweisungen ohne Übersetzung
• Umfassende Unterstützung für Datentypen: Unterstützung für alle Spark SQL-Datentypen einschließlich komplexer Typen (ARRAY, MAP, STRUCT)
• Asynchrones Ergebnismengen-Prefetching: Hintergrunddatenladen für verbesserte Leistung
• Circuit Breaker Pattern: Schutz vor kaskadierenden Ausfällen mit automatischem Retry
• Automatische Wiederverbindung: Transparente Sitzungswiederherstellung bei Verbindungsfehlern
• Proxyunterstützung: HTTP- und SOCKS-Proxykonfiguration für Unternehmensumgebungen

Voraussetzungen

Bevor Sie den Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering verwenden, stellen Sie Folgendes sicher:

• Java Development Kit (JDK): Version 11 oder höher (Java 21 empfohlen)
• Microsoft Fabric Access: Zugriff auf einen Microsoft Fabric-Arbeitsbereich
• Azure Entra ID-Anmeldeinformationen: Geeignete Anmeldeinformationen für die Authentifizierung
• Arbeitsbereichs- und Lakehouse-IDs: GUID-IDs für den Fabric-Arbeitsbereich und das Lakehouse

Herunterladen und Installieren

Microsoft JDBC Driver für Microsoft Fabric Data Engineering Version 1.0.0 ist die öffentliche Vorschau und unterstützt Java 11, 17 und 21. Wir verbessern kontinuierlich die Java-Konnektivitätsunterstützung und empfehlen Ihnen, mit der neuesten Version des Microsoft ASPX-Treibers zu arbeiten.

• Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering (ZIP) herunterladen
• Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering herunterladen (tar)

1. Laden Sie entweder die ZIP- oder Tar-Datei aus den obigen Links herunter.
2. Extrahieren Sie die heruntergeladene Datei, um auf die Treiber-JAR-Dateien zuzugreifen.
3. Wählen Sie die JAR-Datei aus, die Ihrer JRE-Version entspricht:
   • Für Java 11: ms-sparksql-jdbc-1.0.0.jre11.jar
   • Für Java 17: ms-sparksql-jdbc-1.0.0.jre17.jar
   • Für Java 21: ms-sparksql-jdbc-1.0.0.jre21.jar
4. Fügen Sie die ausgewählte JAR-Datei zum Klassenpfad Ihrer Anwendung hinzu.
5. Konfigurieren Sie für JDBC-Clients die JDBC-Treiberklasse: com.microsoft.spark.livy.jdbc.LivyDriver

Schnellstartbeispiel

In diesem Beispiel wird veranschaulicht, wie Sie eine Verbindung mit Microsoft Fabric herstellen und eine Abfrage mithilfe des Microsoft FABRIC Data Engineering-Treibers ausführen. Stellen Sie sicher, dass Sie die Voraussetzungen erfüllt und den Treiber installiert haben, bevor Sie diesen Code ausführen.

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;" +  // Interactive browser 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();
        }
    }
}

Verbindungszeichenfolgenformat

Basisverbindungszeichenfolge

Der Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering verwendet das folgende Verbindungszeichenfolgenformat:

jdbc:fabricspark://<hostname>[:<port>][;<parameter1>=<value1>;<parameter2>=<value2>;...]

Verbindungskettenkomponenten

Beispielverbindungszeichenfolgen

Standardverbindung (interaktive Authentifizierung)

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=2

Mit Spark-Ressourcenkonfiguration

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2;AuthFlow=2

Mit Spark Session-Eigenschaften

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;spark.sql.adaptive.enabled=true;spark.sql.shuffle.partitions=200;AuthFlow=2

Authentifizierung

Der Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering unterstützt mehrere Authentifizierungsmethoden über Microsoft Entra ID (früher Azure Active Directory). Die Authentifizierung wird mithilfe des AuthFlow Parameters in der Verbindungszeichenfolge konfiguriert.

Authentifizierungsabläufe

Interaktive Browserauthentifizierung

Am besten geeignet für: Entwicklung und interaktive Anwendungen

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=2;" +  // Interactive browser authentication
             "AuthTenantID=<tenant-id>;" +  // Optional
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Parameter:

• AuthFlow=2: Gibt die interaktive Browserauthentifizierung an.
• AuthTenantID (optional): Azure-Mandanten-ID
• AuthClientID (optional): Anwendungs-ID (Client)

Benehmen:

• Öffnet ein Browserfenster für die Benutzerauthentifizierung.
• Anmeldeinformationen werden für nachfolgende Verbindungen zwischengespeichert, bis sie abgelaufen sind.
• Geeignet für Einzelbenutzeranwendungen

Clientanmeldeinformationen-Authentifizierung

Am besten geeignet für: Automatisierte Dienste und Hintergrundaufträge

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=1;" +  // Client credentials authentication
             "AuthClientID=<client-id>;" +
             "AuthClientSecret=<client-secret>;" +
             "AuthTenantID=<tenant-id>;" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Erforderliche Parameter:

• AuthFlow=1: Gibt die Authentifizierung der Clientanmeldeinformationen an.
• AuthClientID: Anwendungs-ID (Client-ID) von Microsoft Entra ID
• AuthClientSecret: Geheimer Clientschlüssel von Microsoft Entra ID
• AuthTenantID: Azure-Mandanten-ID

Bewährte Methoden:

• Sicheres Speichern geheimer Schlüssel (Azure Key Vault, Umgebungsvariablen)
• Verwenden von verwalteten Identitäten nach Möglichkeit
• Regelmäßiges Erneuern von Geheimnissen

zertifikatbasierte Authentifizierung

Am besten geeignet für: Unternehmensanwendungen, die zertifikatbasierte Authentifizierung erfordern

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=4;" +  // Certificate-based authentication
             "AuthClientID=<client-id>;" +
             "AuthCertificatePath=/path/to/certificate.pfx;" +
             "AuthCertificatePassword=<certificate-password>;" +
             "AuthTenantID=<tenant-id>;" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Erforderliche Parameter:

• AuthFlow=4: Gibt die zertifikatbasierte Authentifizierung an.
• AuthClientID: Anwendungs-ID (Client-ID)
• AuthCertificatePath: Pfad zur PFX/PKCS12-Zertifikatdatei
• AuthCertificatePassword: Zertifikatkennwort
• AuthTenantID: Azure-Mandanten-ID

Dienstprinzipalauthentifizierung

Am besten geeignet für: Headless-Umgebungen und Remotesitzungen

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=3;" +  // Device code authentication
             "AuthClientID=<client-id>;" +
             "AuthTenantID=<tenant-id>;" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Benehmen:

• Zeigt einen Gerätecode und eine URL in der Konsole an.
• Der Benutzer besucht die URL und gibt den Code ein.
• Die Authentifizierung wird nach der Benutzerüberprüfung abgeschlossen.

Zugriffstokenauthentifizierung

Am besten geeignet für: Benutzerdefinierte Authentifizierungsszenarien

// 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);

Zwischenspeichern der Authentifizierung

Der Treiber speichert Authentifizierungstoken automatisch zwischen, um die Leistung zu verbessern:

// 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);

Konfigurationsparameter

Erforderliche Parameter

Diese Parameter müssen in jeder Verbindungszeichenfolge vorhanden sein:

Optionale Parameter

API-Versionskonfiguration

Umgebungskonfiguration

Spark-Konfiguration

Sitzungsressourcenkonfiguration

Konfigurieren sie Spark-Sitzungsressourcen für eine optimale Leistung:

Example:

DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2

Benutzerdefinierte Spark-Sitzungseigenschaften

Jeder Parameter mit dem Präfix spark. wird automatisch auf die Spark-Sitzung angewendet:

Beispiel-Spark-Konfigurationen:

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

Natives Ausführungsmodul (NEE):

spark.nee.enabled=true

Vollständiges Beispiel:

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

HTTP-Verbindungspoolkonfiguration

Konfigurieren sie die HTTP-Verbindungspooling für eine optimale Netzwerkleistung:

Example:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxykonfiguration

Konfigurieren von HTTP- und SOCKEN-Proxyeinstellungen für Unternehmensumgebungen:

HTTP-Proxybeispiel:

UseProxy=true;ProxyTransport=http;ProxyHost=proxy.company.com;ProxyPort=8080;ProxyAuthEnabled=true;ProxyUsername=user;ProxyPassword=pass

SOCKEN-Proxybeispiel:

UseProxy=true;ProxyTransport=tcp;ProxyHost=socks.company.com;ProxyPort=1080;ProxySocksVersion=5

Protokollierungskonfiguration

Example:

LogLevel=DEBUG

Standardprotokollspeicherort:

${user.home}/.microsoft/livy-jdbc-driver/driver.log

Benutzerdefinierte Protokollkonfiguration: Verwenden Sie eine benutzerdefinierte log4j2.xml- oder logback.xml-Datei in Ihrem Klassenpfad.

Verwendungsbeispiele

Grundlegende Verbindung

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();
        }
    }
}

Ausführen von Abfragen

Einfache Abfrage

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);
        }
    }
}

Abfrage mit 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);
        }
    }
}

Abfrage mit Limit

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();
        }
    }
}

Arbeiten mit Resultsets

Navigieren in Ergebnismengen

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"));
        }
    }
}

Verarbeiten großer Ergebnismengen

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
}

Verwendung vorbereiteter Anweisungen

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);
            }
        }
    }
}

Batchvorgänge

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);
    }
}

Datentypzuordnung

Der Treiber ordnet Spark SQL-Datentypen JDBC-SQL-Typen und Java-Typen zu.

Verwandte Inhalte

• Apache Spark-Runtimes in Fabric
• Fabric Runtime 1.3
• Was ist die Livy-API für Data Engineering