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

ODBC (Open Database Connectivity) er en mye brukt standard som gjør det mulig for klientapplikasjoner å koble til og arbeide med data fra databaser og big data-plattformer.

Microsoft ODBC Driver for Fabric Data Engineering lar deg koble til, spørre og administrere Spark-arbeidsbelastninger i Fabric med påliteligheten og enkelheten til ODBC-standarden. Bygget på Fabric sine Livy-API-er, gir driveren sikker og fleksibel Spark SQL-tilkobling til dine C/C++, .NET, Python og andre ODBC-kompatible applikasjoner på Linux.

Viktige funksjoner

• ODBC 3.x-kompatibel: Full implementering av ODBC 3.x-spesifikasjonen.
• Microsoft Entra ID-autentisering: Flere autentiseringsprosesser, inkludert Azure CLI, klientlegitimasjon, sertifikatbasert autentisering og tilgangstokenautentisering.
• Spark SQL-spørringsstøtte: Direkte kjøring av Spark SQL-setninger.
• Omfattende støtte for datatyper: Støtte for alle Spark SQL-datatyper, inkludert komplekse typer (ARRAY, MAP, og STRUCT).
• Gjenbruk av sesjoner: Innebygd sesjonsadministrasjon for bedre ytelse.
• Støtte for store tabeller: Optimalisert håndtering for store resultatsett med konfigurerbare sidestørrelser.
• Asynkron forhåndshenting: Bakgrunnsdata laster inn for bedre ytelse.
• Proxy-støtte: HTTP-proxykonfigurasjon for bedriftsmiljøer.
• Multi-skjema lakehouse-støtte: Koble til et spesifikt skjema i et lakehouse.

Forutsetninger

Før du bruker Microsoft ODBC-driveren for Microsoft Fabric Data Engineering på Linux, må du sørge for at du har følgende forutsetninger:

• Operativsystem: Ubuntu 22.04 eller nyere, Debian 11 eller nyere, eller Red Hat Enterprise Linux (RHEL) 8 eller nyere på x86-64.
• unixODBC: ODBC-driveradministratoren for Linux. Installer unixodbc og-pakkene unixodbc-dev .
• Fabric access: Tilgang til et Fabric-arbeidsområde.
• Microsoft Entra ID-legitimasjon: Passende legitimasjon for autentisering.
• Workspace- og lakehouse-ID-er: GUID-identifikatorene for din Fabric workspace og lakehouse.
• Azure CLI (valgfritt): Kreves når du bruker Azure CLI-autentisering.

Last ned og installer på Linux

Microsoft ODBC Driver for Microsoft Fabric Data Engineering versjon 1.0.0 er tilgjengelig i offentlig forhåndsvisning.

• Last ned Microsoft ODBC-driver for Microsoft Fabric Data Engineering på Linux (zip)

For å installere driveren:

1. Trekk ut ms-sparksql-odbc-linux-1.0.0.zip.

2. Åpne en terminal i den utpakkede katalogen.

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 å registrere driveren manuelt, kjør:

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

Verifiser installasjonen

Verifiser at driveren er registrert og at biblioteket er installert:

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

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

Avinstaller driveren

For å avinstallere driveren, kjør følgende kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Denne kommandoen fjerner driverfilene og avregistrerer driveren fra unixODBC.

Eksempel på hurtigstart

Følgende eksempler kobler til Fabric og kjører en Spark SQL-spørring. Fullfør forutsetningene og installer driveren før du kjø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;
}

Bygg og kjør eksempelet:

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

Tilkoblingsstrengformat

Grunnleggende tilkoblingsstreng

Bruk følgende tilkoblingsstreng-format:

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

Tilkoblingsstrengkomponenter

Eksempler på tilkoblingsstrenger

Grunnleggende forbindelse

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

Tilkobling med ytelsesalternativer

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 med hogst

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

Godkjenning

Microsoft ODBC-driveren for Microsoft Fabric Data Engineering støtter flere autentiseringsmetoder gjennom Microsoft Entra ID. Konfigurer autentisering ved å bruke parameteren AuthFlow i tilkoblingsstreng eller DSN.

Godkjenningsmetoder

Azure CLI-autentisering

Bruk Azure CLI-autentisering for utviklings- og interaktive applikasjoner.

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 kobler til, sjekk at Azure CLI er installert og logg inn:

az --version
az login

For å installere Azure CLI på Debian eller Ubuntu, bruk pakkebehandleren:

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

Autentisering av klientopplysninger

Bruk autentisering av klientinformasjon for automatiserte tjenester og bakgrunnsjobber.

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

Oppgi følgende parametere:

• TenantId: Microsoft Entra-leietaker-ID.
• ClientId: Applikasjons- (klient-)ID-en.
• ClientSecret: Klientens hemmelighet.

Lagre hemmeligheter i en sikker hemmelig lagring eller miljøvariabler. Ikke lagre hemmeligheter i klartekstforbindelser eller INI-filer.

Sertifikatbasert godkjenning

