Sterownik ODBC firmy Microsoft dla inżynierii danych usługi Microsoft Fabric (wersja zapoznawcza)

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 aplikacjami .NET, Python i innymi kompatybilnymi z ODBC oraz narzędziami BI.

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
• 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
• Wsparcie dla wieloschematowych domów nad jeziorem: Połącz się z konkretnym schematem w domku nad jeziorem
• 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

Sterownik Microsoft ODBC dla usługi Microsoft Fabric Data Engineering w wersji 1.0.0 jest w publicznej wersji zapoznawczej, który można pobrać z tego linku centrum pobierania.

• 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 MicrosoftFabricODBCDriver-1.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-1.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-1.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 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

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

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};"
)

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

Konfiguracja 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
   • 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()

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:

• TRACE: Najbardziej szczegółowy, obejmuje wszystkie wywołania interfejsu API
• DEBUG: Szczegółowe informacje o debugowaniu
• 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 na Linuksie
• Ś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