Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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.
- Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering (zip) downloaden
- Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering (tar) downloaden
- Download het zip- of tar-bestand via de bovenstaande koppelingen.
- Pak het gedownloade bestand uit om toegang te krijgen tot de JAR-bestanden van het stuurprogramma.
- 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
- Voor Java 11:
- Voeg het geselecteerde JAR-bestand toe aan het klassepad van uw toepassing.
- 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
Navigeren in 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 |