Sterownik Microsoft ODBC dla Microsoft Fabric Data Engineering na Linuksie

ODBC (Open Database Connectivity) to powszechnie przyjęty standard, który umożliwia aplikacjom klienckim łączenie się z bazami danych i platformami danych big data oraz pracę z nimi.

Sterownik Microsoft ODBC dla Fabric Data Engineering pozwala podłączać, zapytywać i zarządzać obciążeniami Spark w Fabric z niezawodnością i prostotą standardu ODBC. Oparty na API Livy firmy Fabric, sterownik zapewnia bezpieczną i elastyczną łączność Spark SQL z C/C++, .NET, Python oraz innymi aplikacjami kompatybilnymi z ODBC na Linuksie.

Kluczowe funkcje

• Zgodność z ODBC 3.x: Pełna implementacja specyfikacji ODBC 3.x.
• Uwierzytelnianie Microsoft Entra ID: Wiele przepływów uwierzytelniania, w tym Azure CLI, dane klienta, uwierzytelnianie oparte na certyfikatach oraz uwierzytelnianie za pomocą tokenów dostępu.
• Wsparcie zapytań SQL w Spark: Bezpośrednie wykonywanie instrukcji SQL Spark.
• Kompleksowe wsparcie typów danych: Obsługa wszystkich typów danych SQL Spark, w tym typów złożonych (ARRAY, MAP, i STRUCT).
• Ponowne wykorzystanie sesji: Wbudowane zarządzanie sesjami dla lepszej wydajności.
• Tryb wysokiej współbieżności: Włącz współdzielone, utrzymywane w gotowości sesje Livy po stronie serwera, aby zmniejszyć opóźnienia przy nawiązywaniu połączenia i ograniczyć nadmierne rozrastanie się klastrów Spark.
• Obsługa dużych tabel: Optymalizacja obsługi dużych zestawów wyników z konfigurowalnymi rozmiarami stron.
• Async prefetch: Ładowanie danych w tle dla lepszej wydajności.
• Wsparcie proxy: konfiguracja proxy HTTP dla środowisk korporacyjnych.
• Wsparcie dla wieloschematowych domów nad jeziorem: Połącz się z konkretnym schematem w domku nad jeziorem.

Wymagania wstępne

Zanim użyjesz sterownika Microsoft ODBC dla Microsoft Fabric Data Engineering na Linuksie, upewnij się, że masz następujące wymagania wstępne:

• System operacyjny: Ubuntu 22.04 lub nowszy, Debian 11 lub nowszy, albo Red Hat Enterprise Linux (RHEL) 8 lub nowszy na x86-64.
• unixODBC: Menedżer sterowników ODBC dla Linuksa. Zainstaluj pakiety unixodbc i unixodbc-dev.
• libcurl: Zależność w środowisku uruchomieniowym HTTP, taka jak libcurl4 lub odpowiednik pakietu dla Twojej dystrybucji.
• OpenSSL: Zależność środowiska uruchomieniowego dla TLS i kryptografii, taka jak pakiety openssl i libssl3 lub ich odpowiedniki.
• Fabric access: Dostęp do przestrzeni roboczej Fabric.
• Poświadczenia usługi Microsoft Entra ID: Poświadczenia odpowiednie do uwierzytelniania.
• Identyfikatory przestrzeni roboczej i domów nad jeziorem: identyfikatory GUID dla twojej przestrzeni roboczej Fabric i domku nad jeziorem.
• Azure CLI (opcjonalnie): Wymagane przy użyciu uwierzytelniania Azure CLI.

Pobierz i zainstaluj na Linuksie

• Pobierz sterownik Microsoft ODBC dla Microsoft Fabric Data Engineering na Linuksie (tar)

Aby zainstalować sterownik:

1. Wyodrębnij ms-sparksql-odbc-linux-2.0.0.tar.

2. Otwórz terminal w rozpakowanym katalogu.

3. Zainstaluj pakiet Debian:

   sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb
   

Pakiet instaluje następujące pliki:

Zainstaluj pakiet RPM

