Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.
- Scaricare Microsoft JDBC Driver per Microsoft Fabric Data Engineering (zip)
- Scaricare Microsoft JDBC Driver per Microsoft Fabric Data Engineering (tar)
- Scaricare il file ZIP o tar dai collegamenti precedenti.
- Estrarre il file scaricato per accedere ai file JAR del driver.
- 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
- Per Java 11:
- Aggiungere il file JAR selezionato al classpath dell'applicazione.
- 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
Esplorazione 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 |