Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering

ODBC (Open Database Connectivity) ist ein weit verbreiteter Standard, mit dem Clientanwendungen eine Verbindung mit Daten aus Datenbanken und Big Data-Plattformen herstellen und damit arbeiten können.

Der Microsoft ODBC Driver for Fabric Data Engineering ermöglicht es Ihnen, Spark-Workloads in Fabric mit der Zuverlässigkeit und Einfachheit des ODBC-Standards zu verbinden, abzufragen und zu verwalten. Der Treiber basiert auf den Livy-APIs von Fabric und bietet eine sichere und flexible Spark-SQL-Konnektivität zu Ihren C/C++-, .NET-, Python- und anderen ODBC-kompatiblen Anwendungen und BI-Tools.

Wichtigste Funktionen

• ODBC 3.x-kompatibel: Vollständige Implementierung der ODBC 3.x-Spezifikation
• Microsoft Entra ID authentication: Mehrere Authentifizierungsflüsse, einschließlich Azure CLI, interaktive, Client-Authentifizierungsinformationen, zertifikatbasierte und Zugriffstoken-Authentifizierung
• Unterstützung von Spark SQL-Abfragen: Direkte Ausführung von Spark SQL-Anweisungen
• Umfassende Unterstützung für Datentypen: Unterstützung für alle Spark SQL-Datentypen einschließlich komplexer Typen (ARRAY, MAP, STRUCT)
• Wiederverwenden von Sitzungen: Integrierte Sitzungsverwaltung für verbesserte Leistung
• Modus für hohe Parallelität: Aktivieren Sie gemeinsam genutzte, bereits gestartete serverseitige Livy-Sitzungen, um die Latenz beim Verbindungsaufbau und die unnötige Ausbreitung von Spark-Clustern zu reduzieren
• Unterstützung für große Tabellen: Optimierte Behandlung für große Resultsets mit konfigurierbaren Seitengrößen
• Async Prefetch: Laden von Hintergrunddaten zur verbesserung der Leistung
• Proxyunterstützung: HTTP-Proxykonfiguration für Unternehmensumgebungen
• Multi-Schema-Lakehouse-Unterstützung: Stellen Sie eine Verbindung mit einem bestimmten Schema in einem Lakehouse her
• OneLake-Integration: Zugriff auf in OneLake gespeicherte Lakehouse-Daten, einschließlich Tabellen über mehrere Schemata, über eine einheitliche ODBC-Schnittstelle ohne separate Speicherkonfiguration
• Unterstützung von Umgebungselementen: Hängen Sie Fabric-Umgebungselemente während der Jobausführung an, um Arbeitsbereichsbibliotheken, Spark-Eigenschaften und Variablen auf jede Sitzung anzuwenden.
• Custom Spark-Konfiguration: Übergeben Sie Spark-Konfigurationseigenschaften direkt über die Verbindungszeichenfolge, um das Sitzungsverhalten zu optimieren.

Voraussetzungen

Stellen Sie vor der Verwendung des Microsoft ODBC-Treibers für Microsoft Fabric Data Engineering folgendes sicher:

• Betriebssystem: Windows 10/11 oder Windows Server 2016+
• Fabric Access: Zugang zu einem Fabric-Arbeitsbereich
• Microsoft Entra ID-Anmeldeinformationen: Geeignete Anmeldeinformationen für die Authentifizierung
• Workspace- und Lakehouse-IDs: GUID-Kennungen für Ihren Fabric-Arbeitsplatz und Ihr Lakehouse
• Azure CLI (optional): Erforderlich für die Azure CLI-Authentifizierungsmethode

Herunterladen und MSI-Installation

• Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering herunterladen (ZIP)