Na RHEL, Fedora lub CentOS zainstaluj pakiet RPM z rozpakowanego archiwum sterowników:

sudo dnf install ./microsoft-fabric-odbc-driver-*.x86_64.rpm

Alternatywnie, użyj rpm:

sudo rpm -i microsoft-fabric-odbc-driver-*.x86_64.rpm

Sprawdź, czy RPM zarejestrował sterownik:

odbcinst -q -d | grep "Microsoft"

Aby odinstalować pakiet RPM, wykonaj:

sudo dnf remove microsoft-fabric-odbc-driver

Zainstaluj tarball

Dla dystrybucji bez wsparcia dla pakietów Debian lub RPM, albo dla niestandardowej lokalizacji instalacji, rozpakuj .tar.gz pakiet i uruchom jego skrypt instalacyjny:

tar -xzf microsoft-fabric-odbc-driver-2.0.0-linux-x86_64.tar.gz
cd microsoft-fabric-odbc-driver-2.0.0

# Install to /opt/microsoft/fabricodbc.
sudo ./install.sh

# Or install to a custom writable location.
./install.sh --prefix=$HOME/fabricodbc

Skrypt instalacyjny obsługuje następujące opcje:

Aby zweryfikować domyślną instalację tarballa, uruchom następująco:

odbcinst -q -d
ls -la /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so

Aby ją odinstalować, uruchom sudo ./install.sh --uninstall z katalogu rozpakowanego pakietu.

Rejestruj sterownik ręcznie

Pakiet automatycznie rejestruje sterownik w unixODBC. Aby zarejestrować sterownika ręcznie, wykonaj:

sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template

Weryfikowanie instalacji

Sprawdź, czy sterownik jest zarejestrowany i że biblioteka jest zainstalowana:

odbcinst -q -d
ls -la /usr/lib/libmicrosoftfabricodbc.so

Polecenie odbcinst powinno wyświetlać [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Odinstaluj sterownik

Aby odinstalować sterownik, wykonaj następujące polecenie:

sudo dpkg -r microsoft-fabric-odbc-driver

To polecenie usuwa pliki sterownika i wyrejestrowuje sterownik z unixODBC.

Przykład szybkiego startu

Poniższe przykłady łączą się z Fabric i uruchamiają zapytanie SQL w Spark. Wypełnij wymagania wstępne i zainstaluj sterownik, zanim uruchomisz przykład.

Przykład języka Python

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

conn = pyodbc.connect(connection_string, timeout=30)
cursor = conn.cursor()

cursor.execute("SELECT 'Hello from Fabric!' AS message")
row = cursor.fetchone()
print(row.message)

conn.close()

Przykład C/C++

#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV henv = SQL_NULL_HENV;
    SQLHDBC hdbc = SQL_NULL_HDBC;
    SQLHSTMT hstmt = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

    const char* connectionString =
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;";

    SQLRETURN result = SQLDriverConnect(
        hdbc,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        std::cout << "Connected successfully!" << std::endl;

        SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        result = SQLExecDirect(
            hstmt,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(hstmt) == SQL_SUCCESS) {
                SQLGetData(
                    hstmt,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
        SQLDisconnect(hdbc);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return 0;
}

Zbuduj i uruchom przykład:

g++ -o fabric_test fabric_test.cpp -lodbc -std=c++17
./fabric_test

Przykład platformy .NET

using System.Data.Odbc;

string connectionString =
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand(
    "SELECT 'Hello from Fabric!' AS message",
    connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Format łańcucha połączenia

Podstawowe parametry połączenia

Użyj poniższego formatu parametrów połączenia:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};<parameter1>=<value1>;<parameter2>=<value2>;...

Składniki parametrów połączenia

Przykładowe parametry połączenia

Podstawowe połączenie

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI

Powiązanie z opcjami wydajności

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;ReuseSession=true;LargeTableSupport=true;PageSizeBytes=18874368

Powiązanie z logowaniem

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=/tmp/odbc_driver.log

Połączenie w trybie wysokiej współbieżności

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Pełne wskazówki dotyczące konfiguracji można znaleźć w trybie High-Concurrency (HC).

Uwierzytelnianie

Sterownik Microsoft ODBC dla Microsoft Fabric Data Engineering obsługuje wiele metod uwierzytelniania poprzez Microsoft Entra ID. Konfiguruj uwierzytelnianie, używając parametru AuthFlow w parametry połączenia lub DSN.

Metody uwierzytelniania

Uwierzytelnianie CLI platformy Azure

Używaj uwierzytelniania Azure CLI do tworzenia i aplikacji interaktywnych.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Przed połączeniem sprawdź, czy Azure CLI jest zainstalowany i zaloguj się:

az --version
az login

Aby zainstalować Azure CLI na Debianie lub Ubuntu, użyj menedżera pakietów:

sudo apt-get update
sudo apt-get install -y azure-cli

Uwierzytelnianie danych klienta

Używaj uwierzytelniania klienta do automatycznych usług i zadań w tle.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CREDENTIAL;"
    f"TenantId={tenant_id};"
    f"ClientId={client_id};"
    f"ClientSecret={client_secret};"
)

Podaj następujące parametry:

• TenantId: ID tenanta Microsoft Entra.
• ClientId: identyfikator aplikacji (klienta).
• ClientSecret: Sekret klienta.

Przechowuj wpisy tajne w bezpiecznym magazynie lub w zmiennych środowiskowych. Nie przechowuj sekretów w tekstowych łańcuchach połączeń ani plikach INI.

Uwierzytelnianie oparte na certyfikatach

Używaj uwierzytelniania opartego na certyfikatach dla aplikacji korporacyjnych wymagających certyfikatów uwierzytelniających.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CERTIFICATE;"
    "TenantId=<tenant-id>;"
    "ClientId=<client-id>;"
    "CertificatePath=/path/to/cert.pfx;"
    "CertificatePassword=<password>;"
)

Podaj następujące parametry:

• TenantId: ID tenanta Microsoft Entra.
• ClientId: identyfikator aplikacji (klienta).
• CertificatePath: Ścieżka do pliku certyfikatu PFX lub PKCS12.
• CertificatePassword: Hasło do certyfikatu.

Uwierzytelnianie tokenu dostępu

Używaj uwierzytelniania za pomocą tokena dostępu, gdy Twoja aplikacja pozyskuje token za pomocą innego mechanizmu.

access_token = acquire_token_from_custom_source()

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=ACCESS_TOKEN;"
    f"AccessToken={access_token};"
)

Uwierzytelnianie tokenów plików

Używaj uwierzytelniania tokenów plików w środowiskach konteneryzowanych i zautomatyzowanych potokach, gdzie inny proces zapisuje token nośnika do dobrze znanego pliku token sterownika:

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

Aby zapoznać się z obsługiwanymi aliasami właściwości między sterownikami, zobacz Aliasy właściwości między sterownikami.

Parametry konfiguracji

Wymagane parametry

Uwzględnij te parametry w każdym ciągu połączenia:

Parametry opcjonalne

Ustawienia połączenia

Ustawienia wydajności

Ustawienia rejestrowania

Ustawienia serwera proxy

Ustawienia wysokiej współbieżności (HC)

Użyj tych parametrów, aby włączyć i skonfigurować tryb wysokiej współbieżności (HC). Tryb HC wymaga włączenia. Jeśli nie ustawisz LivyMode lub UseHighConcurrency, sterownik używa klasycznej ścieżki pojedynczej sesji. Wskazówki i przykłady można znaleźć w trybie wysokiej współbieżności (HC).

Precedens i walidacja trybu

• LivyMode ma priorytet nad UseHighConcurrency, gdy ustawisz oba parametry.
• Wartości parametrów nie są zależne od wielkości liter.
• UseHighConcurrency akceptuje true, 1, yes, lub on do włączenia trybu HC. Akceptuje false, 0, no lub off, aby wyłączyć tryb HC.
• Dla innych wartości niepustych zwraca SQLDriverConnect błąd. Tylko SQLConnect DSN rejestruje niepowodzenie walidacji i korzysta z klasycznej ścieżki.

Ustawienia zgodności

