Del via


Microsoft JDBC-driver til Microsoft Fabric Data Engineering (forhåndsvisning)

Notat

Denne funktion er en prøveversion.

JDBC (Java Database Connectivity) er en bredt anvendt standard, der gør det muligt for klientapplikationer at forbinde til og arbejde med data fra databaser og big data-platforme.

Microsoft JDBC Driver for Fabric Data Engineering lader dig forbinde, forespørge og administrere Spark-arbejdsbelastninger i Microsoft Fabric med pålideligheden og enkelheden fra JDBC-standarden. Drevet er bygget på Microsoft Fabrics Livy API'er og leverer sikker og fleksibel Spark SQL-forbindelse til dine Java-applikationer og BI-værktøjer. Denne integration gør det muligt at indsende og køre Spark-kode direkte uden at skulle oprette separate Notebook- eller Spark Job Definition-artefakter.

Vigtige funktioner

  • JDBC 4.2-kompatibel: Fuld implementering af JDBC 4.2-specifikationen
  • Microsoft Entra ID-autentificering: Flere autentificeringsflows, herunder interaktiv, klientoplysninger og certifikatbaseret autentificering
  • Enterprise Connection Pooling: Indbygget forbindelsespooling med sundhedsovervågning og automatisk gendannelse
  • Spark SQL Native Query Support: Direkte udførelse af Spark SQL-sætninger uden oversættelse
  • Omfattende understøttelse af datatyper: Understøttelse af alle Spark SQL-datatyper inklusive komplekse typer (ARRAY, MAP, STRUCT)
  • Asynkron resultatmængde forudhentning: Indlæsning af baggrundsdata for forbedret ydeevne
  • Circuit Breaker-mønster: Beskyttelse mod kaskaderede fejl med automatisk genprøvning
  • Auto-genforbindelse: Gennemsigtig sessionsgendannelse ved forbindelsesfejl
  • Proxy-understøttelse: HTTP- og SOCKS-proxykonfiguration til virksomhedsmiljøer

Forudsætninger

Før du bruger Microsoft JDBC-driveren til Microsoft Fabric Data Engineering, skal du sikre dig, at du har:

  • Java Development Kit (JDK): Version 11 eller højere (Java 21 anbefales)
  • Microsoft Fabric Access: Adgang til et Microsoft Fabric-arbejdsområde
  • Azure Entra ID Credentials: Passende legitimationsoplysninger til autentificering
  • Workspace og Lakehouse ID'er: GUID-identifikatorer for dit Fabric workspace og lakehouse

Download og installation

Microsoft JDBC Driver for Microsoft Fabric Data Engineering version 1.0.0 er den offentlige forhåndsvisning og understøtter Java 11, 17 og 21. Vi forbedrer løbende Java-forbindelsesunderstøttelsen og anbefaler, at du arbejder med den nyeste version af Microsoft JDBC-driveren.

  1. Download enten zip- eller tar-filen fra linkene ovenfor.
  2. Udpak den downloadede fil for at få adgang til driverens JAR-filer.
  3. Vælg den JAR-fil, der matcher din JRE-version:
    • For Java 11: ms-sparksql-jdbc-1.0.0.jre11.jar
    • For Java 17: ms-sparksql-jdbc-1.0.0.jre17.jar
    • For Java 21: ms-sparksql-jdbc-1.0.0.jre21.jar
  4. Tilføj den valgte JAR-fil til din applikations classpath.
  5. For JDBC-klienter konfigureres JDBC-driverklassen: com.microsoft.spark.livy.jdbc.LivyDriver

Eksempel på hurtigstart

Dette eksempel demonstrerer, hvordan man forbinder til Microsoft Fabric og udfører en forespørgsel ved hjælp af Microsoft JDBC Driver for Microsoft Fabric Data Engineering. Før du kører denne kode, skal du sikre dig, at du har opfyldt adgangskravene og installeret driveren.

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

Forbindelsesstrengsformat

Grundlæggende forbindelsesstreng

Microsoft JDBC-driveren for Microsoft Fabric Data Engineering bruger følgende forbindelsesstrengsformat:

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

Forbindelsesstrengskomponenter

