Condividi tramite


Driver JDBC di Microsoft per Microsoft Fabric Data Engineering (anteprima)

Annotazioni

Questa funzionalità è in anteprima.

JDBC (Java Database Connectivity) è uno standard ampiamente adottato che consente alle applicazioni client di connettersi e lavorare con i dati dai database e dalle piattaforme Big Data.

Microsoft JDBC Driver for Fabric Data Engineering consente di connettere, eseguire query e gestire carichi di lavoro Spark in Microsoft Fabric con affidabilità e semplicità dello standard JDBC. Basato sulle API Livy di Microsoft Fabric, il driver offre connettività Spark SQL sicura e flessibile alle applicazioni Java e agli strumenti di business intelligence. Questa integrazione consente di inviare ed eseguire codice Spark direttamente senza dover creare artefatti di definizione del processo Spark o notebook separati.

Funzionalità principali

  • Conforme a JDBC 4.2: implementazione completa della specifica JDBC 4.2
  • Autenticazione con ID Microsoft Entra: più flussi di autenticazione, tra cui l'autenticazione interattiva, le credenziali del client e l'autenticazione basata su certificati
  • Pool di connessioni aziendali: pool di connessioni predefinito con monitoraggio dell'integrità e ripristino automatico
  • Supporto Query Nativa di Spark SQL: Esecuzione diretta di istruzioni Spark SQL senza conversione
  • Supporto completo dei tipi di dati: supporto per tutti i tipi di dati SPARK SQL, inclusi tipi complessi (ARRAY, MAP, STRUCT)
  • Prelettura del set di risultati asincrono: caricamento dei dati in background per migliorare le prestazioni
  • Modello Circuit Breaker: protezione contro i guasti a catena con tentativo automatico
  • Riconnessione automatica: ripristino sessione trasparente in caso di errori di connessione
  • Supporto proxy: configurazione proxy HTTP e SOCKS per ambienti aziendali

Prerequisiti

Prima di usare Microsoft JDBC Driver for Microsoft Fabric Data Engineering, assicurarsi di disporre di:

  • Java Development Kit (JDK): versione 11 o successiva (Consigliato Java 21)
  • Microsoft Fabric Access: accesso a un'area di lavoro di Microsoft Fabric
  • Azure Entra ID Credentials: credenziali appropriate per l'autenticazione
  • ID area di lavoro e Lakehouse: identificatori GUID per il tuo workspace e lakehouse Fabric

Download e installazione

Microsoft JDBC Driver per Microsoft Fabric Data Engineering versione 1.0.0 è la versione di anteprima pubblica e supporta Java 11, 17 e 21. Stiamo migliorando continuamente il supporto della connettività Java e ti consigliamo di lavorare con la versione più recente del driver Microsoft JDBC.

  1. Scaricare il file ZIP o tar dai collegamenti precedenti.
  2. Estrarre il file scaricato per accedere ai file JAR del driver.
  3. Selezionare il file JAR corrispondente alla versione JRE:
    • Per Java 11: ms-sparksql-jdbc-1.0.0.jre11.jar
    • Per Java 17: ms-sparksql-jdbc-1.0.0.jre17.jar
    • Per Java 21: ms-sparksql-jdbc-1.0.0.jre21.jar
  4. Aggiungere il file JAR selezionato al classpath dell'applicazione.
  5. Per dei client JDBC, configurare classe driver JDBC: com.microsoft.spark.livy.jdbc.LivyDriver

Esempio di avvio rapido

Questo esempio illustra come connettersi a Microsoft Fabric ed eseguire una query usando Microsoft JDBC Driver for Microsoft Fabric Data Engineering. Prima di eseguire questo codice, assicurarsi di aver completato i prerequisiti e installato il 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;" +  // 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();
        }
    }
}

Formato stringa di connessione

Stringa di connessione di base

Microsoft JDBC Driver for Microsoft Fabric Data Engineering usa il formato di stringa di connessione seguente:

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

Componenti della stringa di connessione

Componente Description Example
Protocollo Identificatore del protocollo URL JDBC jdbc:fabricspark://
Nome host Nome host dell'endpoint di Microsoft Fabric api.fabric.microsoft.com
Porto Numero di porta facoltativo (impostazione predefinita: 443) :443
Parametri Coppie chiave=valore separate da punto e virgola FabricWorkspaceID=<guid>

Stringhe di connessione di esempio

Connessione di base (autenticazione interattiva)

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

Con la configurazione delle risorse 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

Con le proprietà della sessione 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 supporta più metodi di autenticazione tramite Microsoft Entra ID (in precedenza Azure Active Directory). L'autenticazione viene configurata usando il AuthFlow parametro nella stringa di connessione.

Flussi di autenticazione

AuthFlow Metodo di autenticazione Caso d'uso
0 Credenziale Azure CLI Sviluppo con l'interfaccia della riga di comando di Azure
1 Credenziali client (principale del servizio) Autenticazione automatizzata/da servizio a servizio
2 Browser interattivo Autenticazione utente interattiva (impostazione predefinita)
3 SPN Autenticazione tramite principale di servizio
4 Basato su Certificato Autenticazione dell'entità servizio basata su certificati
5 Token di accesso Token di accesso pre-acquisito

Autenticazione interattiva del browser

Ideale per: sviluppo e applicazioni interattive

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

Parametri:

  • AuthFlow=2: specifica l'autenticazione interattiva del browser
  • AuthTenantID (facoltativo): ID tenant di Azure
  • AuthClientID (facoltativo): ID applicazione (client)

Comportamento:

  • Apre una finestra del browser per l'autenticazione utente
  • Le credenziali vengono memorizzate nella cache per le connessioni successive fino alla scadenza
  • Adatto per applicazioni a utente singolo

Autenticazione delle credenziali client

Ideale per: servizi automatizzati e processi in background

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

Parametri obbligatori:

  • AuthFlow=1: specifica l'autenticazione delle credenziali client
  • AuthClientID: ID dell'applicazione (client) di Microsoft Entra ID
  • AuthClientSecret: segreto del client da Microsoft Entra ID
  • AuthTenantID: ID tenant di Azure

Procedure consigliate:

  • Archiviare i segreti in modo sicuro (Azure Key Vault, variabili di ambiente)
  • Usare le identità gestite quando possibile
  • Ruotare regolarmente i segreti

Autenticazione basata su certificati

Ideale per: applicazioni aziendali che richiedono l'autenticazione basata su certificati

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

Parametri obbligatori:

  • AuthFlow=4: specifica l'autenticazione basata su certificati
  • AuthClientID: ID applicazione (cliente)
  • AuthCertificatePath: percorso del file di certificato PFX/PKCS12
  • AuthCertificatePassword: password del certificato
  • AuthTenantID: ID tenant di Azure

Autenticazione tramite entità servizio

Ideale per: ambienti headless e sessioni remote

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

Comportamento:

  • Visualizza il codice e l'URL del dispositivo nella console
  • L'utente visita l'URL e immette il codice
  • L'autenticazione viene completata dopo la verifica dell'utente

Autenticazione del token di accesso

Ideale per: scenari di autenticazione personalizzati

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

Memorizzazione nella cache dell'autenticazione

Il driver memorizza automaticamente nella cache i token di autenticazione per migliorare le prestazioni:

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

Parametri di configurazione

Parametri obbligatori

Questi parametri devono essere presenti in ogni stringa di connessione:

Parametro TIPO Description Example
FabricWorkspaceID UUID (Identificatore Unico Universale) Identificatore dell'area di lavoro di Microsoft Fabric <workspace-id>
FabricLakehouseID UUID (Identificatore Unico Universale) Identificatore del lakehouse di Microsoft Fabric <lakehouse-id>
AuthFlow Integer Tipo di flusso di autenticazione (0-5) 2

Parametri facoltativi

Configurazione della versione dell'API

Parametro TIPO Predefinito Description
FabricVersion String v1 Versione dell'API Microsoft Fabric
LivyApiVersion String 2023-12-01 Versione dell'API Livy

Configurazione dell'ambiente

Parametro TIPO Predefinito Description
FabricEnvironmentID UUID (Identificatore Unico Universale) None Identificatore dell'ambiente di fabric per il riferimento agli elementi dell'ambiente per la sessione Spark

