Sterownik Microsoft ODBC dla Microsoft Fabric Data Engineering

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 i narzędziami BI kompatybilnymi z ODBC.

Kluczowe funkcje

• Zgodne ze standardem ODBC 3.x: pełna implementacja specyfikacji ODBC 3.x
• Microsoft Entra ID uwierzytelnianie: Wiele przepływów uwierzytelniania, w tym Azure CLI, interaktywnych, poświadczeń klienta, uwierzytelniania opartego na certyfikatach i tokenu dostępu
• Obsługa zapytań Spark SQL: bezpośrednie wykonywanie instrukcji Spark SQL
• Kompleksowa obsługa typów danych: obsługa wszystkich typów danych Spark SQL, w tym typów złożonych (ARRAY, MAP, STRUCT)
• Ponowne użycie sesji: wbudowane zarządzanie sesjami w celu zwiększenia wydajności
• Tryb wysokiej współbieżności: Włącz współdzielone, wstępnie uruchomione sesje Livy po stronie serwera, aby zmniejszyć opóźnienie inicjowania połączenia i ograniczyć nadmierne rozrastanie się klastrów Spark
• Obsługa dużej tabeli: zoptymalizowana obsługa dużych zestawów wyników z konfigurowalnymi rozmiarami stron
• Pobieranie wstępne asynchroniczne: ładowanie danych w tle w celu zwiększenia wydajności
• Obsługa serwera proxy: konfiguracja serwera proxy HTTP dla środowisk przedsiębiorstwa
• Obsługa wielu schematów w lakehouse: Połącz się z określonym schematem w lakehouse
• Integracja z OneLake: Dostęp do danych lakehouse przechowywanych w OneLake, w tym tabel w różnych schematach, poprzez zunifikowany interfejs ODBC bez oddzielnej konfiguracji pamięci
• Wsparcie dla elementów środowiska: Podłączanie elementów środowiska Fabric podczas wykonywania zadania w celu stosowania bibliotek przestrzeni roboczych, właściwości Spark i zmiennych do wszystkich sesji
• Dostosowanie konfiguracji platformy Spark: Przekazywanie właściwości konfiguracji platformy Spark bezpośrednio za pośrednictwem parametry połączenia w celu dostosowania zachowania sesji

Wymagania wstępne

Przed rozpoczęciem korzystania ze sterownika MICROSOFT ODBC dla inżynierii danych usługi Microsoft Fabric upewnij się, że masz następujące elementy:

• System operacyjny: Windows 10/11 lub Windows Server 2016+
• Fabric Access: Dostęp do przestrzeni roboczej Fabric
• Microsoft Entra ID poświadczenia: Odpowiednie poświadczenia do uwierzytelniania
• Identyfikatory workspace i lakehouse: identyfikatory GUID dla Twojego workspace Fabric i domku nad jeziorem
• Interfejs wiersza polecenia platformy Azure (opcjonalnie): wymagany dla metody uwierzytelniania interfejsu wiersza polecenia platformy Azure

Pobieranie i instalacja MSI

• Pobierz sterownik MICROSOFT ODBC dla usługi Microsoft Fabric Data Engineering (zip)