Sterownik akceptuje TenantPrincipal i PoolMax, łącznie z ich odpowiednikami w postaci zmiennych środowiskowych, aby zachować zgodność z wcześniejszymi konfiguracjami HC. Sterownik analizuje i weryfikuje te wartości, ale nie wpływają one na dopasowanie sesji HC ani pojemność puli w czasie rzeczywistym. Nie polegaj na nich w kwestii izolacji najemcy ani limitów łączności.

Zmiany zmienne środowiskowe

Sterownik używa następujących zmiennych środowiskowych tylko wtedy, gdy odpowiadający mu parametr DSN lub string połączenia nie jest ustawiony:

Dla FABRIC_ODBC_USE_HC włączanie wyłącznie za pomocą zmiennych środowiskowych rozpoznaje true, 1 i yes (bez rozróżniania wielkości liter). Inne wartości wyłączają tryb HC. Aliasy on i off dotyczą tylko wartości DSN i stringów połączeń.

Tryb wysokiej współbieżności (HC)

Tryb wysokiej współbieżności (HC) umożliwia połączeniom ODBC z tym samym obszarem roboczym i usługą Lakehouse dołączanie do współdzielonych, już uruchomionych sesji Livy Spark po stronie serwera zamiast inicjowania osobnego klastra dla każdego połączenia. Używaj tego rozwiązania do obciążeń, takich jak pulpity nawigacyjne BI, jądra notebooków i rozgałęzianie ETL, które otwierają wiele krótkotrwałych połączeń i mogą współdzielić zarządzane przez serwer zasoby Spark.

Tryb HC wymaga włączenia. Jeśli nie skonfigurujesz konfiguracji HC, sterownik używa klasycznej ścieżki dla pojedynczej sesji.

Wybieranie trybu połączenia

Używaj trybu HC, gdy:

• Twoje obciążenie otwiera wiele krótkotrwałych połączeń ODBC, takich jak dashboardy BI, jądra notebooków czy ETL fan-out.
• Połączenia celują w tę samą przestrzeń roboczą i domek nad jeziorem i mogą współdzielić sesję Spark zarządzaną przez serwer.
• Zmniejszenie opóźnienia zimnego startu dla każdego połączenia jest ważne.

Użyj trybu klasycznego, gdy:

• Każde połączenie wymaga izolowanej sesji Spark ze względu na różne konfiguracje Spark lub ścisłą izolację zasobów.
• Punkt końcowy usługi Fabric Livy dla docelowego obszaru roboczego i lakehouse nie obsługuje trybu HC.

Włącz tryb wysokiej współbieżności

Dodaj parametr trybu wysokiej współbieżności do DSN lub ciągu połączenia.

Zalecane: Zestaw LivyMode

Użyj LivyMode, aby jawnie wybrać tryb pozyskiwania sesji:

LivyMode=HighConcurrency

Obsługiwane wartości to Classic, HighConcurrencyi Auto. Wielkość liter nie ma znaczenia dla wartości. Auto Obecnie wybiera tryb klasyczny.

Alternatywa: Ustaw UseHighConcurrency

Użyj ustawienia Boole'a dla kompatybilności z istniejącymi konfiguracjami:

UseHighConcurrency=true

Aby włączyć tryb o wysokiej równoczesności, użyj true, 1, yes, lub on. Aby ją wyłączyć, użyj false, 0, no, lub off. Wielkość liter nie ma znaczenia dla wartości. SQLDriverConnect odrzuca inne wartości niepuste za pomocą SQLSTATE HY024. Tylko SQLConnect DSN rejestruje błąd walidacji i używa trybu klasycznego.

Możesz także włączyć tryb wysokiej równobieżności dla obecnej powłoki, używając zmiennych środowiskowych:

export FABRIC_ODBC_USE_HC=true
export FABRIC_ODBC_WORKSPACE_ID=<workspace-id>
export FABRIC_ODBC_LAKEHOUSE_ID=<lakehouse-id>
export FABRIC_ODBC_SESSION_TAG=bi-dashboard

Wymagane parametry w trybie HC

