Delen via


Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering (preview)

Opmerking

Deze functie is beschikbaar als preview-versie.

JDBC (Java Database Connectivity) is een veelgebruikte standaard waarmee clienttoepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

Met het Microsoft JDBC-stuurprogramma voor Fabric Data Engineering kunt u Spark-workloads in Microsoft Fabric verbinden, opvragen en beheren met de betrouwbaarheid en eenvoud van de JDBC-standaard. Het stuurprogramma is gebouwd op livy-API's van Microsoft Fabric en biedt veilige en flexibele Spark SQL-connectiviteit met uw Java-toepassingen en BI-hulpprogramma's. Met deze integratie kunt u Spark-code rechtstreeks verzenden en uitvoeren zonder afzonderlijke notebook- of Spark-taakdefinitieartefacten te hoeven maken.

Belangrijke functies

  • JDBC 4.2 Compatibel: volledige implementatie van JDBC 4.2-specificatie
  • Microsoft Entra ID-verificatie: meerdere verificatiestromen, waaronder interactieve, clientreferenties en verificatie op basis van certificaten
  • Groepsgewijze bedrijfsverbindingen: ingebouwde groepsgewijze verbindingen met statuscontrole en automatisch herstel
  • Ondersteuning voor systeemeigen Spark SQL-query's: directe uitvoering van Spark SQL-instructies zonder vertaling
  • Uitgebreide ondersteuning voor gegevenstypen: ondersteuning voor alle Spark SQL-gegevenstypen, waaronder complexe typen (ARRAY, MAP, STRUCT)
  • Asynchrone resultatenset prefetching: achtergrondgegevens laden voor verbeterde prestaties
  • Circuit Breaker-patroon: beveiliging tegen cascaderende fouten met automatische pogingen
  • Automatisch opnieuw verbinding maken: Transparant sessieherstel bij verbindingsfouten
  • Proxyondersteuning: HTTP- en SOCKS-proxyconfiguratie voor bedrijfsomgevingen

Vereiste voorwaarden

Voordat u het Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering gebruikt, moet u ervoor zorgen dat u het volgende hebt:

  • Java Development Kit (JDK): versie 11 of hoger (Java 21 aanbevolen)
  • Microsoft Fabric Access: Toegang tot een Microsoft Fabric-werkruimte
  • Referenties voor Azure Entra ID: juiste referenties voor authenticatie
  • Werkruimte- en Lakehouse-id's: GUID-id's voor uw Fabric-werkruimte en Lakehouse

Downloaden en installeren

Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering versie 1.0.0 is de openbare preview-versie en ondersteunt Java 11, 17 en 21. We verbeteren voortdurend ondersteuning voor Java-connectiviteit en raden u aan met de nieuwste versie van het Microsoft JDBC-stuurprogramma te werken.

  1. Download het zip- of tar-bestand via de bovenstaande koppelingen.
  2. Pak het gedownloade bestand uit om toegang te krijgen tot de JAR-bestanden van het stuurprogramma.
  3. Selecteer het JAR-bestand dat overeenkomt met uw JRE-versie:
    • Voor Java 11: ms-sparksql-jdbc-1.0.0.jre11.jar
    • Voor Java 17: ms-sparksql-jdbc-1.0.0.jre17.jar
    • Voor Java 21: ms-sparksql-jdbc-1.0.0.jre21.jar
  4. Voeg het geselecteerde JAR-bestand toe aan het klassepad van uw toepassing.
  5. Voor JDBC-clients configureert u de JDBC-stuurprogrammaklasse: com.microsoft.spark.livy.jdbc.LivyDriver

Snelstartvoorbeeld

In dit voorbeeld ziet u hoe u verbinding maakt met Microsoft Fabric en een query uitvoert met behulp van het Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering. Voordat u deze code uitvoert, moet u ervoor zorgen dat u de vereisten hebt voltooid en het stuurprogramma hebt geïnstalleerd.

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

Formaat van verbindingsstring

Basisverbindingsreeks

Het Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering maakt gebruik van de volgende verbindingsreeksindeling:

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

Componenten van de connection string

Onderdeel Description Example
Protocol JDBC URL-protocolidentificatie jdbc:fabricspark://
Hostnaam Hostnaam van Microsoft Fabric-eindpunt api.fabric.microsoft.com
port Optioneel poortnummer (standaard: 443) :443
Parameters Door puntkomma's gescheiden sleutel=waarde paren FabricWorkspaceID=<guid>

