Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Это важно
Эта функция доступна в предварительной версии.
JDBC (Подключение к базе данных Java) — это широко используемый стандарт, который позволяет клиентским приложениям подключаться к данным и работать с данными из баз данных и платформ больших данных.
Microsoft JDBC Driver for Fabric Data Engineering позволяет подключать, запрашивать рабочие нагрузки Spark и управлять ими в Microsoft Fabric с надежностью и простотой стандарта JDBC. Драйвер, основанный на API Livy в Microsoft Fabric, обеспечивает безопасное и гибкое подключение Spark SQL к вашим Java-приложениям и инструментам бизнес-аналитики (BI). Эта интеграция позволяет отправлять и выполнять код Spark напрямую, без необходимости создавать отдельные артефакты блокнота или задания Spark.
Ключевые функции
- Соответствие JDBC 4.2: полная реализация спецификации JDBC 4.2
- Проверка подлинности идентификатора Microsoft Entra: несколько потоков проверки подлинности, включая интерактивные, учетные данные клиента и проверку подлинности на основе сертификатов
- Пул подключений для предприятия: встроенная система управления подключениями с мониторингом состояния и автоматическим восстановлением
- Поддержка собственных запросов Spark SQL: прямое выполнение инструкций Spark SQL без перевода
- Полная поддержка типов данных: поддержка всех типов данных Spark SQL, включая сложные типы (ARRAY, MAP, STRUCT)
- Асинхронное предварительное получение набора результатов: загрузка данных в фоновом режиме для повышения производительности
- Шаблон разбиения цепи: защита от каскадных сбоев с помощью автоматической повторных попыток
- Автоматическое повторное подключение: прозрачное восстановление сеансов при сбоях подключения
- Поддержка прокси-сервера: конфигурация прокси-сервера HTTP и SOCKS для корпоративных сред
Предпосылки
Прежде чем использовать драйвер Microsoft JDBC для microsoft Fabric Data Engineering, убедитесь, что вы:
- Пакет средств разработки Java (JDK): версия 11 или более поздняя (рекомендуется java 21)
- Microsoft Fabric Access: доступ к рабочей области Microsoft Fabric
- Учетные данные Azure Entra ID: подходящие учетные данные для аутентификации
- Идентификаторы рабочей области и Lakehouse: идентификаторы GUID для рабочей области Fabric и Lakehouse
Скачивание и установка
Microsoft JDBC Driver for Microsoft Fabric Data Engineering версии 1.0.0 — это общедоступная предварительная версия и поддерживает Java 11, 17 и 21. Мы постоянно обновляем поддержку подключения Java и рекомендуем работать с последней версией драйвера Microsoft JDBC.
- Скачайте драйвер Microsoft JDBC для microsoft Fabric Data Engineering (zip)
- Скачайте драйвер Microsoft JDBC для microsoft Fabric Data Engineering (tar)
- Скачайте ZIP-файл или tar из приведенных выше ссылок.
- Извлеките скачанный файл для доступа к JAR-файлам драйвера.
- Выберите JAR-файл, соответствующий версии JRE:
- Для Java 11:
ms-sparksql-jdbc-1.0.0.jre11.jar - Для Java 17:
ms-sparksql-jdbc-1.0.0.jre17.jar - Для Java 21:
ms-sparksql-jdbc-1.0.0.jre21.jar
- Для Java 11:
- Добавьте выбранный JAR-файл в классpath приложения.
- Для клиентов JDBC настройте класс драйвера JDBC:
com.microsoft.spark.livy.jdbc.LivyDriver
Пример быстрого запуска
В этом примере показано, как подключиться к Microsoft Fabric и выполнить запрос с помощью microsoft JDBC Driver for Microsoft Fabric Data Engineering. Перед выполнением этого кода убедитесь, что вы выполнили предварительные требования и установили драйвер.
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();
}
}
}
Формат строки подключения
Базовая строка подключения
Драйвер Microsoft JDBC для microsoft Fabric Data Engineering использует следующий формат строки подключения:
jdbc:fabricspark://<hostname>[:<port>][;<parameter1>=<value1>;<parameter2>=<value2>;...]
Компоненты строки подключения
| Компонент | Description | Example |
|---|---|---|
| Протокол | Идентификатор протокола URL-адреса JDBC | jdbc:fabricspark:// |
| Имя узла | Имя узла конечной точки Microsoft Fabric | api.fabric.microsoft.com |
| Port | Необязательный номер порта (по умолчанию: 443) | :443 |
| Параметры | Пары "Ключ=значение", разделенные точкой с запятой | FabricWorkspaceID=<guid> |
Примеры строк подключения
Базовое подключение (интерактивная проверка подлинности на основе браузера)
jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=1
С использованием конфигурации ресурсов 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
С помощью свойств сеанса 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 для Microsoft Fabric Data Engineering поддерживает несколько методов проверки подлинности с помощью идентификатора Microsoft Entra (ранее — Azure Active Directory). Проверка подлинности настраивается с помощью AuthFlow параметра в строке подключения.
Потоки аутентификации
| AuthFlow | Метод проверки подлинности | Вариант использования |
|---|---|---|
| 1 | Интерактивный браузер | Интерактивная проверка подлинности пользователей с помощью OAuth 2.0 |
| 2 | Azure CLI (Интерфейс командной строки для Azure) | Разработка с помощью Azure CLI |
| 3 | Учетные данные секрета клиента (субъект-служба) | Автоматическая аутентификация между сервисами |
| 4 | Учетные данные сертификата клиентского доступа | Проверка подлинности субъекта-службы на основе сертификатов |
| 5 | Маркер доступа | Предварительно приобретенный токен доступа владельца |
Интерактивная проверка подлинности браузера
Наиболее подходит для: разработки и интерактивных приложений
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);
Параметры:
-
AuthFlow=1: указывает интерактивную проверку подлинности браузера -
AuthTenantID(необязательно): идентификатор клиента Azure -
AuthClientID(необязательно): идентификатор приложения (клиента)
Поведение:
- Открывает окно браузера для проверки подлинности пользователя
- Учетные данные кэшируются для последующих подключений до истечения срока его действия.
- Подходит для однопользовательских приложений
Учетные данные клиента или проверка подлинности сервисного принципала
Идеально для: автоматизированных служб и фоновых задач
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);
Обязательные параметры:
-
AuthFlow=3: указывает проверку подлинности учетных данных клиента -
AuthClientID: идентификатор приложения (клиента) из Microsoft Entra ID -
AuthClientSecret: секрет клиента из идентификатора Microsoft Entra -
AuthTenantID: идентификатор клиента Azure
Рекомендации:
- Безопасное хранение секретов (Azure Key Vault, переменные среды)
- По возможности используйте управляемые удостоверения
- Регулярно поворачивать секреты
Аутентификация на базе сертификатов
Лучше всего: корпоративные приложения, требующие проверки подлинности на основе сертификатов
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);
Обязательные параметры:
-
AuthFlow=4: указывает проверку подлинности на основе сертификатов -
AuthClientID: идентификатор приложения (клиента) -
AuthCertificatePath: Путь к файлу сертификата PFX/PKCS12 -
AuthCertificatePassword: пароль сертификата -
AuthTenantID: идентификатор клиента Azure
Аутентификация токена доступа
Лучше всего подходит для: пользовательских сценариев проверки подлинности
// 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);
Кэширование проверки подлинности
Драйвер автоматически кэширует маркеры проверки подлинности для повышения производительности:
// 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);
Параметры конфигурации
Обязательные параметры
Эти параметры должны присутствовать в каждой строке подключения:
| Параметр | Тип | Description | Example |
|---|---|---|---|
FabricWorkspaceID |
UUID (Универсальный уникальный идентификатор) | Идентификатор рабочей области Microsoft Fabric | <workspace-id> |
FabricLakehouseID |
UUID (Универсальный уникальный идентификатор) | Идентификатор Microsoft Fabric lakehouse | <lakehouse-id> |
AuthFlow |
Целое число | Тип потока проверки подлинности (1–5) | 2 |
Необязательные параметры
Конфигурация версии API
| Параметр | Тип | По умолчанию | Description |
|---|---|---|---|
FabricVersion |
String | v1 |
Версия API Microsoft Fabric |
LivyApiVersion |
String | 2023-12-01 |
Версия API Livy |
Конфигурация среды
| Параметр | Тип | По умолчанию | Description |
|---|---|---|---|
FabricEnvironmentID |
UUID (Универсальный уникальный идентификатор) | None | Идентификатор среды Fabric для ссылки на элемент среды для сеанса Spark |
Конфигурация Spark
Конфигурация ресурса сеанса
Настройте ресурсы сеанса Spark для оптимальной производительности:
| Параметр | Тип | По умолчанию | Description | Example |
|---|---|---|---|---|
DriverCores |
Целое число | По умолчанию Spark | Число ядер ЦП для драйвера | 4 |
DriverMemory |
String | По умолчанию Spark | Выделение памяти для драйвера | 4g |
ExecutorCores |
Целое число | По умолчанию Spark | Количество ядер ЦП на исполнителя | 4 |
ExecutorMemory |
String | По умолчанию Spark | Выделение памяти для каждого исполнителя | 8g |
NumExecutors |
Целое число | По умолчанию Spark | Количество исполнителей | 2 |
Example:
DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2
Настраиваемые свойства сеанса Spark
Любой параметр с префиксом spark. автоматически применяется к сеансу Spark:
Примеры конфигураций Spark:
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
Нативный исполнительный движок (NEE):
spark.nee.enabled=true
Полный пример:
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
Настройте пул подключений HTTP для оптимальной производительности сети:
| Параметр | Тип | По умолчанию | Description |
|---|---|---|---|
HttpMaxTotalConnections |
Целое число | 100 | Максимальное общее количество HTTP-подключений |
HttpMaxConnectionsPerRoute |
Целое число | 50 | Максимальное количество подключений на маршрут |
HttpConnectionTimeoutInSeconds |
Целое число | 30 | Время соединения истекло |
HttpSocketTimeoutInSeconds |
Целое число | 60 | Время ожидания чтения сокета |
HttpReadTimeoutInSeconds |
Целое число | 60 | Время ожидания чтения HTTP |
HttpConnectionRequestTimeoutSeconds |
Целое число | 30 | Время ожидания запроса подключения из пула |
HttpEnableKeepAlive |
Boolean | true | Включить удержание соединения HTTP активным |
HttpKeepAliveTimeoutSeconds |
Целое число | 60 | Время ожидания в режиме поддержания активности |
HttpFollowRedirects |
Boolean | true | Следуйте перенаправлениям HTTP |
HttpUseAsyncIO |
Boolean | false | Использование асинхронного ввода-вывода HTTP |
Example:
HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60
Конфигурация прокси-сервера
Настройте параметры прокси-сервера HTTP и SOCKS для корпоративных сред:
| Параметр | Тип | По умолчанию | Description |
|---|---|---|---|
UseProxy |
Boolean | false | Включение прокси-сервера |
ProxyTransport |
String | http |
Тип транспорта прокси-сервера (http/tcp) |
ProxyHost |
String | None | Имя узла прокси-сервера |
ProxyPort |
Целое число | None | Порт прокси-сервера |
ProxyAuthEnabled |
Boolean | false | Включение проверки подлинности прокси-сервера |
ProxyUsername |
String | None | Имя пользователя аутентификации прокси-сервера |
ProxyPassword |
String | None | Пароль проверки подлинности прокси-сервера |
ProxyAuthScheme |
String | basic |
Схема проверки подлинности (basic/digest/ntlm) |
ProxySocksVersion |
Целое число | 5 | Версия SOCKS (4/5) |
Пример прокси-сервера HTTP:
UseProxy=true;ProxyTransport=http;ProxyHost=proxy.company.com;ProxyPort=8080;ProxyAuthEnabled=true;ProxyUsername=user;ProxyPassword=pass
Пример прокси-сервера SOCKS:
UseProxy=true;ProxyTransport=tcp;ProxyHost=socks.company.com;ProxyPort=1080;ProxySocksVersion=5
Конфигурация ведения журнала
| Параметр | Тип | По умолчанию | Description |
|---|---|---|---|
LogLevel |
String | INFO |
Уровень ведения журнала: ТРАССИРОВКА (TRACE), ОТЛАДКА (DEBUG), ИНФОРМАЦИЯ (INFO), ПРЕДУПРЕЖДЕНИЕ (WARN), ОШИБКА (ERROR) |
Example:
LogLevel=DEBUG
Расположение журнала по умолчанию:
${user.home}/.microsoft/livy-jdbc-driver/driver.log
Настраиваемая конфигурация журнала: Используйте файл log4j2.xml или logback.xml на вашем classpath.
Примеры использования
Базовое подключение
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();
}
}
}
Выполнение запросов
Простой запрос
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);
}
}
}
Запрос с фильтром
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);
}
}
}
Запрос с ограничением
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();
}
}
}
Работа с результирующими наборами
Навигация по результирующих наборам
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"));
}
}
}
Обработка больших результирующих наборов
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
}
Использование подготовленных инструкций
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);
}
}
}
}
Пакетные операции
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);
}
}
Сопоставление типов данных
Драйвер сопоставляет типы данных Spark SQL с типами SQL JDBC и типами Java:
| Тип SQL Spark | Тип SQL JDBC | Тип Java | Примечания. |
|---|---|---|---|
BOOLEAN |
BOOLEAN |
Boolean |
|
BYTE |
TINYINT |
Byte |
|
SHORT |
SMALLINT |
Short |
|
INT |
INTEGER |
Integer |
|
LONG |
BIGINT |
Long |
|
FLOAT |
FLOAT |
Float |
|
DOUBLE |
DOUBLE |
Double |
|
DECIMAL |
DECIMAL |
BigDecimal |
Точность и масштабирование сохранены |
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 |
Сериализовано как JSON |
MAP |
VARCHAR |
String |
Сериализовано как JSON |
STRUCT |
VARCHAR |
String |
Сериализовано как JSON |