Поделиться через


Драйвер Microsoft JDBC для microsoft Fabric Data Engineering (предварительная версия)

Это важно

Эта функция доступна в предварительной версии.

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.

  1. Скачайте ZIP-файл или tar из приведенных выше ссылок.
  2. Извлеките скачанный файл для доступа к JAR-файлам драйвера.
  3. Выберите 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
  4. Добавьте выбранный JAR-файл в классpath приложения.
  5. Для клиентов 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