Microsoft ODBC-driver voor Microsoft Fabric Data Engineering op Linux (Preview)

ODBC (Open Database Connectivity) is een veelgebruikte standaard waarmee clienttoepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

De Microsoft ODBC Driver for Fabric Data Engineering stelt je in staat om Spark-workloads in Fabric te verbinden, te bevragen en te beheren met de betrouwbaarheid en eenvoud van de ODBC-standaard. Gebouwd op de Livy-API's van Fabric, biedt de driver veilige en flexibele Spark SQL-connectiviteit naar je C/C++, .NET, Python en andere ODBC-compatibele applicaties op Linux.

Belangrijkste kenmerken

• ODBC 3.x-conform: Volledige implementatie van de ODBC 3.x-specificatie.
• Microsoft Entra ID-authenticatie: Meerdere authenticatieflows, waaronder Azure CLI, clientgegevens, certificaatgebaseerde en toegangstokenauthenticatie.
• Spark SQL-queryondersteuning: Directe uitvoering van Spark SQL-instructies.
• Uitgebreide ondersteuning voor datatypes: Ondersteuning voor alle Spark SQL-datatypes, inclusief complexe types (ARRAY, MAP, en STRUCT).
• Hergebruik van sessies: Ingebouwd sessiebeheer voor betere prestaties.
• Ondersteuning voor grote tabellen: Geoptimaliseerde behandeling voor grote resultatensets met configureerbare paginagroottes.
• Async prefetch: Achtergronddata laden voor betere prestaties.
• Proxy-ondersteuning: HTTP-proxyconfiguratie voor enterprise-omgevingen.
• Multi-schema lakehouse ondersteuning: Verbind met een specifiek schema binnen een lakehouse.

Prerequisites

Voordat je de Microsoft ODBC Driver voor Microsoft Fabric Data Engineering op Linux gebruikt, zorg ervoor dat je aan de volgende vereisten voldoet:

• Besturingssysteem: Ubuntu 22.04 of later, Debian 11 of later, of Red Hat Enterprise Linux (RHEL) 8 of later op x86-64.
• unixODBC: De ODBC-drivermanager voor Linux. Installeer de unixodbc and-pakketten unixodbc-dev .
• Fabric access: Toegang tot een Fabric werkruimte.
• Microsoft Entra ID-inloggegevens: Geschikte inloggegevens voor authenticatie.
• Werkruimte- en meerhuis-ID's: De GUID-identificaties voor je Fabric-werkruimte en meerhuis.
• Azure CLI (optioneel): Vereist wanneer je Azure CLI-authenticatie gebruikt.

Download en installeer op Linux

Microsoft ODBC Driver voor Microsoft Fabric Data Engineering versie 1.0.0 is beschikbaar in de publieke preview.

• Download Microsoft ODBC Driver voor Microsoft Fabric Data Engineering op Linux (zip)

Het stuurprogramma installeren:

1. Pak ms-sparksql-odbc-linux-1.0.0.zip uit.

2. Open een terminal in de uitgepakte map.

3. Installeer het Debian-pakket:

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

Het pakket installeert de volgende bestanden:

Stuur de chauffeur handmatig in

Het pakket registreert de driver automatisch bij unixODBC. Om de driver handmatig te registreren, voer je uit:

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

De installatie controleren

Controleer of de driver geregistreerd is en dat de bibliotheek is geïnstalleerd:

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

Het odbcinst commando zou moeten vermelden [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Verwijder de driver

Om de driver te verwijderen, voer je het volgende commando uit:

sudo dpkg -r microsoft-fabric-odbc-driver

Dit commando verwijdert de driverbestanden en verwijdert het register van de driver uit unixODBC.

Snelstartvoorbeeld

De volgende voorbeelden verbinden met Fabric en voeren een Spark SQL-query uit. Voltooi de vereisten en installeer de driver voordat je een voorbeeld uitvoert.

Python-voorbeeld

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++ voorbeeld

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

Bouw en draai het voorbeeld:

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

.NET-voorbeeld

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

Indeling van verbindingstekenreeks

Basisverbindingsreeks

Gebruik het volgende verbindingsreeks-formaat:

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

Onderdelen van verbindingsreeks

Voorbeeld van verbindingsreeksen

Basisverbinding

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

Verbinding met prestatie-opties

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

Verbinding met houtkap

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

Verificatie

De Microsoft ODBC Driver for Microsoft Fabric Data Engineering ondersteunt meerdere authenticatiemethoden via Microsoft Entra ID. Configureer authenticatie door de AuthFlow parameter in de verbindingsreeks of DSN te gebruiken.

Verificatiemethoden

Azure CLI-verificatie

Gebruik Azure CLI-authenticatie voor ontwikkel- en interactieve applicaties.

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)

Controleer voordat je verbinding maakt of de Azure CLI is geïnstalleerd en log in:

az --version
az login

Om Azure CLI op Debian of Ubuntu te installeren, gebruik je de pakketbeheerder:

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

Authenticatie van clientgegevens

Gebruik client-credential-authenticatie voor geautomatiseerde diensten en achtergrondopdrachten.

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

Geef de volgende parameters op:

• TenantId: De Microsoft Entra tenant-ID.
• ClientId: de toepassings-id (client).
• ClientSecret: Het cliëntgeheim.

Bewaar geheimen in een beveiligde geheime opslag of omgevingsvariabelen. Sla geen geheimen op in platte tekst verbindingsstrings of INI-bestanden.

Verificatie op basis van certificaat

Gebruik certificaatgebaseerde authenticatie voor bedrijfsapplicaties die certificaatgegevens vereisen.

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

Geef de volgende parameters op:

• TenantId: De Microsoft Entra tenant-ID.
• ClientId: de toepassings-id (client).
• CertificatePath: Het pad naar het PFX- of PKCS12-certificaatbestand.
• CertificatePassword: Het certificaatwachtwoord.

Verificatie van toegangstokens

Gebruik toegangstokenauthenticatie wanneer je applicatie via een ander mechanisme een token verkrijgt.

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

Configuratieparameters

Benodigde parameters

Neem deze parameters op in elke verbindingsreeks:

Optionele parameters

Verbindingsinstellingen

Prestatie-instellingen

Instellingen voor logboekregistratie

Proxy-instellingen

DSN-configuratie

Op Linux configureer je databronnamen (DSN's) in INI-bestanden in plaats van in het Windows-register.

Een DSN maken

Kopieer het geïnstalleerde sjabloon:

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

Bewerk ~/.odbc.ini met je Fabric-werkruimtedetails:

[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

Controleer het DSN

Geef een lijst van de geconfigureerde DSN's en test vervolgens de verbinding:

odbcinst -q -s
isql -v FabricDSN

Het isql commando vereist de unixODBC-commandoregeltools.

Gebruik een DSN in applicaties

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

Voorbeelden van gebruik

Test een verbinding met isql

Start een interactieve SQL-sessie:

isql -v FabricDSN

Voer één enkele query uit:

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

Werk met grote resultatensets

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

Ontdek schema's en tabellen

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

Koppeling van gegevenstypen

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan ODBC SQL-typen:

Platformverschillen

Probleemoplossingsproces

Bestuurder niet gevonden

Probleem: De verbinding faalt met [IM002] Data source name not found and no default driver specified.

Oplossingen:

1. Controleer de chauffeursregistratie door te draaien odbcinst -q -d.
2. Controleer of dat bestaat /usr/lib/libmicrosoftfabricodbc.so .
3. Registreer de bestuurder door te draaien sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Installeer het pakket opnieuw door . uit te voeren sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN is niet gevonden

Probleem: De verbinding faalt met [IM002] Data source name not found.

Oplossingen:

1. Controleer de DSN-configuratie door te draaien odbcinst -q -s.
2. Controleer dat of /etc/odbc.ini het ~/.odbc.ini DSN-gedeelte bevat.
3. Zorg ervoor dat de Driver waarde precies overeenkomt met de naam van de geregistreerde bestuurder.

Verbindingsfouten

Probleem: De driver kan geen verbinding maken met Fabric.

Oplossingen:

1. Controleer of de workspace ID en lakehouse ID geldige GUIDs zijn.
2. Controleer Azure CLI-authenticatie door az account show.
3. Zorg dat je de vereiste Fabric-werkruimterechten hebt.
4. Controleer de netwerkconnectiviteit en proxy-instellingen.

Authenticatiefouten

Probleem: Azure CLI-authenticatie faalt.

Oplossingen:

1. Ren az login om je gegevens te verversen.
2. Stel het juiste abonnement in door te draaien az account set --subscription <subscription-id>.
3. Controleer de token door te draaien az account get-access-token --resource https://api.fabric.microsoft.com.
4. Zorg ervoor dat je account de vereiste Fabric-werkruimterechten heeft.

Fouten in gedeelde bibliotheken

Probleem: De bestuurder meldt error while loading shared libraries: libmicrosoftfabricodbc.so.

Oplossingen:

1. Installeer het pakket opnieuw door . uit te voeren sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Controleer of dat bestaat /usr/lib/libmicrosoftfabricodbc.so .
3. Voer sudo ldconfig uit om de gedeelde bibliotheekcache te versen.

Time-outs voor zoekopdrachten

Probleem: Queries lopen uit op grote tabellen.

Oplossingen:

1. Voeg deze toe LargeTableSupport=true aan de verbindingsreeks.
2. Pas PageSizeBytes aan op de grootte van het resultaat.
3. Voeg deze toe EnableAsyncPrefetch=1 aan de verbindingsreeks.
4. Gebruik een LIMIT clausule om de grootte van het resultaat te beperken.

Logboekregistratie inschakelen

Schakel gedetailleerde logging in een DSN in:

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

Alternatief kun je loggparameters toevoegen aan de verbindingsreeks:

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

De driver ondersteunt de volgende logboekniveaus:

• TRACE: Bevat alle API-aanroepen.
• DEBUG: Bevat gedetailleerde informatie over het debuggen.
• INFO: Bevat algemene informatie en is de standaard.
• WARN: Bevat alleen waarschuwingen.
• ERROR: Bevat alleen fouten.

Schakel unixODBC-tracering in

Voor laag-niveau ODBC-aanroepdiagnostiek voegt u de volgende configuratie toe aan /etc/odbcinst.ini:

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

Zet het traceren uit zodra je klaar bent met het oplossen van problemen om onnodige prestatie-overhead te voorkomen.

Verwante onderwerpen

• Microsoft ODBC-stuurprogramma voor Microsoft Fabric Data Engineering
• Apache Spark-runtimes in Fabric
• Fabric Runtime 1.3
• Wat is de Livy-API voor Data Engineering?
• Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering
• unixODBC