Aktywacja HC wymaga następujących ważnych identyfikatorów:

Uwzględnij, SessionTag ponieważ wpływa to na dopasowanie po stronie serwera dla sesji ciepłych.

Dopasowywanie sesji

Tryb HC nie gwarantuje, że każde połączenie ponownie wykorzystuje istniejącą sesję. Dla każdego żądania pozyskania sesji sterownik wysyła:

• Wartość SessionTag.
• Rzeczywista konfiguracja platformy Spark, w tym ustawienia conf.* i EnvironmentId.

Usługa Fabric Livy ocenia te wartości i decyduje, czy przypisać połączenie do aktywnej sesji, czy utworzyć nową sesję. Aby poprawić ponowne wykorzystanie sesji, używaj spójnych wartości między połączeniami, które mają współdzielić przepustowość Sparka zarządzanego przez serwer.

Przykładowe parametry połączenia

Minimalne połączenie HC z uwierzytelnianiem Azure CLI:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Połączenie HC z dostrojonymi timeoutami:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

Połączenie HC ze środowiskiem i nadpisywanie konfiguracji Spark:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python z pyodbc:

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

Konfiguruj tryb HC w DSN Linuksa

Zamiast powtarzać ustawienia HC w każdym ciągu połączenia, zapisz je w ~/.odbc.ini dla DSN specyficznego dla użytkownika lub w /etc/odbc.ini dla DSN systemowego.

[FabricHCDSN]
Description               = Microsoft Fabric Data Engineering with HC mode
Driver                    = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId               = <workspace-id>
LakehouseId               = <lakehouse-id>
AuthFlow                  = AZURE_CLI
LivyMode                  = HighConcurrency
SessionTag                = bi-dashboard
AcquireTimeoutSeconds     = 300
HeartbeatTimeoutInSecond  = 600

Po zapisaniu DSN, zweryfikowaj go i przetestuj połączenie.

odbcinst -q -s
isql -k -v "DSN=FabricHCDSN;"

Gdy parametry połączenia nie określa wartości, sterownik odczytuje te ustawienia z DSN:

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

Sterownik odczytuje również ustawienia TenantPrincipal tylko do celów zgodności PoolMax. Użyj nazw parametrów w tabeli ustawień HC.

Wyłącz tryb HC

Możesz wyłączyć pozyskiwanie nowych sesji HC bez ponownego wdrażania sterownika. Użyj metody odpowiadającej temu, jak włączyłeś tryb HC:

Ustawienia parametrów połączenia i DSN mają pierwszeństwo nad mechanizmem rezerwowym opartym na zmiennej środowiskowej. Zmiany te dotyczą jedynie nowych połączeń. Istniejące sesje HC trwają do momentu ich wydania.

Zrozumienie zachowania środowiska wykonawczego HC

• Walidacja:SQLDriverConnect odrzuca nieprawidłowe wartości booleańskie HC i dodatnie całkowite za pomocą SQLSTATE HY024. Odrzuca nieprawidłowy LivyMode oraz nieprawidłowe lub zbyt duże wartości WorkspaceId, LakehouseId i IdempotencyKey, zgłaszając SQLSTATE HY000. Zbyt duża wartość kompatybilności TenantPrincipal również zwraca HY000. W przypadku samego SQLConnectDSN sterownik rejestruje standardowe błędy walidacji HC i działa w trybie klasycznym. Zbyt duże wartości wrażliwe pod względem bezpieczeństwa nadal uniemożliwiają nawiązanie połączenia.
• Dane wrażliwe: Sterownik wyklucza lub usuwa IdempotencyKey inne wrażliwe pola z logów HC i wyników diagnostycznych.
• Anulowanie: Anulowanie oświadczenia jest współpracą. Operacje serwera, które są już w toku, są wygaszane w kontrolowany sposób, zamiast być natychmiast przerywane.
• Wyłączniki obwodowe: Tryby HC i klasyczne wykorzystują oddzielne wyłączniki. Wyczerpanie jednego trybu nie wpływa na drugi.
• Początkowa baza danych: Połączenia HC nie wykonują początkowej USE instrukcji dla parametru Database. Uruchom USE <database> po połączeniu lub użyj w pełni kwalifikowanych nazw tabel.
• Diagnostyka: Ustaw LogLevel=DEBUG, aby rejestrować pozyskiwanie, odpytywanie i zwalnianie HC oraz decyzje dotyczące mapowania błędów. Aby zawęzić diagnostykę, ustaw LIVY_HC_VERBOSE=1 tak, aby obejmowało dodatkowe zanonimizowane dane diagnostyczne HC HTTP.

Konfiguracja DSN

Na Linuksie konfiguruj nazwy źródeł danych (DSN) w plikach INI zamiast w rejestrze Windows.

Utwórz DSN

Jeśli ~/.odbc.ini istnieje, dodaj nową sekcję DSN bez zastępowania istniejącego pliku. Skopiuj zainstalowany szablon tylko podczas tworzenia pliku:

if [ -e "$HOME/.odbc.ini" ]; then
    echo "Preserve ~/.odbc.ini and add the new DSN section manually."
else
    cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template "$HOME/.odbc.ini"
fi

Zaktualizuj ~/.odbc.ini, podając szczegóły obszaru roboczego Fabric:

[FabricDSN]
Description    = Microsoft Fabric Data Engineering
Driver         = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId    = <workspace-id>
LakehouseId    = <lakehouse-id>
AuthFlow       = AZURE_CLI
LogLevel       = INFO
# LogFile      = /tmp/fabric_odbc.log
# LargeTableSupport = true
# ReuseSession = true

Zweryfikowaj DSN

Wypisz skonfigurowane DSN, a następnie przetestuj połączenie:

odbcinst -q -s
isql -k -v "DSN=FabricDSN;"

Polecenie isql wymaga narzędzi unixODBC wiersza polecenia. Opcja -k używa SQLDriverConnect, co pozwala sterownikowi przetwarzać atrybuty połączenia DSN.

Używaj DSN w aplikacjach

conn = pyodbc.connect("DSN=FabricDSN")

using var connection = new OdbcConnection("DSN=FabricDSN");
await connection.OpenAsync();

SQLRETURN result = SQLConnect(
    hdbc,
    (SQLCHAR*)"FabricDSN",
    SQL_NTS,
    NULL,
    0,
    NULL,
    0);

Przykłady użycia

Przetestowaj połączenie z isql

Rozpocznij interaktywną sesję SQL:

isql -k -v "DSN=FabricDSN;"

Wykonaj jedno zapytanie:

echo "SELECT 1 AS test" | isql -k -v "DSN=FabricDSN;" -b

Użyj -k dla identyfikatorów DSN Fabric, aby isql łączył się za pośrednictwem SQLDriverConnect zamiast SQLConnect.

Praca z dużymi zbiorami wyników

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LargeTableSupport=true;"
    "PageSizeBytes=18874368;"
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT * FROM large_table")

row_count = 0
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break

    for row in rows:
        row_count += 1

    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

Odkryj schematy i tabele

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SHOW TABLES")
for table in cursor.fetchall():
    print(table)

cursor.execute("DESCRIBE employees")
for column in cursor.fetchall():
    print(column)

cursor.execute("SHOW SCHEMAS")
for schema in cursor.fetchall():
    print(schema)

conn.close()

Mapowanie typu danych

Sterownik mapuje typy danych Spark SQL na typy SQL ODBC:

Różnice między platformami

Rozwiązywanie problemów

Kierowca nie znaleziony

Problem: Połączenie nie działa przy [IM002] Data source name not found and no default driver specified.

Rozwiązania:

1. Sprawdź rejestrację kierowcy, uruchamiając odbcinst -q -d.
2. Sprawdź, czy to /usr/lib/libmicrosoftfabricodbc.so istnieje.
3. Zarejestruj sterownik, uruchamiając sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Przeinstaluj pakiet, uruchamiając sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Kierowca nie znaleziony po instalacji tarballa

Problem: Sterownik jest zarejestrowany, ale współdzielona biblioteka nie jest obecna na zarejestrowanej ścieżce.

Rozwiązania:

1. Sprawdź, czy to /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so istnieje.
2. Ponów sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Jeśli użyłeś niestandardowego prefiksu, sprawdź, czy zarejestrowana ścieżka sterownika używa tego samego prefiksu.

Nie znaleziono DSN

Problem: Połączenie nie działa przy [IM002] Data source name not found.

Rozwiązania:

1. Zweryfikowaj konfigurację DSN, uruchamiając odbcinst -q -s.
2. Sprawdź, czy ~/.odbc.ini lub /etc/odbc.ini zawiera sekcję DSN.
3. Upewnij się, że Driver wartość dokładnie odpowiada zarejestrowanemu nazwisku kierowcy.

Awarie połączenia

Problem: Sterownik nie może połączyć się z Fabric.

Rozwiązania:

1. Sprawdź, czy identyfikator przestrzeni roboczej i identyfikator domu nad jeziorem są ważnymi GUID-ami.
2. Sprawdź uwierzytelnianie Azure CLI poprzez uruchomienie az account show.
3. Upewnij się, że masz wymagane uprawnienia do Fabric workspace.
4. Sprawdź łączność sieciową i ustawienia proxy.

Błędy uwierzytelniania

Problem: uwierzytelnianie Azure CLI zawodzi.

Rozwiązania:

1. Uruchom az login, aby odświeżyć poświadczenia.
2. Ustaw właściwą subskrypcję, uruchamiając az account set --subscription <subscription-id>.
3. Sprawdź token, uruchamiając az account get-access-token --resource https://api.fabric.microsoft.com.
4. Upewnij się, że Twoje konto ma wymagane uprawnienia do przestrzeni roboczej Fabric.

Błędy biblioteki współdzielonej

Problem: Sterownik zgłasza error while loading shared libraries: libmicrosoftfabricodbc.so.

Rozwiązania:

1. Przeinstaluj pakiet, uruchamiając sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Sprawdź, czy to /usr/lib/libmicrosoftfabricodbc.so istnieje.
3. Uruchom sudo ldconfig, aby odświeżyć pamięć podręczną bibliotek współdzielonych.

Limity czasu zapytań

Problem: Zapytania przekraczają limit czasu w przypadku dużych tabel.

Rozwiązania:

1. Dodaj LargeTableSupport=true do parametrów połączenia.
2. Dostosuj PageSizeBytes rozmiar wyniku.
3. Dodaj EnableAsyncPrefetch=1 do parametrów połączenia.
4. Użyj klauzuli LIMIT ograniczającej rozmiar wyniku.

Włącz logowanie

Umożliwienie szczegółowego logowania w DSN:

[FabricDSN]
LogLevel = DEBUG
LogFile  = /tmp/fabric_odbc_debug.log

Alternatywnie, można dodać parametry logowania do parametry połączenia:

LogLevel=DEBUG;LogFile=/tmp/fabric_odbc_debug.log;

Sterownik obsługuje następujące poziomy logów:

• DEBUG: Zawiera szczegółowe informacje o debugowaniu i jest najbardziej rozbudowanym poziomem dziennika sterowników.
• INFO: Zawiera ogólne informacje i jest domyślna.
• WARN: Zawiera tylko ostrzeżenia.
• ERROR: Zawiera tylko błędy.

Włącz śledzenie unixODBC

Dla diagnostyki wywołań ODBC na niskim poziomie dodaj następującą konfigurację do /etc/odbcinst.ini:

[ODBC]
Trace     = yes
TraceFile = /tmp/odbc_trace.log

Wyłącz śledzenie po zakończeniu rozwiązywania problemów, aby uniknąć niepotrzebnych narzutów wydajnościowych.

Treści powiązane

• Sterownik ODBC firmy Microsoft dla inżynierii danych usługi Microsoft Fabric
• Środowiska uruchomieniowe platformy Apache Spark w Fabric
• Środowisko uruchomieniowe Fabric 1.3
• Co to jest interfejs API Livy do inżynierii danych
• Sterownik JDBC firmy Microsoft dla inżynierii danych usługi Microsoft Fabric
• unixODBC