Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering unter Linux (Vorschau)

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 sichere und flexible Spark-SQL-Konnektivität zu Ihren C/C++-, .NET-, Python- und anderen ODBC-kompatiblen Anwendungen unter Linux.

Wichtigste Funktionen

• ODBC 3.x-konform: Vollständige Implementierung der ODBC 3.x-Spezifikation.
• Microsoft Entra ID-Authentifizierung: Mehrere Authentifizierungsflüsse, einschließlich Azure CLI, Client-Zugangsdaten, zertifikatsbasierter und Zugriffstoken-Authentifizierung.
• Spark SQL-Abfrageunterstützung: 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, und STRUCT).
• Wiederverwendung von Sitzungen: Integriertes Sitzungsmanagement für bessere Leistung.
• Unterstützung für große Tabellen: Optimierte Behandlung für große Ergebnissätze mit konfigurierbaren Seitengrößen.
• Async Prefetch: Hintergrunddatenladen zur verbesserten Leistung.
• Proxy-Unterstützung: HTTP-Proxy-Konfiguration für Unternehmensumgebungen.
• Multi-Schema-Lakehouse-Unterstützung: Verbinden Sie sich mit einem bestimmten Schema innerhalb eines Lakehouse.

Voraussetzungen

Bevor Sie den Microsoft ODBC Driver für Microsoft Fabric Data Engineering unter Linux verwenden, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllen:

• Betriebssystem: Ubuntu 22.04 oder neuer, Debian 11 oder neuer, oder Red Hat Enterprise Linux (RHEL) 8 oder später auf x86-64.
• unixODBC: Der ODBC-Treibermanager für Linux. Installiere die unixodbc and-Pakete unixodbc-dev .
• Fabric Access: Zugang zu einem Fabric-Arbeitsbereich.
• Microsoft Entra ID-Zugangsdaten: Geeignete Zugangsdaten für die Authentifizierung.
• Arbeitsplatz- und Seehaus-IDs: Die GUID-Kennungen für Ihren Fabric-Arbeitsplatz und Ihr Seehaus.
• Azure CLI (optional): Erforderlich, wenn Sie Azure CLI-Authentifizierung verwenden.

Herunterladen und installieren auf Linux

Der Microsoft ODBC Driver für Microsoft Fabric Data Engineering Version 1.0.0 ist in der öffentlichen Vorschau verfügbar.

• Laden Sie den Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering auf Linux (zip) herunter

Den Treiber installieren:

1. Extrahieren Sie ms-sparksql-odbc-linux-1.0.0.zip.

2. Öffnen Sie ein Terminal im extrahierten Verzeichnis.

3. Installieren Sie das Debian-Paket:

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

Das Paket installiert die folgenden Dateien:

Treiber manuell registrieren

Das Paket registriert den Treiber automatisch bei unixODBC. Um den Treiber manuell zu registrieren, führen Sie aus:

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

Überprüfen der Installation

Überprüfen Sie, ob der Treiber registriert ist und die Bibliothek installiert ist:

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

Der Befehl odbcinst sollte auflisten [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Deinstalliere den Treiber

Um den Treiber zu deinstallieren, führen Sie folgenden Befehl aus:

sudo dpkg -r microsoft-fabric-odbc-driver

Dieser Befehl entfernt die Treiberdateien und deregistriert den Treiber aus unixODBC.

Schnellstartbeispiel

Die folgenden Beispiele verbinden sich mit Fabric und führen eine Spark-SQL-Abfrage aus. Erfülle die Voraussetzungen und installiere den Treiber, bevor du ein Beispiel ausführst.

Python-Beispiel

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

C/C++ Beispiel

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

Baue und führe das Beispiel aus:

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

.NET-Beispiel

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

Grundlegende Verbindungszeichenfolge

Verwenden Sie das folgende Verbindungszeichenfolge-Format:

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

Komponenten der Verbindungszeichenfolge

Exemplarische Verbindungszeichenfolgen

Grundverbindung

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

Verbindung 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

Verbindung zum Holzeinschlag

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

Authentication

Der Microsoft ODBC Driver for Microsoft Fabric Data Engineering unterstützt mehrere Authentifizierungsmethoden über Microsoft Entra ID. Konfigurieren Sie die Authentifizierung durch Verwendung des Parameters AuthFlow im Verbindungszeichenfolge oder DSN.

Authentifizierungsmethoden

Azure CLI-Authentifizierung

Verwenden Sie Azure CLI-Authentifizierung für Entwicklungs- und interaktive Anwendungen.

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)

Bevor Sie sich verbinden, überprüfen Sie, ob die Azure CLI installiert ist, und melden Sie sich an:

az --version
az login

Um Azure CLI auf Debian oder Ubuntu zu installieren, verwenden Sie den Paketmanager:

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

Authentifizierung der Client-Zugangsdaten

Verwenden Sie die Authentifizierung der Client-Zugangsdaten für automatisierte Dienste und Hintergrundjobs.

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

Geben Sie die folgenden Parameter an:

• TenantId: Die Microsoft Entra-Tenant-ID.
• ClientId: Die Client-ID der Anwendung.
• ClientSecret: Das Geheimnis des Kunden.

Speichere Geheimnisse in einem sicheren Geheimspeicher oder in Umgebungsvariablen. Speichere keine Geheimnisse in Klartext-Verbindungsstrings oder INI-Dateien.

Zertifikatbasierte Authentifizierung

Verwenden Sie zertifikatsbasierte Authentifizierung für Unternehmensanwendungen, die Zertifikatsdaten benötigen.

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

Geben Sie die folgenden Parameter an:

• TenantId: Die Microsoft Entra-Tenant-ID.
• ClientId: Die Client-ID der Anwendung.
• CertificatePath: Der Pfad zur PFX- oder PKCS12-Zertifikatsdatei.
• CertificatePassword: Das Zertifikatspasswort.