Bruk sertifikatbasert autentisering for bedriftsapplikasjoner som krever sertifikatlegitimasjon.

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

Oppgi følgende parametere:

• TenantId: Microsoft Entra-leietaker-ID.
• ClientId: Applikasjons- (klient-)ID-en.
• CertificatePath: Veien til PFX- eller PKCS12-sertifikatfilen.
• CertificatePassword: Sertifikatpassordet.

Autentisering av tilgangstoken

Bruk autentisering av tilgangstokenet når applikasjonen din får tak i en token gjennom en annen 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};"
)

Konfigurasjonsparametere

Påkrevde parametere

Inkluder disse parameterne i hver tilkoblingsstreng:

Valgfrie parametere

Tilkoblingsinnstillinger

Ytelsesinnstillinger

Loggingsinnstillinger

Proxy-innstillinger

DSN-konfigurasjon

På Linux, konfigurer datakildenavn (DSN) i INI-filer i stedet for i Windows-registeret.

Opprett et DSN

Kopier den installerte malen:

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

Rediger ~/.odbc.ini med dine Fabric-arbeidsområ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

Verifiser DSN-en

List opp de konfigurerte DSN-ene, og test deretter tilkoblingen:

odbcinst -q -s
isql -v FabricDSN

Kommandoen isql krever kommandolinjeverktøyene unixODBC.

Bruk DSN i applikasjoner

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

Brukseksempler

Test en tilkobling med isql

Start en interaktiv SQL-økt:

isql -v FabricDSN

Kjør én enkelt spørring:

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

Arbeid med store resultatsett

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

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

Tilordning av datatype

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

Plattformforskjeller

Feilsøking

Føreren ikke funnet

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

Løsninger:

1. Verifiser førerregistreringen ved å kjøre odbcinst -q -d.
2. Sjekk at det /usr/lib/libmicrosoftfabricodbc.so finnes.
3. Registrer sjåføren ved å kjøre sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Installer pakken på nytt ved å kjøre sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN ikke funnet

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

Løsninger:

1. Verifiser DSN-konfigurasjonen ved å kjøre odbcinst -q -s.
2. Verifiser at ~/.odbc.ini eller /etc/odbc.ini inneholder DSN-delen.
3. Sørg for at verdien samsvarer Driver nøyaktig med den registrerte sjåførens navn.

Tilkoblingsfeil

Problem: Driveren kan ikke koble til Fabric.

Løsninger:

1. Sjekk at arbeidsplass-ID-en og lakehouse-ID-en er gyldige GUID-er.
2. Sjekk Azure CLI-autentisering ved å kjøre az account show.
3. Sørg for at du har de nødvendige Fabric-arbeidsplasstillatelsene.
4. Sjekk nettverkstilkobling og proxy-innstillinger.

Godkjenningsfeil

Problem: Azure CLI-autentisering feiler.

Løsninger:

1. Løp az login for å oppdatere legitimasjonen din.
2. Sett riktig abonnement ved å kjøre az account set --subscription <subscription-id>.
3. Sjekk tokenet ved å kjøre az account get-access-token --resource https://api.fabric.microsoft.com.
4. Sørg for at kontoen din har de nødvendige Fabric-arbeidsplasstillatelsene.

Delte bibliotekfeil

Problem: Føreren rapporterer error while loading shared libraries: libmicrosoftfabricodbc.so.

Løsninger:

1. Installer pakken på nytt ved å kjøre sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Sjekk at det /usr/lib/libmicrosoftfabricodbc.so finnes.
3. Kjør sudo ldconfig for å oppdatere cachen i det delte biblioteket.

Spørringstidsavbrudd

Problem: Forespørsler går ut på tid på store tabeller.

Løsninger:

1. Legg til LargeTableSupport=true i tilkoblingsstreng.
2. Juster PageSizeBytes for resultatstørrelsen.
3. Legg til EnableAsyncPrefetch=1 i tilkoblingsstreng.
4. Bruk en LIMIT klausul for å begrense resultatstørrelsen.

Aktiver logging

Aktiver detaljert logging i et DSN:

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

Alternativt, legg til loggingsparametere i tilkoblingsstreng:

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

Driveren støtter følgende log-nivåer:

• TRACE: Inkluderer alle API-kall.
• DEBUG: Inkluderer detaljert feilsøkingsinformasjon.
• INFO: Inkluderer generell informasjon og er standard.
• WARN: Inkluderer kun advarsler.
• ERROR: Inneholder kun feil.

Aktiver unixODBC-sporing

For lavnivå ODBC-kalldiagnostikk, legg til følgende konfigurasjon til /etc/odbcinst.ini:

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

Slå av sporing når du er ferdig med feilsøking for å unngå unødvendig ytelsesbelastning.

Relatert innhold

• Microsoft ODBC-driver for Microsoft Fabric Data Engineering
• Apache Spark runtimes i Stoff
• Stoff Kjøretid 1.3
• Hva er Livy API for Data Engineering
• Microsoft JDBC-driver for Microsoft Fabric Data Engineering
• unixODBC