1. Herunterladen des Microsoft ODBC-Treibers für Microsoft Fabric Data Engineering MSI-Paket
2. Doppelklicken Sie auf MicrosoftFabricODBCDriver-2.0.msi.
3. Folgen Sie dem Installations-Assistenten, und akzeptieren Sie den Lizenzvertrag.
4. Installationsverzeichnis auswählen (Standard: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Abschließen der Installation

Unbeaufsichtigte Installation

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

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

Überprüfen der Installation

Überprüfen Sie nach der Installation, ob der Treiber registriert ist:

1. Ausführen odbcad32.exe (ODBC-Datenquellenadministrator)
2. Navigieren zur Registerkarte "Treiber "
3. Überprüfen, ob "Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering" aufgeführt ist

Schnellstartbeispiel

Dieses Beispiel zeigt, wie man sich mit Fabric verbindet und eine Abfrage mit dem Microsoft ODBC Driver for Microsoft Fabric Data Engineering ausführt. Stellen Sie sicher, dass Sie die Voraussetzungen erfüllt und den Treiber installiert haben, bevor Sie diesen Code ausführen.

C/C++ Beispiel

#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;
}

Python-Beispiel

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

.NET-Beispiel

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 der Verbindungszeichenfolge

Grundlegende Verbindungszeichenfolge

Der Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering verwendet das folgende Verbindungszeichenfolgenformat:

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

Komponenten der Verbindungszeichenfolge

Exemplarische Verbindungszeichenfolgen

Grundlegende Verbindung (Azure CLI-Authentifizierung)

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

Mit Leistungsoptionen

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

Mit Protokollierung

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

Mit Modus für hohe Nebenläufigkeit

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

Siehe den Abschnitt zum Modus „High-Concurrency (HC)“ für vollständige Konfigurationshinweise.

Authentifizierung

Der Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering unterstützt mehrere Authentifizierungsmethoden über Microsoft Entra ID (früher Azure Active Directory). Die Authentifizierung wird mithilfe des AuthFlow Parameters in der Verbindungszeichenfolge konfiguriert.

Authentifizierungsmethoden

Sie können Authentifizierungswerte in SNAKE_CASE in Großbuchstaben, PascalCase oder numerischer Form angeben. Der Fahrer akzeptiert außerdem kurze Aliase wie Browser, , , CLI, CertificateToken, und FileInteractive. Der Fahrer ignoriert Unterstriche beim Vergleich von Werten.

Azure CLI-Authentifizierung

Am besten geeignet für: Entwicklung und interaktive Anwendungen

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

Erforderliche Komponenten:

• Azure CLI installiert: az --version
• Angemeldet: az login

Interaktive Browserauthentifizierung

Am besten geeignet für: Benutzerorientierte Anwendungen

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

Verhalten:

• Öffnet ein Browserfenster für die Benutzerauthentifizierung.
• Anmeldeinformationen werden für nachfolgende Verbindungen zwischengespeichert.

Clientanmeldeinformationen (Dienstprinzipal)-Authentifizierung

Am besten geeignet für: Automatisierte Dienste und Hintergrundaufträge

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

Erforderliche Parameter

• TenantId: Azure-Mandanten-ID
• ClientId: Anwendungs-ID (Client-ID) von Microsoft Entra ID
• ClientSecret: Geheimer Clientschlüssel von Microsoft Entra ID

Bewährte Methoden

• Sicheres Speichern geheimer Schlüssel (Azure Key Vault, Umgebungsvariablen)
• Verwenden von verwalteten Identitäten nach Möglichkeit
• Regelmäßiges Erneuern von Geheimnissen

Zertifikatbasierte Authentifizierung

Am besten geeignet für: Unternehmensanwendungen, die zertifikatbasierte Authentifizierung erfordern

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

Erforderliche Parameter:

• TenantId: Azure-Mandanten-ID
• ClientId: Anwendungs-ID (Client-ID)
• CertificatePath: Pfad zur PFX/PKCS12-Zertifikatdatei
• CertificatePassword: Zertifikatkennwort

Zugriffstokenauthentifizierung

Am besten geeignet für: Benutzerdefinierte Authentifizierungsszenarien

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

Dateitoken-Authentifizierung

Verwenden Sie Dateitoken-Authentifizierung für containerisierte Umgebungen und automatisierte Pipelines, bei denen ein anderer Prozess einen Inhabertoken in die bekannte Tokendatei des Treibers schreibt:

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

Der Treiber löst den Token-Dateistandort unter Windows und Linux auf.

Treiberübergreifende Eigenschaftsaliase

Der ODBC-Treiber akzeptiert ausgewählte ADONET- und JDBC-Eigenschaftsnamen zusätzlich zu nativen ODBC-Namen. Diese Unterstützung kann Verbindungsstring-Änderungen reduzieren, wenn du zwischen Fabric-Treibern wechselst.