Voorbeeld van verbindingsreeksen

Basisverbinding (verificatie op basis van interactieve browser)

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

Met Spark-resourceconfiguratie

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

Met eigenschappen van Spark-sessie

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

Authenticatie

Het Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering ondersteunt meerdere verificatiemethoden via Microsoft Entra ID (voorheen Azure Active Directory). Verificatie wordt geconfigureerd met behulp van de AuthFlow parameter in de verbindingsreeks.

Verificatiestromen

AuthFlow Verificatiemethode Gebruikssituatie
1 Interactieve browser Interactieve gebruikersverificatie met OAuth 2.0
2 Azure-opdrachtregelinterface (CLI) Ontwikkeling met behulp van Azure CLI
3 Referenties voor clientgeheim (service-principal) Geautomatiseerde/service-naar-service-authenticatie
4 Referentie voor clientcertificaat Authenticatie van een service-principal op basis van certificaat
5 Toegangstoken Vooraf verkregen bearer-toegangstoken

Interactieve browserverificatie

Geschikt voor: Ontwikkeling en interactieve toepassingen

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

Parameters:

  • AuthFlow=1: Specificeert interactieve browserverificatie
  • AuthTenantID (optioneel): Azure-tenant-id
  • AuthClientID (optioneel): Toepassing (client) ID

Gedrag:

  • Hiermee opent u een browservenster voor gebruikersverificatie
  • Referenties worden opgeslagen in de cache voor volgende verbindingen totdat deze verlopen is
  • Geschikt voor toepassingen met één gebruiker

Client- of Servicegebruikerauthenticatie

Geschikt voor: Geautomatiseerde services en achtergrondtaken

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

Vereiste parameters:

  • AuthFlow=3: Hiermee specificeert u client-credentials-authenticatie
  • AuthClientID: Toepassings-ID (client) van Microsoft Entra ID
  • AuthClientSecret: Clientgeheim van Microsoft Entra-id
  • AuthTenantID: Azure-tenant-id

Best practices:

  • Geheimen veilig opslaan (Azure Key Vault, omgevingsvariabelen)
  • Beheerde identiteiten gebruiken indien mogelijk
  • Geheimen regelmatig roteren

Certificate-Based Authenticatie

Geschikt voor: Bedrijfstoepassingen waarvoor verificatie op basis van certificaten is vereist

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

Vereiste parameters:

  • AuthFlow=4: Hiermee geeft u verificatie op basis van certificaten op
  • AuthClientID: Applicatie-ID (client)
  • AuthCertificatePath: Pad naar PFX-/PKCS12-certificaatbestand
  • AuthCertificatePassword: Certificaatwachtwoord
  • AuthTenantID: Azure-tenant-id

Verificatie van toegangstokens

Geschikt voor: Scenario's voor aangepaste verificatie

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

Verificatiecaching

Het stuurprogramma slaat verificatietokens automatisch in de cache op om de prestaties te verbeteren:

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

Configuratieparameters

Vereiste parameters

Deze parameters moeten aanwezig zijn in elke verbindingsreeks:

Kenmerk Typologie Description Example
FabricWorkspaceID UUID (universeel unieke identificator) Microsoft Fabric-werkruimte-id <workspace-id>
FabricLakehouseID UUID (universeel unieke identificator) Microsoft Fabric Lakehouse-id <lakehouse-id>
AuthFlow Integer Verificatiestroomtype (1-5) 2

Optionele parameters

API-versieconfiguratie

Kenmerk Typologie Verstek Description
FabricVersion Snaar / Touwtje v1 Microsoft Fabric API-versie
LivyApiVersion Snaar / Touwtje 2023-12-01 Livy-API-versie

Omgevingsconfiguratie

Kenmerk Typologie Verstek Description
FabricEnvironmentID UUID (universeel unieke identificator) Geen Fabric-omgeving-ID voor het refereren aan een item binnen de omgeving voor een Spark-sessie

Spark-configuratie

Configuratie van sessieresource

Spark-sessiebronnen configureren voor optimale prestaties:

Kenmerk Typologie Verstek Description Example
DriverCores Integer Spark-standaardwaarde Aantal CPU-kernen voor stuurprogramma 4
DriverMemory Snaar / Touwtje Spark-standaardwaarde Geheugentoewijzing voor stuurprogramma 4g
ExecutorCores Integer Spark-standaardwaarde Aantal CPU-kernen per uitvoerder 4
ExecutorMemory Snaar / Touwtje Spark-standaardwaarde Geheugentoewijzing per uitvoerder 8g
NumExecutors Integer Spark-standaardwaarde Aantal uitvoerders 2

Example:

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

Eigenschappen van aangepaste Spark-sessie

Elke parameter met het voorvoegsel spark. wordt automatisch toegepast op de Spark-sessie:

Voorbeeld van Spark-configuraties:

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

Systeemeigen uitvoeringsengine (NEE):

spark.nee.enabled=true

Volledig voorbeeld:

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

Configuratie van HTTP-verbindingsgroep

HTTP-verbindingspooling configureren voor optimale netwerkprestaties:

Kenmerk Typologie Verstek Description
HttpMaxTotalConnections Integer 100 Maximumaantal HTTP-verbindingen
HttpMaxConnectionsPerRoute Integer 50 Maximum aantal verbindingen per route
HttpConnectionTimeoutInSeconds Integer 30 Verbindingstijd is verlopen
HttpSocketTimeoutInSeconds Integer 60 Time-out voor socketleesbewerking
HttpReadTimeoutInSeconds Integer 60 Time-out voor HTTP-leesbewerking
HttpConnectionRequestTimeoutSeconds Integer 30 Time-out van verbindingsaanvraag vanuit pool
HttpEnableKeepAlive Booleaan true HTTP-keep-alive inschakelen
HttpKeepAliveTimeoutSeconds Integer 60 Keep-alive time-out
HttpFollowRedirects Booleaan true HTTP-omleidingen volgen
HttpUseAsyncIO Booleaan false Asynchrone HTTP I/O gebruiken

Example:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxyconfiguratie

HTTP- en SOCKS-proxyinstellingen configureren voor bedrijfsomgevingen:

Kenmerk Typologie Verstek Description
UseProxy Booleaan false Proxy inschakelen
ProxyTransport Snaar / Touwtje http Proxy-transporttype (http/tcp)
ProxyHost Snaar / Touwtje Geen Proxyhostnaam
ProxyPort Integer Geen Proxypoort
ProxyAuthEnabled Booleaan false Proxyverificatie inschakelen
ProxyUsername Snaar / Touwtje Geen Gebruikersnaam voor proxyverificatie
ProxyPassword Snaar / Touwtje Geen Wachtwoord voor proxyverificatie
ProxyAuthScheme Snaar / Touwtje basic Authenticatieschema (basic/digest/ntlm)
ProxySocksVersion Integer 5 SOCKS-versie (4/5)

Voorbeeld van HTTP-proxy:

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

Voorbeeld van SOCKS-proxy:

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

Configuratie van logboekregistratie

Kenmerk Typologie Verstek Description
LogLevel Snaar / Touwtje INFO Niveau van logboekregistratie: TRACE, DEBUG, INFO, WAARSCHUWING, FOUT

Example:

LogLevel=DEBUG

Standaardlocatie van logboek:

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

Aangepaste logboekconfiguratie: Gebruik een aangepast log4j2.xml bestand of logback.xml bestand in uw klaspad.


Gebruiksvoorbeelden

Basisverbinding

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

Query's uitvoeren

Eenvoudige query

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

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

Query met limiet

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

Werken met resultatensets

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

Grote resultatensets verwerken

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
}

Voorbereide instructies gebruiken

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

Batchverwerkingen

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

Gegevenstypemapping

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan JDBC SQL-typen en Java-typen:

Spark SQL-type JDBC SQL-type Java type Opmerkingen
BOOLEAN BOOLEAN Boolean
BYTE TINYINT Byte
SHORT SMALLINT Short
INT INTEGER Integer
LONG BIGINT Long
FLOAT FLOAT Float
DOUBLE DOUBLE Double
DECIMAL DECIMAL BigDecimal Precisie en schaal behouden
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 Geserialiseerd als JSON
MAP VARCHAR String Geserialiseerd als JSON
STRUCT VARCHAR String Geserialiseerd als JSON