Microsoft ODBC-driver til Microsoft Fabric Data Engineering på Linux (Forhåndsvisning)

ODBC (Open Database Connectivity) er en bredt anvendt standard, der gør det muligt for klientapplikationer at forbinde til og arbejde med data fra databaser og big data-platforme.

Microsoft ODBC Driver for Fabric Data Engineering lader dig forbinde, forespørge og administrere Spark-arbejdsbelastninger i Fabric med pålideligheden og enkelheden fra ODBC-standarden. Drevet er bygget på Fabric's Livy API'er og leverer sikker og fleksibel Spark SQL-forbindelse til dine C/C++, .NET, Python og andre ODBC-kompatible applikationer på Linux.

Nøglefunktioner

• ODBC 3.x-kompatibel: Fuld implementering af ODBC 3.x-specifikationen.
• Microsoft Entra ID-autentificering: Flere autentificeringsflows, herunder Azure CLI, klientoplysninger, certifikatbaseret og adgangstoken-autentificering.
• Spark SQL-forespørgselsunderstøttelse: Direkte udførelse af Spark SQL-sætninger.
• Omfattende understøttelse af datatyper: Understøttelse af alle Spark SQL-datatyper, inklusive komplekse typer (ARRAY, MAP, og STRUCT).
• Genbrug af sessioner: Indbygget sessionstyring for forbedret ydeevne.
• Understøttelse af store tabel: Optimeret håndtering af store resultatsæt med konfigurerbare sidestørrelser.
• Asynkron prefetch: Indlæsning af baggrundsdata for forbedret ydeevne.
• Proxy-understøttelse: HTTP-proxykonfiguration til virksomhedsmiljøer.
• Multi-schema lakehouse-support: Forbind til et specifikt skema inden for et lakehouse.

Forudsætninger

Før du bruger Microsoft ODBC Driver til Microsoft Fabric Data Engineering på Linux, skal du sikre dig, at du opfylder følgende forudsætninger:

• Operativsystem: Ubuntu 22.04 eller nyere, Debian 11 eller nyere, eller Red Hat Enterprise Linux (RHEL) 8 eller senere på x86-64.
• unixODBC: ODBC's drivermanager til Linux. Installer og-pakkerne unixodbcunixodbc-dev .
• Fabric access: Adgang til et Fabric-arbejdsområde.
• Microsoft Entra ID-legitimationsoplysninger: Passende legitimationsoplysninger til autentificering.
• Workspace- og lakehouse-ID'er: GUID-identifikatorerne for dit Fabric-arbejdsområde og lakehouse.
• Azure CLI (valgfrit): Påkrævet, når du bruger Azure CLI-autentificering.

Download og installer på Linux

Microsoft ODBC Driver for Microsoft Fabric Data Engineering version 1.0.0 er tilgængelig i offentlig forhåndsvisning.

• Download Microsoft ODBC Driver til Microsoft Fabric Data Engineering på Linux (zip)

For at installere driveren:

1. Udtræk ms-sparksql-odbc-linux-1.0.0.zip.

2. Åbn en terminal i den udpakkede mappe.

3. Installer Debian-pakken:

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

Pakken installerer følgende filer:

Registrer driveren manuelt

Pakken registrerer automatisk driveren hos unixODBC. For at registrere driveren manuelt, kør:

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

Verificér installationen

Kontroller at driveren er registreret, og at biblioteket er installeret:

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

Kommandoen odbcinst skal vise [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Afinstaller driveren

For at afinstallere driveren, kør følgende kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Denne kommando fjerner driverfilerne og afregistrerer driveren fra unixODBC.

Eksempel på hurtigstart

Følgende eksempler forbinder til Fabric og kører en Spark SQL-forespørgsel. Gennemfør forudsætningerne og installer driveren, før du kører et eksempel.

Python-eksempel

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

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

Byg og kør eksemplet:

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

.NET-eksempel

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

Forbindelsesstrengsformat

Grundlæggende forbindelsesstreng

Brug følgende forbindelsesstreng-format:

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

Forbindelsesstrengskomponenter

Eksempel på forbindelsesstrenge

Grundlæggende forbindelse

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

Forbindelse med performance-muligheder

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

Forbindelse til skovhugning

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

Godkendelse

Microsoft ODBC Driver for Microsoft Fabric Data Engineering understøtter flere autentificeringsmetoder via Microsoft Entra ID. Konfigurér autentificering ved at bruge parameteren AuthFlow i forbindelsesstreng eller DSN.

Godkendelsesmetoder

Azure CLI authentication

Brug Azure CLI-autentificering til udvikling og interaktive 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)

Før du forbinder, skal du sikre dig, at Azure CLI er installeret, og log ind:

az --version
az login

For at installere Azure CLI på Debian eller Ubuntu, brug pakkehåndteringen:

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

Klientlegitimationsautentificering

Brug kundelegitimationsgodkendelse til automatiserede tjenester og baggrundsjobs.

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

Angiv følgende parametre:

• TenantId: Microsoft Entra lejer-ID.
• ClientId: Applikations-(klient-)ID'et.
• ClientSecret: Klientens hemmelighed.

Gem hemmeligheder i en sikker hemmelig butik eller miljøvariable. Gem ikke hemmeligheder i klartekst-forbindelsesstrenge eller INI-filer.

Certifikatbaseret godkendelse

Brug certifikatbaseret autentificering til virksomhedsapplikationer, der kræver certifikatoplysninger.

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

Angiv følgende parametre:

• TenantId: Microsoft Entra lejer-ID.
• ClientId: Applikations-(klient-)ID'et.
• CertificatePath: Stien til PFX- eller PKCS12-certifikatfilen.
• CertificatePassword: Certifikatets adgangskode.

Adgangstoksgodkendelse

Brug adgangstoken-autentificering, når din applikation får en token gennem en anden mekanisme.

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

Konfigurationsparametre

Påkrævede parametre

Inkluder disse parametre i hver forbindelsesstreng:

Valgfrie parametre

Forbindelsesindstillinger

Ydelsesindstillinger

Logningsindstillinger

Proxy-indstillinger

DSN-konfiguration

På Linux konfigureres datakildenavne (DSN'er) i INI-filer i stedet for i Windows-registret.

Opret et DSN

Kopier den installerede skabelon:

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

Rediger ~/.odbc.ini med dine Fabric-arbejdsområdedetaljer:

[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

Verificér DSN

List de konfigurerede DSN'er, og test derefter forbindelsen:

odbcinst -q -s
isql -v FabricDSN

Kommandoen isql kræver kommandolinjeværktøjerne unixODBC.

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

Eksempler på anvendelse

Test en forbindelse med isql

Start en interaktiv SQL-session:

isql -v FabricDSN

Kør en enkelt forespørgsel:

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

Arbejde med store resultatsæt

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

Opdag skemaer og 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()

Datatypetilknytning

Driveren mapper Spark SQL-datatyper til ODBC SQL-typer:

Platformforskelle

Fejlfinding

Chauffør ikke fundet

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

Løsninger:

1. Verificér førerregistreringen ved at køre odbcinst -q -d.
2. Bekræfte at det /usr/lib/libmicrosoftfabricodbc.so findes.
3. Registrer føreren ved at køre sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Geninstaller pakken ved at køre sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN ikke fundet

Problem: Forbindelsen fejler med [IM002] Data source name not found.

Løsninger:

1. Verificér DSN-konfigurationen ved at køre odbcinst -q -s.
2. Bekræft at ~/.odbc.ini det indeholder /etc/odbc.ini DSN-sektionen.
3. Sørg for, at værdien Driver præcist matcher den registrerede førers navn.

Forbindelsesfejl

Problem: Driveren kan ikke forbinde til Fabric.

Løsninger:

1. Bekræft, at arbejdsområde-ID'et og lakehouse-ID'et er gyldige GUID'er.
2. Tjek Azure CLI-autentificering ved at køre az account show.
3. Sørg for, at du har de nødvendige tilladelser til Fabric workspace.
4. Tjek netværksforbindelse og proxyindstillinger.

Godkendelsesfejl

Problem: Azure CLI-autentificering fejler.

Løsninger:

1. Løb az login for at opdatere dine legitimationsoplysninger.
2. Sæt det korrekte abonnement ved at køre az account set --subscription <subscription-id>.
3. Tjek tokenet ved at køre az account get-access-token --resource https://api.fabric.microsoft.com.
4. Sørg for, at din konto har de nødvendige Fabric-arbejdsområde-tilladelser.

Delte biblioteksfejl

Problem: Chaufføren rapporterer error while loading shared libraries: libmicrosoftfabricodbc.so.

Løsninger:

1. Geninstaller pakken ved at køre sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Bekræfte at det /usr/lib/libmicrosoftfabricodbc.so findes.
3. Kør sudo ldconfig for at opdatere cachen til det delte bibliotek.

Timeout for forespørgsler

Problem: Forespørgsler går ud på store tabeller.

Løsninger:

1. Tilføj LargeTableSupport=true til forbindelsesstreng.
2. Juster PageSizeBytes for resultatstørrelsen.
3. Tilføj EnableAsyncPrefetch=1 til forbindelsesstreng.
4. Brug en LIMIT klausul til at begrænse resultatstørrelsen.

Aktiver logning

Aktiver detaljeret logning i et DSN:

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

Alternativt kan du tilføje logningsparametre til forbindelsesstreng:

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

Driveren understøtter følgende log-niveauer:

• TRACE: Inkluderer alle API-kald.
• DEBUG: Indeholder detaljeret information om fejlfinding.
• INFO: Indeholder generel information og er standarden.
• WARN: Indeholder kun advarsler.
• ERROR: Indeholder kun fejl.

Aktivér unixODBC-sporing

For lavniveau ODBC-kaldsdiagnostik, tilføj følgende konfiguration til /etc/odbcinst.ini:

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

Slå sporing fra, når du er færdig med fejlfinding, for at undgå unødvendigt ydelsesmæssigt overhead.

Relateret indhold

• Microsoft ODBC-driver til Microsoft Fabric Data Engineering
• Apache Spark-runtimes i Fabric
• Stof Driftstid 1.3
• Hvad er Livy API til Data Engineering
• Microsoft JDBC Driver til Microsoft Fabric Data Engineering
• unixODBC