Der Treiber löst beim Verbindungsaufbau 17 treiberübergreifende Aliase auf.

Konfigurationsparameter

Erforderliche Parameter

Diese Parameter müssen in jeder Verbindungszeichenfolge vorhanden sein:

Optionale Parameter

Verbindungseinstellungen

Leistungseinstellungen

Logging-Einstellungen

Proxyeinstellungen

Einstellungen für hohe Parallelität (HC)

Verwenden Sie diese Parameter, um den High-Concurrency (HC)-Modus zu aktivieren und zu konfigurieren. Der HC-Modus ist optional. Wenn Sie LivyMode oder UseHighConcurrency nicht festlegen, verwendet der Treiber den klassischen Pfad für eine einzelne Sitzung. Für Hinweise und Beispiele siehe High-Concurrency (HC)-Modus.

Priorität und Validierung von Modi

• LivyMode hat Vorrang vor UseHighConcurrency, wenn Sie beide Parameter festlegen.
• Parameterwerte sind nicht groß- und grossschreibungssensitiv.
• UseHighConcurrency akzeptiert true, yes, on oder 1, um den HC-Modus zu aktivieren. Es akzeptiert false, 0, no oder off, um den HC-Modus zu deaktivieren.
• Für andere nichtleere Werte liefert ein SQLDriverConnect Fehler zurück. DSN-only protokolliert den Validierungsfehler SQLConnect und verwendet den klassischen Pfad.

Kompatibilitätseinstellungen

Der Treiber akzeptiert TenantPrincipal und PoolMax, einschließlich ihrer umgebungsvariablen Fallbacks, um mit früheren HC-Konfigurationen kompatibel zu sein. Der Treiber parselt und validiert diese Werte, aber sie beeinflussen nicht das HC-Session-Matching oder die Laufzeit-Poolkapazität. Verlassen Sie sich nicht auf sie für Mieterisolation oder Verbindungsgrenzen.

Umgebungsvariablen-Fallbacks

Der Treiber verwendet die folgenden Umweltvariablen nur, wenn der entsprechende DSN- oder Verbindungsstring-Parameter nicht gesetzt ist:

Für FABRIC_ODBC_USE_HC erkennt die ausschließlich umgebungsbasierte Aktivierung true, 1 oder yes (ohne Beachtung der Groß-/Kleinschreibung). Andere Werte lassen HC deaktiviert. Die Aliase off und on gelten nur für DSN- und Verbindungszeichenfolgenwerte.

Umgebungseinstellungen

Sie können ein Fabric Umgebungselement an die Spark-Sitzung anfügen, die vom Treiber gestartet wurde. Die Bibliotheken, Spark-Eigenschaften und Variablen der ausgewählten Umgebung werden automatisch angewendet, wenn die Sitzung erstellt wird.

Beispiel für eine Verbindungszeichenfolge mit einem Umgebungselement:

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

Benutzerdefinierte Spark-Konfiguration

Sie können Spark-Konfigurationseigenschaften direkt im Verbindungszeichenfolge übergeben. Jeder Parameter, der mit spark. präfixiert ist, wird zum Erstellungszeitpunkt automatisch auf die Spark-Sitzung angewendet, sodass Sie den Arbeitsbereich oder die Laufzeitstandardwerte außer Kraft setzen können.

Beispiel-Spark-Konfigurationen:

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

Example Verbindungszeichenfolge mit benutzerdefinierten Spark-Eigenschaften:

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

Hoch-Nebenläufigkeit (HC) Modus

Der Modus für hohe Parallelität (HC) ermöglicht es ODBC-Verbindungen mit demselben Arbeitsbereich und demselben Lakehouse, eine Verbindung mit gemeinsam genutzten, bereits aufgewärmten serverseitigen Livy Spark-Sitzungen herzustellen, statt für jede Verbindung einen separaten Cluster bereitzustellen. Nutze es für Arbeitslasten wie BI-Dashboards, Notebook-Kernel und ETL-Fan-outs, die viele kurzlebige Verbindungen öffnen und serververwaltete Spark-Kapazitäten teilen können.

Der HC-Modus ist opt-in. Wenn du keine HC-Einstellung konfigurierst, verwendet der Treiber den klassischen Einzelsitzungspfad.