Zugriffstokenauthentifizierung

Verwenden Sie die Zugriffstoken-Authentifizierung, wenn Ihre Anwendung ein Token über einen anderen Mechanismus erhält.

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

Konfigurationsparameter

Erforderliche Parameter

Fügen Sie diese Parameter in jede Verbindungszeichenfolge ein:

Optionale Parameter

Verbindungseinstellungen

Leistungseinstellungen

Einstellungen für die Protokollierung

Proxyeinstellungen

DSN-Konfiguration

Unter Linux konfigurieren Sie Datenquellennamen (DSNs) in INI-Dateien statt in der Windows-Registry.

Erstellen eines DSN

Kopiere die installierte Vorlage:

cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template ~/.odbc.ini

Bearbeiten ~/.odbc.ini Sie mit Ihren Details zum Fabric-Arbeitsbereich:

[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

Verifiziere die DSN

Liste die konfigurierten DSNs auf und teste dann die Verbindung:

odbcinst -q -s
isql -v FabricDSN

Der Befehl isql benötigt die unixODBC-Kommandozeilen-Tools.

Verwendung eines DSN in Anwendungen

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

Verwendungsbeispiele

Teste eine Verbindung mit isql

Starte eine interaktive SQL-Sitzung:

isql -v FabricDSN

Führe eine einzelne Abfrage aus:

echo "SELECT 1 AS test" | isql -v FabricDSN -b

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

Schemata und Tabellen entdecken

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

Datentypzuordnung

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

Plattformunterschiede

Troubleshooting

Fahrer nicht gefunden

Problem: Die Verbindung schlägt mit [IM002] Data source name not found and no default driver specifiedfehl.

Lösungen:

1. Überprüfen Sie die Fahrerregistrierung, indem Sie odbcinst -q -d.
2. Vergewissern Sie sich, dass dies /usr/lib/libmicrosoftfabricodbc.so vorhanden ist.
3. Registrieren Sie den Fahrer, indem Sie . sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.templateausführen.
4. Installieren Sie das Paket erneut, indem Sie sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb. ausführen.

DSN nicht gefunden

Problem: Die Verbindung schlägt mit [IM002] Data source name not foundfehl.

Lösungen:

1. Überprüfen Sie die DSN-Konfiguration, indem Sie odbcinst -q -s. ausführen.
2. Überprüfen Sie, ob dieser ~/.odbc.ini den /etc/odbc.ini DSN-Abschnitt enthält.
3. Stellen Sie sicher, dass der Driver Wert genau mit dem Namen des registrierten Fahrers übereinstimmt.

Verbindungsfehler

Problem: Der Fahrer kann sich nicht mit Fabric verbinden.

Lösungen:

1. Überprüfen Sie, ob die Arbeitsplatz-ID und die Lakehouse-ID gültige GUIDs sind.
2. Überprüfen Sie die Azure CLI-Authentifizierung, indem Sie az account show. ausführen
3. Stelle sicher, dass du die erforderlichen Fabric-Arbeitsbereichsberechtigungen hast.
4. Überprüfe die Netzwerkverbindung und die Proxy-Einstellungen.

Authentifizierungsfehler

Problem: Die Azure CLI-Authentifizierung schlägt fehl.

Lösungen:

1. Laufen Sie az login , um Ihre Zugangsdaten zu aktualisieren.
2. Setze das richtige Abonnement, indem du . ausführst az account set --subscription <subscription-id>.
3. Überprüfen Sie den Token, indem Sie . az account get-access-token --resource https://api.fabric.microsoft.comausführen.
4. Stellen Sie sicher, dass Ihr Konto die erforderlichen Fabric-Arbeitsbereichsberechtigungen hat.

Fehler in der gemeinsamen Bibliothek

Problem: Der Fahrer meldet error while loading shared libraries: libmicrosoftfabricodbc.so.

Lösungen:

1. Installieren Sie das Paket erneut, indem Sie sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb. ausführen.
2. Vergewissern Sie sich, dass dies /usr/lib/libmicrosoftfabricodbc.so vorhanden ist.
3. Führe aus, sudo ldconfig um den Cache der gemeinsamen Bibliothek zu aktualisieren.

Zeitüberschreitungen bei Abfragen

Problem: Abfragen laufen auf großen Tabellen ab.

Lösungen:

1. Fügen Sie der Verbindungszeichenfolge hinzu LargeTableSupport=true .
2. Passen PageSizeBytes Sie die Ergebnisgröße an.
3. Fügen Sie der Verbindungszeichenfolge hinzu EnableAsyncPrefetch=1 .
4. Verwenden Sie eine LIMIT Klausel, um die Größe des Ergebnisses zu begrenzen.

Protokollierung aktivieren

Aktivieren Sie eine detaillierte Protokollierung in einem DSN:

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

Alternativ fügen Sie dem Verbindungszeichenfolge Logging-Parameter hinzu:

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

Der Treiber unterstützt folgende Log-Level:

• TRACE: Beinhaltet alle API-Aufrufe.
• DEBUG: Enthält detaillierte Debugging-Informationen.
• INFO: Enthält allgemeine Informationen und ist der Standard.
• WARN: Enthält nur Warnungen.
• ERROR: Enthält nur Fehler.

Aktivieren Sie unixODBC-Tracing

Für Low-Level-ODBC-Aufrufdiagnostiken fügen Sie folgende Konfiguration hinzu:/etc/odbcinst.ini

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

Schalten Sie das Nachverfolgen aus, wenn Sie die Fehlersuche beendet haben, um unnötigen Leistungsaufwand zu vermeiden.

Verwandte Inhalte

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