1. Pobierz pakiet MSI sterownika ODBC Microsoft dla Microsoft Fabric Data Engineering
2. Kliknij dwukrotnie plik MicrosoftFabricODBCDriver-2.0.msi.
3. Postępuj zgodnie z instrukcjami kreatora instalacji i zaakceptuj umowę licencyjną
4. Wybierz katalog instalacyjny (ustawienie domyślne: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Ukończ instalację

Instalacja dyskretna

# Silent installation
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /l*v install.log

Weryfikowanie instalacji

Po zakończeniu instalacji sprawdź, czy sterownik jest zarejestrowany:

1. Uruchom odbcad32.exe (Administrator źródła danych ODBC)
2. Przejdź do karty Sterowniki
3. Sprawdź, czy na liście znajduje się element "Microsoft ODBC Driver for Microsoft Fabric Data Engineering".

Przykład szybkiego startu

Ten przykład pokazuje, jak połączyć się z Fabric i wykonać zapytanie za pomocą sterownika Microsoft ODBC dla Microsoft Fabric Data Engineering. Przed uruchomieniem tego kodu upewnij się, że zostały spełnione wymagania wstępne i zainstalowano sterownik.

Przykład C/C++

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

int main() {
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);
    SQLSetEnvAttr(
        environment,
        SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3,
        0);
    SQLAllocHandle(SQL_HANDLE_DBC, environment, &connection);

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

    SQLRETURN result = SQLDriverConnectA(
        connection,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);
        result = SQLExecDirectA(
            statement,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

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

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

        SQLFreeHandle(SQL_HANDLE_STMT, statement);
        SQLDisconnect(connection);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, connection);
    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Przykład języka Python

import pyodbc

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

# Connect and execute query
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 platformy .NET

using System.Data.Odbc;

// Connection string with required parameters
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 ciągu połączenia

Podstawowe parametry połączenia

Sterownik Microsoft ODBC dla inżynierii danych usługi Microsoft Fabric używa następującego 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

Połączenie podstawowe (uwierzytelnianie Azure CLI)

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

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

Z logowaniem

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

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

Zobacz sekcję High-Concurrency (HC) Mode, aby uzyskać pełne wskazówki dotyczące konfiguracji.

Authentication

Sterownik MICROSOFT ODBC dla inżynierii danych usługi Microsoft Fabric obsługuje wiele metod uwierzytelniania za pośrednictwem identyfikatora Entra firmy Microsoft (dawniej Azure Active Directory). Uwierzytelnianie jest konfigurowane przy użyciu parametru AuthFlow w parametrach połączenia.

Metody uwierzytelniania

Możesz określić wartości uwierzytelniające wielkimi literami w notacji snake_case, w notacji PascalCase lub w postaci liczbowej. Sterownik akceptuje także krótkie aliasy, takie jak Browser, Interactive, CLI, Certificate, Token, oraz File. Kierowca ignoruje podkreślenia podczas porównywania wartości.

Uwierzytelnianie CLI platformy Azure

Najlepsze dla: Tworzenie i interakcyjne aplikacje

# Python Example
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)

Prerequisites:

• Zainstalowany interfejs wiersza polecenia platformy Azure: az --version
• Zalogowano: az login

Uwierzytelnianie za pomocą przeglądarki interakcyjnej

Najlepsze dla: aplikacje przeznaczone dla użytkowników

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

Zachowanie:

• Otwiera okno przeglądarki na potrzeby uwierzytelniania użytkownika
• Poświadczenia są buforowane dla kolejnych połączeń

Uwierzytelnianie poświadczeń klienta (jednostki usługi)

Najlepsze dla: Zautomatyzowane usługi i zadania 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};"
)

Wymagane parametry

• TenantId: Identyfikator dzierżawy platformy Azure
• ClientId: Identyfikator aplikacji (klienta) z Microsoft Entra ID
• ClientSecret: Tajny klucz klienta od Microsoft Entra ID

Najlepsze praktyki

• Bezpieczne przechowywanie wpisów tajnych (azure Key Vault, zmienne środowiskowe)
• Używanie tożsamości zarządzanych, jeśli jest to możliwe
• Regularna rotacja sekretów

Uwierzytelnianie oparte na certyfikatach

Najlepsze rozwiązanie: Aplikacje dla przedsiębiorstw wymagające uwierzytelniania opartego na certyfikatach

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=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

Wymagane parametry:

• TenantId: Identyfikator dzierżawy platformy Azure
• ClientId: Identyfikator aplikacji (klienta)
• CertificatePath: Ścieżka do pliku certyfikatu PFX/PKCS12
• CertificatePassword: Hasło certyfikatu

Uwierzytelnianie tokenu dostępu

Najlepszy dla: niestandardowe scenariusze uwierzytelniania

# Acquire token through custom mechanism
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 nosiciela do dobrze znanego pliku tokenu sterownika:

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

Sterownik rozwiązuje lokalizację pliku token na Windows i Linux.

Aliasy właściwości międzysterownikowych

Sterownik ODBC akceptuje wybrane nazwy właściwości ADO.NET i JDBC oprócz natywnych nazw ODBC. Ta obsługa może ograniczyć zmiany w parametrach połączenia przy przechodzeniu między sterownikami Fabric.

Sterownik rozpoznaje 17 aliasów między sterownikami podczas nawiązywania połączenia.

Parametry konfiguracji

Wymagane parametry

Te parametry muszą być obecne 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.

Alternatywy 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 pozostawiają HC wyłączone. Aliasy on i off dotyczą tylko wartości DSN i stringów połączeń.

Ustawienia środowiska

Element środowiska Fabric można dołączyć do sesji platformy Spark uruchomionej przez sterownik. Biblioteki wybranego środowiska, właściwości platformy Spark i zmienne są automatycznie stosowane podczas tworzenia sesji.

Przykładowy ciąg połączenia ze składnikiem środowiska:

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

Niestandardowa konfiguracja platformy Spark

Właściwości konfiguracji platformy Spark można przekazać bezpośrednio w parametry połączenia. Każdy parametr poprzedzony prefiksem spark. jest automatycznie stosowany do sesji platformy Spark w czasie tworzenia, co umożliwia zastąpienie domyślnych ustawień obszaru roboczego lub środowiska uruchomieniowego.

Przykładowe konfiguracje platformy Spark:

spark.sql.shuffle.partitions=200
spark.sql.adaptive.enabled=true
spark.sql.autoBroadcastJoinThreshold=10485760

Przykładowy ciąg połączeniowy z niestandardowymi właściwościami Spark:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;spark.sql.shuffle.partitions=200;spark.sql.adaptive.enabled=true

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.

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 (uwierzytelnianie 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

HC z dostrojonymi przerwami:

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

HC z środowiskiem i nadpisaniami Spark conf:

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 (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

Możesz przechowywać ustawienia HC w DSN, zamiast powtarzać te ustawienia w każdym ciągu połączenia. 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. Aby zapisać te ustawienia, edytuj DSN w odbcad32.exe lub użyj SQLWritePrivateProfileString. 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.

Konfiguruj DSN

Utwórz systemowy DSN

1. Otwórz administratora ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Utwórz nowy DSN systemu

   • Przejdź do karty "System DSN"
   • Wybierz pozycję „Dodaj”.
   • Wybierz pozycję "Sterownik Microsoft ODBC dla Microsoft Fabric Data Engineering"
   • Wybierz pozycję "Zakończ"

3. Konfigurowanie ustawień DSN

   • Nazwa źródła danych: wprowadź unikatową nazwę (np. FabricODBC)
   • Opis: opcjonalny opis
   • Identyfikator obszaru roboczego: identyfikator GUID obszaru roboczego usługi Fabric
   • Identyfikator Lakehouse: Twój identyfikator GUID lakehouse w Fabric
   • Uwierzytelnianie: wybierz metodę uwierzytelniania
   • Identyfikator środowiska (opcjonalnie): wprowadź identyfikator GUID elementu środowiska Fabric, aby dołączyć podczas tworzenia sesji
   • Tryb Livy (opcjonalnie): Ustaw na HighConcurrency, aby włączyć tryb HC
   • Tag sesji (opcjonalnie): Wprowadź niewrażliwą etykietę operacyjną dla dopasowania sesji HC
   • Konfigurowanie dodatkowych ustawień zgodnie z potrzebami

4. Przetestuj połączenie

   • Wybierz pozycję "Testuj połączenie", aby zweryfikować ustawienia
   • Wybierz pozycję "OK", aby zapisać

Używanie DSN w aplikacjach

# Python - Connect using DSN
conn = pyodbc.connect("DSN=FabricODBC")

// .NET - Connect using DSN
using var connection = new OdbcConnection("DSN=FabricODBC");
await connection.OpenAsync();

Przykłady użycia

Podstawowe połączenie i zapytanie

Python

import pyodbc

def main():
    connection_string = (
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;"
        "ReuseSession=true;"
    )
    
    conn = pyodbc.connect(connection_string, timeout=30)
    cursor = conn.cursor()
    
    print("Connected successfully!")
    
    # Show available tables
    print("\nAvailable tables:")
    cursor.execute("SHOW TABLES")
    for row in cursor.fetchall():
        print(f"  {row}")
    
    # Query data
    print("\nQuery results:")
    cursor.execute("SELECT * FROM employees LIMIT 10")
    
    # Print column names
    columns = [desc[0] for desc in cursor.description]
    print(f"Columns: {columns}")
    
    # Print rows
    for row in cursor.fetchall():
        print(row)
    
    conn.close()

if __name__ == "__main__":
    main()

.NET

using System.Data.Odbc;

class Program
{
    static async Task Main(string[] args)
    {
        string connectionString = 
            "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
            "WorkspaceId=<workspace-id>;" +
            "LakehouseId=<lakehouse-id>;" +
            "AuthFlow=AZURE_CLI;" +
            "ReuseSession=true;";

        using var connection = new OdbcConnection(connectionString);
        await connection.OpenAsync();
        
        Console.WriteLine("Connected successfully!");

        // Show available tables
        Console.WriteLine("\nAvailable tables:");
        using (var cmd = new OdbcCommand("SHOW TABLES", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine($"  {reader.GetString(0)}");
            }
        }

        // Query data
        Console.WriteLine("\nQuery results:");
        using (var cmd = new OdbcCommand("SELECT * FROM employees LIMIT 10", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            // Print column names
            var columns = new List<string>();
            for (int i = 0; i < reader.FieldCount; i++)
            {
                columns.Add(reader.GetName(i));
            }
            Console.WriteLine($"Columns: {string.Join(", ", columns)}");

            // Print rows
            while (await reader.ReadAsync())
            {
                var values = new object[reader.FieldCount];
                reader.GetValues(values);
                Console.WriteLine(string.Join("\t", values));
            }
        }
    }
}

Praca z dużymi zestawami 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;"  # 18 MB pages
    "EnableAsyncPrefetch=1;"
)

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

# Execute large query
cursor.execute("SELECT * FROM large_table")

# Process in batches
row_count = 0
while True:
    rows = cursor.fetchmany(1000)  # Fetch 1000 rows at a time
    if not rows:
        break
    
    for row in rows:
        # Process row
        row_count += 1
        
    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

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

Wykonuj instrukcje DML

bool executeDml(SQLHDBC connection, const char* sql, const char* description) {
    SQLHSTMT statement = SQL_NULL_HSTMT;
    SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);

    std::cout << "Executing: " << description << std::endl;
    SQLRETURN result = SQLExecDirectA(
        statement,
        (SQLCHAR*)sql,
        SQL_NTS);

    bool succeeded = SQL_SUCCEEDED(result);
    if (succeeded) {
        SQLLEN rowCount;
        SQLRowCount(statement, &rowCount);
        std::cout << "Rows affected: " << rowCount << std::endl;
    }

    SQLFreeHandle(SQL_HANDLE_STMT, statement);
    return succeeded;
}

Użyj executeDml z instrukcjami INSERT, UPDATE lub DELETE. Zgłoszona liczba wierszy zależy od tego, czy wynik zawiera aktualizację rozpoznaną przez sterownik.

Odnajdywanie schematów

import pyodbc

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

# List all tables
print("Tables in current default schema / database:")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
for table in tables:
    print(f"  {table}")

# Describe table structure
print("\nTable structure for 'employees':")
cursor.execute("DESCRIBE employees")
for col in cursor.fetchall():
    print(f"  {col}")

# List schemas (for multi-schema Lakehouses)
print("\nAvailable schemas:")
cursor.execute("SHOW SCHEMAS")
for db in cursor.fetchall():
    print(f"  {db}")

conn.close()

Mapowanie typu danych

Sterownik mapuje typy danych Spark SQL na typy SQL ODBC:

Integracja narzędzia analizy biznesowej

Microsoft Excel

1. Otwieranie programu Excel — dane —>> pobieranie danych —> z innych źródeł —> od ODBC
2. Wybierz skonfigurowaną nazwę DSN (np. FabricODBC)
3. Uwierzytelnij się, jeśli zostanie wyświetlony monit
4. Przeglądaj i wybieraj tabele
5. Ładowanie danych do arkusza programu Excel

Power BI Desktop

1. Otwieranie programu Power BI Desktop —> pobieranie danych —> ODBC
2. Wybierz skonfigurowaną nazwę DSN
3. Przeglądanie wykazu danych i wybieranie tabel
4. Przekształcanie danych zgodnie z potrzebami
5. Tworzenie wizualizacji

SQL Server Management Studio (połączony serwer)

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

Rozwiązywanie problemów

Ta sekcja zawiera wskazówki dotyczące rozwiązywania typowych problemów, które mogą wystąpić podczas korzystania ze sterownika MICROSOFT ODBC dla inżynierii danych usługi Microsoft Fabric.

Typowe problemy

W poniższych sekcjach opisano typowe problemy i ich rozwiązania:

Awarie połączenia

Problem: Nie można połączyć się z Fabric

Rozwiązania:

1. Sprawdź, czy identyfikator workspace i lakehouse są poprawne
2. Sprawdź uwierzytelnianie Azure CLI: az account show
3. Upewnij się, że masz odpowiednie uprawnienia obszaru roboczego usługi Fabric
4. Sprawdzanie ustawień łączności sieciowej i serwera proxy

Błędy uwierzytelniania

Problem: Uwierzytelnianie kończy się niepowodzeniem za pomocą Azure CLI

Rozwiązania:

• Uruchom az login aby odświeżyć poświadczenia
• Sprawdź poprawnego dzierżawcę: az account set --subscription <subscription-id>
• Sprawdź ważność tokenu: az account get-access-token --resource https://api.fabric.microsoft.com

Limit czasu zapytania

Problem: Limit czasu zapytań w dużych tabelach

Rozwiązania:

• Włącz LargeTableSupport=true
• Dopasuj PageSizeBytes do optymalnego rozmiaru fragmentu
• Włącz pobieranie wstępne asynchroniczne: EnableAsyncPrefetch=1
• Użyj LIMIT klauzuli , aby ograniczyć rozmiar wyniku

Włącz rejestrowanie

Podczas rozwiązywania problemów włączenie szczegółowego rejestrowania może pomóc zidentyfikować główną przyczynę problemów. Rejestrowanie można włączyć za pomocą parametrów połączenia.

Aby włączyć szczegółowe rejestrowanie:

LogLevel=DEBUG;LogFile=C:\temp\odbc_driver_debug.log;

Poziomy logów:

• DEBUG: Szczegółowe informacje o debugowaniu oraz najbardziej rozbudowany poziom dziennika sterowników
• INFO: Ogólne informacje (ustawienie domyślne)
• WARN: Tylko ostrzeżenia
• ERROR: Tylko błędy

Śledzenie ODBC

W przypadku diagnostyki niskiego poziomu można włączyć śledzenie ODBC systemu Windows w celu przechwytywania szczegółowych wywołań interfejsu API ODBC i zachowania sterownika. Pamiętaj, aby wyłączyć śledzenie, gdy nie jest to konieczne, aby zachować optymalną wydajność.

Aby włączyć funkcję śledzenia ODBC:

1. Otwórz odbcad32.exe
2. Przejdź do karty "Śledzenie"
3. Ustaw ścieżkę pliku śledzenia (np. C:\temp\odbctrace.log)
4. Wybierz pozycję "Rozpocznij śledzenie teraz"
5. Zreplikuj problem
6. Wybierz pozycję "Zatrzymaj śledzenie teraz"

Treści powiązane

• Microsoft ODBC Driver for Microsoft Fabric Data Engineering w systemie Linux
• Ś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