Auswählen eines Verbindungsmodus

Benutze den HC-Modus wenn:

• Ihre Arbeitslast öffnet viele kurzlebige ODBC-Verbindungen, wie BI-Dashboards, Notebook-Kernel oder ETL-Fan-Out.
• Verbindungen zielen auf denselben Arbeitsbereich und dasselbe Lakehouse ab und können eine serververwaltete Spark-Sitzung teilen.
• Die Reduzierung der Kaltstart-Latenz pro Verbindung ist wichtig.

Nutze den klassischen Modus, wenn:

• Jede Verbindung erfordert eine isolierte Spark-Sitzung aufgrund unterschiedlicher Spark-Konfigurationen oder strikter Ressourcenisolation.
• Der Fabric Livy-Endpunkt für den Zielarbeitsbereich und das Lakehouse unterstützt den HC-Modus nicht.

Aktivieren Sie den Modus für hohe Parallelität

Fügen Sie der DSN oder der Verbindungszeichenfolge einen Parameter für den Modus mit hoher Parallelität hinzu.

Empfohlen: Festlegen LivyMode

Verwenden Sie LivyMode, um den Sitzungserfassungsmodus explizit auszuwählen:

LivyMode=HighConcurrency

Unterstützte Werte sind Classic, HighConcurrencyund Auto. Werte sind nicht groß-/kleinsensitiv. Auto Derzeit wählt er den Classic-Modus.

Alternative: Satz UseHighConcurrency

Verwenden Sie die boolesche Einstellung zur Kompatibilität mit bestehenden Konfigurationen:

UseHighConcurrency=true

Zum Aktivieren des Modus für hohe Parallelität verwenden Sie true, 1, yes oder on. Um es zu deaktivieren, verwenden Sie false, 0, no oder off. Werte sind nicht groß-/kleinsensitiv. SQLDriverConnect verweigert andere nichtleere Werte mit SQLSTATE HY024. DSN-only protokolliert den Validierungsfehler SQLConnect und verwendet den klassischen Modus.

Erforderliche Parameter im HC-Modus

Die HC-Aktivierung erfordert folgende gültige Kennungen:

Beziehen Sie SessionTag ein, weil es die serverseitige Zuordnung für Warm-Sessions beeinflusst.

Sitzungsabgleich

Der HC-Modus garantiert nicht, dass jede Verbindung eine bestehende Sitzung wiederverwendet. Für jede Anfrage zur Sitzungserfassung sendet der Treiber:

• Der SessionTag-Wert.
• Die effektive Spark-Konfiguration, einschließlich conf.* Einstellungen und EnvironmentId.

Der Fabric Livy Service bewertet diese Werte und entscheidet, ob die Verbindung mit einer warmen Sitzung verbunden oder eine neue Sitzung erstellt wird. Um die Wiederverwendung der Sitzungen zu verbessern, verwenden Sie konsistente Werte über Verbindungen hinweg, die für die gemeinsame Server-verwaltete Spark-Kapazität gedacht sind.

Exemplarische Verbindungszeichenfolgen

Minimale HC-Verbindung (Azure CLI-Authentifizierung):

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

HC mit abgestimmten Auszeiten:

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 mit Umgebungs- und Spark-Konfigurationsüberschreibungen:

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

HC-Modus in einem DSN konfigurieren

Du kannst HC-Einstellungen in einem DSN speichern, anstatt sie in jedem Verbindungszeichenfolge zu wiederholen. Wenn ein Verbindungszeichenfolge keinen Wert angibt, liest der Treiber folgende Einstellungen aus dem DSN:

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

Der Treiber liest außerdem auch die ausschließlich für die Kompatibilität vorgesehenen Einstellungen TenantPrincipal und PoolMax. Um diese Einstellungen zu speichern, bearbeite die DSN in odbcad32.exe oder benutze SQLWritePrivateProfileString. Verwenden Sie die Parameternamen in der HC-Einstellungstabelle.

HC-Modus deaktivieren

Du kannst neue HC-Session-Erwerbungen deaktivieren, ohne den Treiber neu zu deployen. Verwenden Sie die Methode, die mit der Aktivierung des HC-Modus übereinstimmt:

Connection-String- und DSN-Einstellungen haben Vorrang vor dem Fallback über Umgebungsvariablen. Diese Änderungen betreffen nur neue Verbindungen. Bestehende HC-Sessions laufen weiter, bis sie veröffentlicht werden.

Verstehen Sie das Laufzeitverhalten von HC

• Validierung:SQLDriverConnect lehnt ungültige HC-Boolesche und positiv-ganzzahlige Werte mit SQLSTATE HY024ab. Es weist eine ungültige LivyMode sowie ungültige oder zu große WorkspaceId-, LakehouseId- und IdempotencyKey-Werte mit SQLSTATE HY000 zurück. Ein zu großer Kompatibilitäts-TenantPrincipalWert gibt ebenfalls HY000 zurück. Bei ausschließlich SQLConnectDSN protokolliert der Treiber gewöhnliche HC-Validierungsfehler und verwendet den klassischen Modus. Zu große sicherheitssensible Werte führen weiterhin dazu, dass die Verbindung fehlschlägt.
• Sensible Daten: Der Treiber schließt andere sensible Felder aus HC-Logs und Diagnoseausgaben aus oder löscht IdempotencyKey sie aus.
• Stornierung: Die Kündigung des Kontoauszugs erfolgt kooperativ. Die bereits laufende Serverarbeit endet sauber, anstatt sofort beendet zu werden.
• Leistungsschalter: HC- und klassische Modi verwenden separate Leistungsschalter. Das Erschöpfen eines Modus wirkt sich nicht auf das andere aus.
• Anfangsdatenbank: HC-Verbindungen führen die Anfangsanweisung USE für den Parameter Database nicht aus. Führe USE <database> nach der Verbindung aus oder benutze vollständig qualifizierte Tabellennamen.
• Diagnose: Legen Sie LogLevel=DEBUG so fest, dass HC-Erfassung, Abfragen, Freigaben und Entscheidungen zur Fehlerzuordnung protokolliert werden. Für eine gezielte Fehlerbehebung setzen Sie LIVY_HC_VERBOSE=1 so, dass zusätzliche bereinigte HC-HTTP-Diagnosedaten einbezogen werden.

Konfigurieren Sie ein DSN

Erstellen eines System-DSN

1. ODBC-Administrator öffnen

   %SystemRoot%\System32\odbcad32.exe
   

2. Erstellen eines neuen System-DSN

   • Zur Registerkarte "System-DSN" wechseln
   • Wählen Sie „Hinzufügen“ aus.
   • Wählen Sie "Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering" aus.
   • Wählen Sie "Fertig stellen" aus.

3. Konfigurieren von DSN-Einstellungen

   • Datenquellenname: Geben Sie einen eindeutigen Namen ein (z. B. FabricODBC)
   • Beschreibung: Optionale Beschreibung
   • Arbeitsbereichs-ID: GUID des Fabric-Arbeitsbereichs
   • Lakehouse-ID: Ihre Fabric-Lakehouse-GUID
   • Authentifizierung: Authentifizierungsmethode auswählen
   • Environment-ID (optional): Geben Sie die GUID des Fabric Umgebungselements ein, das während der Sitzungserstellung angefügt werden soll.
   • Livy-Modus (optional): Auf HighConcurrency setzen, um den HC-Modus zu aktivieren
   • Session-Tag (optional): Geben Sie ein nicht-sensibles Betriebslabel für HC-Session-Matching ein
   • Konfigurieren zusätzlicher Einstellungen nach Bedarf

4. Verbindung testen

   • Wählen Sie "Verbindung testen" aus, um die Einstellungen zu überprüfen.
   • Wählen Sie zum Speichern "OK" aus.

Verwenden von DSN in Anwendungen

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

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

Verwendungsbeispiele

Grundlegende Verbindung und Abfrage

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

Arbeiten mit großen Ergebnismengen

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

DML-Anweisungen ausführen

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

Verwenden Sie executeDml mit INSERT-, UPDATE- oder DELETE-Anweisungen. Die gemeldete Zeilenanzahl hängt davon ab, ob das Ergebnis eine vom Treiber erkannte Aktualisierungszahl enthält.

Schema-Ermittlung

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

Datentypzuordnung

Der Treiber ordnet Spark SQL-Datentypen ODBC-SQL-Typen zu:

INTEGRATION von BI-Tools

Microsoft Excel

1. Excel öffnen –> Daten –> Daten abrufen –> aus anderen Quellen –> aus ODBC
2. Wählen Sie Ihren konfigurierten DSN aus (z. B. FabricODBC)
3. Authentifizieren Sie sich, wenn Sie dazu aufgefordert werden
4. Durchsuchen und Auswählen von Tabellen
5. Laden von Daten in excel-Arbeitsblatt

Power BI Desktop

1. Öffnen von Power BI Desktop –> Abrufen von Daten –> ODBC
2. Wählen Sie Ihren konfigurierten DSN aus.
3. Durchsuchen des Datenkatalogs und Auswählen von Tabellen
4. Transformieren von Daten nach Bedarf
5. Erstellen von Visualisierungen

SQL Server Management Studio (verknüpfter Server)

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

Problembehandlung

Dieser Abschnitt enthält Anleitungen zum Beheben häufiger Probleme, die bei verwendung des Microsoft ODBC-Treibers für Microsoft Fabric Data Engineering auftreten können.

Häufig auftretende Probleme

In den folgenden Abschnitten werden allgemeine Probleme und deren Lösungen beschrieben:

Verbindungsfehler

Problem: Keine Verbindung zu Fabric

Lösungen:

1. Überprüfen Sie, ob die Workspace-ID und die Lakehouse-ID gültige GUIDs sind.
2. Überprüfen sie die Azure CLI-Authentifizierung: az account show
3. Stellen Sie sicher, dass Sie über entsprechende Fabric-Arbeitsbereichsberechtigungen verfügen.
4. Überprüfen von Netzwerkkonnektivitäts- und Proxyeinstellungen

Authentifizierungsfehler

Problem: Die Authentifizierung schlägt mit Azure CLI fehl

Lösungen:

• Ausführen az login zum Aktualisieren von Anmeldeinformationen
• Überprüfen Sie, ob es sich um den richtigen Mandanten handelt: az account set --subscription <subscription-id>
• Gültigkeit des Tokens überprüfen: az account get-access-token --resource https://api.fabric.microsoft.com

Abfrage-Timeouts

Problem: Abfragen, die bei großen Tabellen eine Zeitüberschreitung haben

Lösungen:

• Aktivieren von LargeTableSupport=true
• Passen Sie PageSizeBytes für eine optimale Blockgröße an.
• Aktivieren sie asynchrone Prefetch: EnableAsyncPrefetch=1
• Verwenden einer LIMIT Klausel zum Einschränken der Ergebnisgröße

Aktivieren der Protokollierung

Beim Behandeln von Problemen kann das Aktivieren der detaillierten Protokollierung dabei helfen, die Ursache der Probleme zu identifizieren. Sie können die Protokollierung über die Verbindungszeichenfolge aktivieren.

So aktivieren Sie die detaillierte Protokollierung:

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

Protokollebenen:

• DEBUG: Detaillierte Debugging-Informationen und die ausführlichste Treiber-Log-Ebene
• INFO: Allgemeine Informationen (Standard)
• WARN: Nur Warnungen
• ERROR: Nur Fehler

ODBC-Ablaufverfolgung

Für Diagnosen auf niedriger Ebene können Sie die Windows ODBC-Ablaufverfolgung aktivieren, um detaillierte ODBC-API-Aufrufe und Treiberverhalten zu erfassen. Denken Sie daran, die Ablaufverfolgung zu deaktivieren, wenn sie nicht erforderlich ist, um eine optimale Leistung aufrechtzuerhalten.

So aktivieren Sie die ODBC-Ablaufverfolgung:

1. odbcad32.exe öffnen
2. Zur "Tracing"-Tab wechseln
3. Festlegen des Pfads der Ablaufverfolgungsdatei (z. B. C:\temp\odbctrace.log)
4. Wählen Sie "Tracing jetzt starten" aus.
5. Reproduzieren Sie das Problem
6. Wählen Sie "Tracing jetzt stoppen" aus.

Verwandte Inhalte

• Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering unter Linux
• Apache Spark-Runtimes in Fabric
• Fabric Runtime 1.3
• Was ist die Livy-API für Data Engineering
• Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering