Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering på Linux (Förhandsgranskning)

ODBC (Open Database Connectivity) är en allmänt antagen standard som gör det möjligt för klientprogram att ansluta till och arbeta med data från databaser och stordataplattformar.

Microsoft ODBC Driver för Fabric Data Engineering låter dig koppla in, fråga och hantera Spark-arbetsbelastningar i Fabric med samma tillförlitlighet och enkelhet som ODBC-standarden. Drivrutinen är byggd på Fabric:s Livy-API:er och erbjuder säker och flexibel Spark SQL-anslutning till dina C/C++, .NET, Python och andra ODBC-kompatibla applikationer på Linux.

Viktiga funktioner

• ODBC 3.x-kompatibel: Fullständig implementering av ODBC 3.x-specifikationen.
• Microsoft Entra ID-autentisering: Flera autentiseringsflöden, inklusive Azure CLI, klientuppgifter, certifikatbaserad autentisering och autentisering av åtkomsttoken.
• Stöd för Spark SQL-frågor: Direkt exekvering av Spark SQL-satser.
• Omfattande stöd för datatyper: Stöd för alla Spark SQL-datatyper, inklusive komplexa typer (ARRAY, MAP, och STRUCT).
• Återanvändning av sessioner: Inbyggd sessionshantering för förbättrad prestanda.
• Stöd för stora tabeller: Optimerad hantering för stora resultatuppsättningar med konfigurerbara sidstorlekar.
• Asynkron prefetch: Bakgrundsdata laddas in för förbättrad prestanda.
• Proxystöd: HTTP-proxykonfiguration för företagsmiljöer.
• Multi-schema sjöhusstöd: Anslut till ett specifikt schema inom ett sjöhus.

Förutsättningar

Innan du använder Microsoft ODBC Driver för Microsoft Fabric Data Engineering på Linux, se till att du uppfyller följande förutsättningar:

• Operativsystem: Ubuntu 22.04 eller senare, Debian 11 eller senare, eller Red Hat Enterprise Linux (RHEL) 8 eller senare på x86-64.
• unixODBC: ODBC:s drivrutinshanterare för Linux. Installera unixodbc och unixodbc-dev paketen.
• Fabric access: Tillgång till en Fabric-arbetsplats.
• Microsoft Entra ID-uppgifter: Lämpliga inloggningsuppgifter för autentisering.
• Workspace- och lakehouse-ID:n: GUID-identifierarna för din Fabric-arbetsplats och lakehouse.
• Azure CLI (valfritt): Krävs när du använder Azure CLI-autentisering.

Ladda ner och installera på Linux

Microsoft ODBC Driver för Microsoft Fabric Data Engineering version 1.0.0 finns tillgänglig i offentlig förhandsvisning.

• Ladda ner Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering på Linux (zip)

Så här installerar du drivrutinen:

1. Extrahera ms-sparksql-odbc-linux-1.0.0.zip.

2. Öppna en terminal i den extraherade katalogen.

3. Installera Debian-paketet:

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

Paketet installerar följande filer:

Registrera drivrutinen manuellt

Paketet registrerar automatiskt drivrutinen hos unixODBC. För att registrera drivrutinen manuellt, kör:

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

Kontrollera installationen

Verifiera att drivrutinen är registrerad och att biblioteket är installerat:

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

Kommandot odbcinst ska lista [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Avinstallera drivrutinen

För att avinstallera drivrutinen, kör följande kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Detta kommando tar bort drivrutinsfilerna och avregistrerar drivrutinen från unixODBC.

Snabbstartsexempel

Följande exempel ansluter till Fabric och kör en Spark SQL-fråga. Fyll i förkunskaperna och installera drivrutinen innan du kör ett exempel.

Python-exempel

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

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

Bygg och kör exemplet:

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

.NET-exempel

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 för anslutningssträng

Grundläggande anslutningssträng

Använd följande reťazec pripojenia-format:

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

Anslutningssträngskomponenter

Exempel på anslutningssträngar

Grundläggande anslutning

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

Anslutning till prestandaalternativ

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

Koppling till skogsavverkning

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

Autentisering

Microsoft ODBC Driver för Microsoft Fabric Data Engineering stöder flera autentiseringsmetoder via Microsoft Entra ID. Konfigurera autentisering genom att använda parametern AuthFlow i reťazec pripojenia eller DSN.

Autentiseringsmetoder

Azure CLI-autentisering

Använd Azure CLI-autentisering för utveckling och interaktiva applikationer.

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)

Innan du ansluter, kontrollera att Azure CLI är installerat och logga in:

az --version
az login

För att installera Azure CLI på Debian eller Ubuntu, använd pakethanteraren:

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

Autentisering av klientuppgifter

Använd autentisering av klientuppgifter för automatiserade tjänster och bakgrundsjobb.

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

Ange följande parametrar:

• TenantId: Microsoft Entra-tenant-ID:t.
• ClientId: Applikations-ID (klient).
• ClientSecret: Klienthemligheten.

Lagra hemligheter i en säker hemlig lagring eller miljövariabler. Spara inte hemligheter i klartextanslutningssträngar eller INI-filer.

Certifikatbaserad autentisering

Använd certifikatbaserad autentisering för företagsapplikationer som kräver certifikatuppgifter.

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

Ange följande parametrar:

• TenantId: Microsoft Entra-tenant-ID:t.
• ClientId: Applikations-ID (klient).
• CertificatePath: Vägen till PFX- eller PKCS12-certifikatfilen.
• CertificatePassword: Certifikatlösenordet.

Åtkomsttokenautentisering

Använd autentisering av accesstoken när din applikation skaffar en token via en annan mekanism.

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

Konfigurationsparametrar

Obligatoriska parametrar

Inkludera dessa parametrar i varje reťazec pripojenia:

Valfria parametrar

Anslutningsinställningar

Prestandainställningar

Loggningsinställningar

Proxyinställningar

DSN-konfiguration

På Linux, konfigurera datakällnamn (DSN) i INI-filer istället för i Windows-registret.

Skapa ett DSN

Kopiera den installerade mallen:

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

Redigera ~/.odbc.ini med dina Fabric-arbetsytsdetaljer:

[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

Verifiera DSN

Lista de konfigurerade DSN:erna och testa sedan anslutningen:

odbcinst -q -s
isql -v FabricDSN

Kommandot isql kräver kommandoradsverktygen unixODBC.

Använd DSN i applikationer

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

Användningsexempel

Testa en anslutning med isql

Starta en interaktiv SQL-session:

isql -v FabricDSN

Kör en enda fråga:

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

Arbete med stora resultatmängder

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

Upptäck scheman och tabeller

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

Datatypkartläggning

Drivrutinen mappar Spark SQL-datatyper till ODBC SQL-typer:

Plattformsskillnader

Felsökning

Föraren ej hittad

Problem: Anslutningen misslyckas med [IM002] Data source name not found and no default driver specified.

Lösningar:

1. Verifiera förarregistreringen genom att köra odbcinst -q -d.
2. Kontrollera att det /usr/lib/libmicrosoftfabricodbc.so finns.
3. Registrera föraren genom att köra sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Installera om paketet genom att köra sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN hittades inte

Problem: Anslutningen misslyckas med [IM002] Data source name not found.

Lösningar:

1. Verifiera DSN-konfigurationen genom att köra odbcinst -q -s.
2. Verifiera att det ~/.odbc.ini eller /etc/odbc.ini innehåller DSN-sektionen.
3. Se till att Driver värdet exakt matchar den registrerade förarens namn.

Anslutningsfel

Problem: Drivrutinen kan inte ansluta till Fabric.

Lösningar:

1. Kontrollera att arbetsmiljö-ID:t och lakehouse-ID:t är giltiga GUID:er.
2. Kontrollera Azure CLI-autentisering genom att köra az account show.
3. Se till att du har de nödvändiga behörigheterna för Fabric-arbetsutrymmet.
4. Kolla nätverksanslutning och proxyinställningar.

Autentiseringsfel

Problem: Azure CLI-autentisering misslyckas.

Lösningar:

1. Spring az login för att uppdatera dina inloggningsuppgifter.
2. Sätt rätt prenumeration genom att köra az account set --subscription <subscription-id>.
3. Kontrollera token genom att köra az account get-access-token --resource https://api.fabric.microsoft.com.
4. Se till att ditt konto har de nödvändiga behörigheterna för Fabric-arbetsytan.

Delade biblioteksfel

Problem: Föraren rapporterar error while loading shared libraries: libmicrosoftfabricodbc.so.

Lösningar:

1. Installera om paketet genom att köra sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Kontrollera att det /usr/lib/libmicrosoftfabricodbc.so finns.
3. Kör sudo ldconfig för att uppdatera det delade bibliotekscachen.

Tidsgränser för frågor

Problem: Frågor går ut på stora tabeller.

Lösningar:

1. Lägg till LargeTableSupport=true i anslutningssträngen.
2. Justera PageSizeBytes för resultatstorleken.
3. Lägg till EnableAsyncPrefetch=1 i anslutningssträngen.
4. Använd en LIMIT klausul för att begränsa resultatstorleken.

Aktivera loggning

Aktivera detaljerad loggning i ett DSN:

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

Alternativt, lägg till loggningsparametrar i reťazec pripojenia:

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

Drivrutinen stöder följande logaritmnivåer:

• TRACE: Inkluderar alla API-anrop.
• DEBUG: Innehåller detaljerad felsökningsinformation.
• INFO: Innehåller allmän information och är standard.
• WARN: Innehåller endast varningar.
• ERROR: Innehåller endast fel.

Aktivera unixODBC-spårning

För låg-nivå ODBC-anropsdiagnostik, lägg till följande konfiguration i /etc/odbcinst.ini:

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

Stäng av spårning när du är klar med felsökningen för att undvika onödig prestandabelastning.

Relaterat innehåll

• Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering
• Apache Spark-körtider i Fabric
• Fabric-körmiljö 1.3
• Vad är Livy API för datateknik
• Microsoft JDBC-drivrutin för Microsoft Fabric Data Engineering
• unixODBC