Configurazione di Spark

Configurazione della risorsa sessione

Configurare le risorse della sessione Spark per ottenere prestazioni ottimali:

Parametro TIPO Predefinito Description Example
DriverCores Integer Impostazione predefinita di Spark Numero di core CPU per il driver 4
DriverMemory String Impostazione predefinita di Spark Allocazione di memoria per il driver 4g
ExecutorCores Integer Impostazione predefinita di Spark Numero di core del processore per executor 4
ExecutorMemory String Impostazione predefinita di Spark Allocazione di memoria per executor 8g
NumExecutors Integer Impostazione predefinita di Spark Numero di executor 2

Esempio:

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

Proprietà personalizzate della sessione Spark

Qualsiasi parametro con il prefisso spark. viene applicato automaticamente alla sessione di Spark:

Configurazioni spark di esempio:

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

Motore di esecuzione nativo (NEE):

spark.nee.enabled=true

Esempio completo:

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

Configurazione del pool di connessioni HTTP

Configurare il pool di connessioni HTTP per ottenere prestazioni di rete ottimali:

Parametro TIPO Predefinito Description
HttpMaxTotalConnections Integer 100 Numero massimo di connessioni HTTP
HttpMaxConnectionsPerRoute Integer 50 Numero massimo di connessioni per percorso
HttpConnectionTimeoutInSeconds Integer 30 Timeout della connessione
HttpSocketTimeoutInSeconds Integer 60 Timeout lettura socket
HttpReadTimeoutInSeconds Integer 60 Timeout lettura HTTP
HttpConnectionRequestTimeoutSeconds Integer 30 Timeout della richiesta di connessione dal pool
HttpEnableKeepAlive Boolean true Abilitare il keep-alive HTTP
HttpKeepAliveTimeoutSeconds Integer 60 Timeout keep-alive
HttpFollowRedirects Boolean true Seguire i reindirizzamenti HTTP
HttpUseAsyncIO Boolean false Usare l'I/O HTTP asincrono

Esempio:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Configurazione proxy

Configurare le impostazioni proxy HTTP e SOCKS per gli ambienti aziendali:

Parametro TIPO Predefinito Description
UseProxy Boolean false Abilitare il proxy
ProxyTransport String http Tipo di trasporto proxy (http/tcp)
ProxyHost String None Nome host proxy
ProxyPort Integer None Porta proxy
ProxyAuthEnabled Boolean false Abilitare l'autenticazione proxy
ProxyUsername String None Nome utente autenticazione proxy
ProxyPassword String None Password di autenticazione proxy
ProxyAuthScheme String basic Schema di autenticazione (basic/digest/ntlm)
ProxySocksVersion Integer 5 Versione SOCKS (4/5)

Esempio di proxy HTTP:

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

Esempio di proxy SOCKS:

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

Configurazione del log

Parametro TIPO Predefinito Description
LogLevel String INFO Livello di registrazione: TRACCIA, DEBUG, INFO, AVVISO, ERRORE

Esempio:

LogLevel=DEBUG

Percorso log predefinito:

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

Configurazione log personalizzata: Usare un file personalizzato log4j2.xml o logback.xml nel classpath.


Esempi di utilizzo

Connessione di base

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

Esecuzione di query

Query semplice

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 con filtro

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 con limite

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

Utilizzo dei set di risultati

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

Elaborazione di set di risultati di grandi dimensioni

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
}

Uso di istruzioni preparate

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

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

Mapping dei tipi di dati

Il driver esegue il mapping dei tipi di dati Spark SQL ai tipi SQL JDBC e ai tipi Java:

Tipo SQL Spark Tipo SQL JDBC Tipo Java Note
BOOLEAN BOOLEAN Boolean
BYTE TINYINT Byte
SHORT SMALLINT Short
INT INTEGER Integer
LONG BIGINT Long
FLOAT FLOAT Float
DOUBLE DOUBLE Double
DECIMAL DECIMAL BigDecimal Precisione e scalabilità mantenute
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 Serializzato come JSON
MAP VARCHAR String Serializzato come JSON
STRUCT VARCHAR String Serializzato come JSON