Komponent Beskrivelse Eksempel
Protokol JDBC URL-protokolidentifikator jdbc:fabricspark://
Værtsnavn Microsoft Fabric endpoint værtsnavn api.fabric.microsoft.com
Havn Valgfrit portnummer (standard: 443) :443
Parametre Semikolon-separeret nøgle=værdipar FabricWorkspaceID=<guid>

Eksempel på forbindelsesstrenge

Grundlæggende forbindelse (interaktiv autentificering)

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

Med Spark Resource Configuration

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

Med Spark Session-egenskaber

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

Godkendelse

Microsoft JDBC-driveren for Microsoft Fabric Data Engineering understøtter flere autentificeringsmetoder via Microsoft Entra ID (tidligere Azure Active Directory). Autentificering konfigureres ved hjælp af parameteren AuthFlow i forbindelsesstrengen.

Autentificeringsflows

AuthFlow Godkendelsesmetode Brug sag
0 Azure CLI Credential Udvikling ved brug af Azure CLI
1 Klientoplysninger (Service Principal) Automatiseret/service-til-service autentificering
2 Interaktiv browser Interaktiv brugerautentificering (standard)
3 SPN Godkendelse af tjenesteprincipal
4 Certificate-Based Certifikatbaseret service principal-autentificering
5 Adgangstoken Foruderhvervet adgangstoken

Interaktiv browserautentificering

Bedst til: Udvikling og interaktive applikationer

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

Parametre:

  • AuthFlow=2: Specificerer interaktiv browserautentificering
  • AuthTenantID (optional): Azure tenant ID
  • AuthClientID (valgfrit): Applikations-ID (klient)

Adfærd:

  • Åbner et browservindue til brugerautentificering
  • Legitimationsoplysninger caches til efterfølgende forbindelser, indtil det er udløbet
  • Velegnet til enkeltbrugerapplikationer

Klientlegitimationsautentificering

Bedst til: Automatiserede tjenester og baggrundsjobs

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

Påkrævede parametre:

  • AuthFlow=1: Angiver klientlegitimationsautentificering
  • AuthClientID: Application (klient) ID fra Microsoft Entra ID
  • AuthClientSecret: Klienthemmelighed fra Microsoft Entra ID
  • AuthTenantID: Azure tenant ID

Bedste praksis:

  • Lagre hemmeligheder sikkert (Azure Key Vault, miljøvariabler)
  • Brug managed identities, når det er muligt
  • Roterer hemmeligheder regelmæssigt

Certificate-Based Autentificering

Bedst til: Virksomhedsapplikationer, der kræver certifikatbaseret autentificering

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

Påkrævede parametre:

  • AuthFlow=4: Specificerer certifikatbaseret autentificering
  • AuthClientID: Applikations-ID (klient)
  • AuthCertificatePath: Sti til PFX/PKCS12 certifikatfil
  • AuthCertificatePassword: Certifikatadgangskode
  • AuthTenantID: Azure tenant ID

Service Principal Autentificering

Bedst til: Headless-miljøer og fjernsessioner

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

Adfærd:

  • Viser en enhedskode og URL i konsollen
  • Brugeren besøger URL'en og indtaster koden
  • Autentificeringen fuldføres efter brugerverifikation

Adgangstoktuifikation

Bedst til: Brugerdefinerede autentificeringsscenarier

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

Autentificeringscache

Driveren cacher automatisk autentificeringstokens for at forbedre ydeevnen:

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

Konfigurationsparametre

Påkrævede parametre

Disse parametre skal være til stede i hver forbindelsesstreng:

Parameter Type Beskrivelse Eksempel
FabricWorkspaceID UUID Microsoft Fabric workspace-identifikator <workspace-id>
FabricLakehouseID UUID Microsoft Fabric lakehouse-identifikator <lakehouse-id>
AuthFlow Integer Autentificeringsflowtype (0-5) 2

Valgfrie parametre

API-versionskonfiguration

Parameter Type Standard Beskrivelse
FabricVersion String v1 Microsoft Fabric API-version
LivyApiVersion String 2023-12-01 Livy API-versionen

Miljøkonfiguration

Parameter Type Standard Beskrivelse
FabricEnvironmentID UUID Ingen Fabric-miljøidentifikator til reference-miljøelement for Spark-session

Spark-konfiguration

Konfiguration af sessionsressourcer

Konfigurer Spark-sessionsressourcer for optimal ydeevne:

Parameter Type Standard Beskrivelse Eksempel
DriverCores Integer Spark standard Antal CPU-kerner for driver 4
DriverMemory String Spark standard Hukommelsesallokering til driver 4g
ExecutorCores Integer Spark standard Antal CPU-kerner pr. eksekver 4
ExecutorMemory String Spark standard Hukommelsesallokering pr. eksekutor 8g
NumExecutors Integer Spark standard Antal eksekutorer 2

Eksempel:

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

Brugerdefinerede Spark Session-egenskaber

Enhver parameter med præfikset spark. anvendes automatisk på Spark-sessionen:

Eksempler på gnistkonfigurationer:

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

Fuldstændigt eksempel:

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 Connection Pool-konfiguration

Konfigurer HTTP-forbindelsespooling for optimal netværksydelse:

Parameter Type Standard Beskrivelse
HttpMaxTotalConnections Integer 100 Maksimalt antal HTTP-forbindelser
HttpMaxConnectionsPerRoute Integer 50 Maksimalt antal forbindelser pr. rute
HttpConnectionTimeoutInSeconds Integer 30 Timeout for forbindelse
HttpSocketTimeoutInSeconds Integer 60 Socket-læsetidsafbrydelse
HttpReadTimeoutInSeconds Integer 60 HTTP-læsetimeout
HttpConnectionRequestTimeoutSeconds Integer 30 Forbindelsesanmodning timeout fra poolen
HttpEnableKeepAlive Boolean sand Aktivér HTTP keep-alive
HttpKeepAliveTimeoutSeconds Integer 60 Keep-alive timeout
HttpFollowRedirects Boolean sand Følg HTTP-omdirigeringer
HttpUseAsyncIO Boolean falsk Brug asynkron HTTP I/O

Eksempel:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxy-konfiguration

Konfigurer HTTP- og SOCKS-proxyindstillinger til virksomhedsmiljøer:

Parameter Type Standard Beskrivelse
UseProxy Boolean falsk Aktiver proxy
ProxyTransport String http Proxy-transporttype (http/tcp)
ProxyHost String Ingen Proxy-værtsnavn
ProxyPort Integer Ingen Proxy-port
ProxyAuthEnabled Boolean falsk Aktivér proxy-autentificering
ProxyUsername String Ingen Brugernavn til proxy-autentificering
ProxyPassword String Ingen Proxy-autentificeringsadgangskode
ProxyAuthScheme String basic Auth-skema (basic/digest/ntlm)
ProxySocksVersion Integer 5 SOCKS-versionen (4/5)

HTTP-proxy eksempel:

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

SOCKS proxy-eksempel:

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

Konfiguration af logning

Parameter Type Standard Beskrivelse
LogLevel String INFO Logningsniveau: TRACE, DEBUG, INFO, WARNING, ERROR

Eksempel:

LogLevel=DEBUG

Standardlogplacering:

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

Brugerdefineret logkonfiguration: Brug en custom log4j2.xml eller logback.xml fil på din classpath.


Anvendelseseksempler

Grundlæggende forbindelse

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

Udførelse af forespørgsler

Simpel forespørgsel

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

Forespørgsel med 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);
        }
    }
}

Forespørgsel med grænse

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

Arbejde med resultatmængder

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

Behandling af store resultatsæt

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
}

Brug af forberedte udsagn

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

Batchoperationer

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

Datatypekortlægning

Driveren mapper Spark SQL-datatyper til JDBC SQL-typer og Java-typer:

Spark SQL Type JDBC SQL Type Java-type Noter
BOOLEAN BOOLEAN Boolean
BYTE TINYINT Byte
SHORT SMALLINT Short
INT INTEGER Integer
LONG BIGINT Long
FLOAT FLOAT Float
DOUBLE DOUBLE Double
DECIMAL DECIMAL BigDecimal Præcision og skala bevaret
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 Serialiseret som JSON
MAP VARCHAR String Serialiseret som JSON
STRUCT VARCHAR String Serialiseret som JSON