Bemærk
Adgang til denne side kræver godkendelse. Du kan prøve at logge på eller ændre mapper.
Adgang til denne side kræver godkendelse. Du kan prøve at ændre mapper.
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.
- Download Microsoft JDBC Driver for Microsoft Fabric Data Engineering (zip)
- Download Microsoft JDBC Driver til Microsoft Fabric Data Engineering (tar)
- Download enten zip- eller tar-filen fra linkene ovenfor.
- Udpak den downloadede fil for at få adgang til driverens JAR-filer.
- 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
- For Java 11:
- Tilføj den valgte JAR-fil til din applikations classpath.
- 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
Navigering af 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 |