Driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux (Anteprima)

ODBC (Open Database Connectivity) è uno standard ampiamente adottato che consente alle applicazioni client di connettersi e lavorare con i dati provenienti da database e piattaforme Big Data.

Il driver Microsoft ODBC per Fabric Data Engineering ti permette di connettere, interrogare e gestire carichi di lavoro Spark in Fabric con l'affidabilità e la semplicità dello standard ODBC. Costruito sulle API Livy di Fabric, il driver offre connettività Spark SQL sicura e flessibile per le tue applicazioni compatibili con C/C++, .NET, Python e altre compatibili ODBC su Linux.

Funzionalità principali

• Conforme a ODBC 3.x: Implementazione completa della specifica ODBC 3.x.
• Autenticazione Microsoft Entra ID: Flussi di autenticazione multipli, inclusi interfaccia della riga di comando di Azure, credenziali client, certificati e autenticazione tramite token di accesso.
• Supporto alle query Spark SQL: esecuzione diretta delle istruzioni SQL di Spark.
• Supporto completo dei tipi di dati: Supporto per tutti i tipi di dati SQL di Spark, inclusi i tipi complessi (ARRAY, MAP, e STRUCT).
• Riutilizzo della sessione: gestione delle sessioni integrata per migliorare le prestazioni.
• Supporto per tabelle grandi: gestione ottimizzata per grandi set di risultati con dimensioni di pagina configurabili.
• Preprefezione asincrona: caricamento dati in background per migliorare le prestazioni.
• Supporto proxy: configurazione proxy HTTP per ambienti aziendali.
• Supporto multi-schema per la casa sul lago: collegati a uno schema specifico all'interno di una casa sul lago.

Prerequisiti

Prima di utilizzare il driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux, assicurati di avere i seguenti prerequisiti:

• Sistema operativo: Ubuntu 22.04 o successiva, Debian 11 o successiva, o Red Hat Enterprise Linux (RHEL) 8 o successivamente su x86-64.
• unixODBC: Il gestore di driver ODBC per Linux. Installa i unixodbc pacchetti e.unixodbc-dev
• Accesso Fabric: Accesso a uno spazio di lavoro Fabric.
• Credenziali Microsoft Entra ID: Credenziali appropriate per l'autenticazione.
• ID dello spazio di lavoro e della casa sul lago: gli identificatori GUID per il tuo spazio di lavoro Fabric e la casa sul lago.
• interfaccia della riga di comando di Azure (opzionale): Richiesta quando si utilizza l'autenticazione interfaccia della riga di comando di Azure.

Scarica e installa su Linux

Il driver Microsoft ODBC per Microsoft Fabric Data Engineering versione 1.0.0 è disponibile in anteprima pubblica.

• Scarica il driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux (zip)

Per installare il driver:

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

2. Apri un terminale nella directory estratta.

3. Installa il pacchetto Debian:

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

Il pacchetto installa i seguenti file:

Registrare manualmente il driver

Il package registra automaticamente il driver con unixODBC. Per registrare manualmente il driver, esegui:

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

Verificare l'installazione

Verifica che il driver sia registrato e che la libreria sia installata:

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

Il odbcinst comando dovrebbe elencare [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Disinstalla il driver

Per disinstallare il driver, esegui il seguente comando:

sudo dpkg -r microsoft-fabric-odbc-driver

Questo comando rimuove i file del driver e disregistra il driver da unixODBC.

Esempio di avvio rapido

I seguenti esempi si collegano a Fabric ed eseguino una query SQL di Spark. Completa i prerequisiti e installa il driver prima di eseguire un esempio.

esempio di Python

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

Esempio di C/C++

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

Costruisci e esegui l'esempio:

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

esempio di .NET

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

Formato stringa di connessione

Stringa di connessione di base

Usa il seguente formato di stringa di connessione:

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

Componenti della stringa di connessione

Esempi di stringhe di connessione

Connessione di base

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

Connessione con le opzioni di prestazione

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

Connessione con il logging

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

Il driver Microsoft ODBC per Microsoft Fabric Data Engineering supporta più metodi di autenticazione tramite Microsoft Entra ID. Configura l'autenticazione usando il parametro AuthFlow nella stringa di connessione o DSN.

Metodi di autenticazione

Autenticazione dell’interfaccia della riga di comando di Azure

Usa l'autenticazione interfaccia della riga di comando di Azure per lo sviluppo e le applicazioni interattive.

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)

Prima di connetterti, verifica che interfaccia della riga di comando di Azure sia installata e accedi:

az --version
az login

Per installare interfaccia della riga di comando di Azure su Debian o Ubuntu, usa il gestore di pacchetti:

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

Autenticazione delle credenziali client

Usa l'autenticazione delle credenziali del client per servizi automatizzati e lavori in background.

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

Fornire i parametri seguenti:

• TenantId: L'ID tenant di Microsoft Entra.
• ClientId: ID dell'applicazione (client).
• ClientSecret: Il segreto del cliente.

Memorizza i segreti in un archivio segreto sicuro o in variabili di ambiente. Non memorizzare segreti in stringhe di connessione in testo semplice o file INI.

Autenticazione basata su certificati

Utilizzare l'autenticazione basata su certificati per applicazioni aziendali che richiedono credenziali di certificazione.

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

Fornire i parametri seguenti:

• TenantId: L'ID tenant di Microsoft Entra.
• ClientId: ID dell'applicazione (client).
• CertificatePath: Il percorso verso il file di certificati PFX o PKCS12.
• CertificatePassword: La password del certificato.

Autenticazione del token di accesso

Usa l'autenticazione del token di accesso quando la tua applicazione acquisisce un token tramite un altro meccanismo.

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

Parametri di configurazione

Parametri obbligatori

Includere questi parametri in ogni stringa di connessione:

Parametri facoltativi

Impostazioni di connessione

Impostazioni delle prestazioni

Impostazioni di registrazione

Impostazioni proxy

Configurazione DSN

Su Linux, configura i nomi delle sorgenti dati (DSN) nei file INI invece che nel registro Windows.

Creare una DSN

Copia il modello installato:

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

Modifica ~/.odbc.ini con i dettagli del tuo spazio di lavoro Fabric:

[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

Verifica il DSN

Elenca le DSN configurate e poi testa la connessione:

odbcinst -q -s
isql -v FabricDSN

Il isql comando richiede gli strumenti a riga di comando unixODBC.

Usa una DSN nelle applicazioni

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

Esempi di utilizzo

Testa una connessione con isql

Inizia una sessione SQL interattiva:

isql -v FabricDSN

Esegui una singola query:

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

Lavoro con grandi insiemi di risultati

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

Scopri schemi e tabelle

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

Mappatura del tipo di dati

Il driver esegue il mapping dei tipi di dati Spark SQL ai tipi SQL ODBC:

Differenze tra le piattaforme

Troubleshooting

Conducente non trovato

Problema: La connessione fallisce con [IM002] Data source name not found and no default driver specified.

Soluzioni:

1. Verifica la registrazione dei conducenti eseguendo odbcinst -q -d.
2. Verificare che /usr/lib/libmicrosoftfabricodbc.so esista.
3. Registra il conducente facendo eseguire sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Reinstalla il pacchetto eseguendo sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN non trovato

Problema: La connessione fallisce con [IM002] Data source name not found.

Soluzioni:

1. Verifica la configurazione DSN eseguendo odbcinst -q -s.
2. Verifica che ~/.odbc.ini o /etc/odbc.ini che contenga la sezione DSN.
3. Assicurati che il Driver valore corrisponda esattamente al nome del conducente registrato.

Errori di connessione

Problema: il driver non riesce a collegarsi a Fabric.

Soluzioni:

1. Verifica che l'ID dello spazio di lavoro e l'ID del lacon siano GUID validi.
2. Controlla l'autenticazione interfaccia della riga di comando di Azure eseguendo az account show.
3. Assicurati di avere i permessi necessari per lo spazio di lavoro Fabric.
4. Controlla la connettività di rete e le impostazioni del proxy.

Errori di autenticazione

Problema: l'autenticazione interfaccia della riga di comando di Azure fallisce.

Soluzioni:

1. Corri az login a rinfrescare le tue credenziali.
2. Imposta l'abbonamento corretto eseguendo az account set --subscription <subscription-id>.
3. Controlla il token eseguendo az account get-access-token --resource https://api.fabric.microsoft.com.
4. Assicurati che il tuo account abbia i permessi necessari per lo spazio di lavoro Fabric.

Errori nella libreria condivisa

Problema: Il conducente segnala error while loading shared libraries: libmicrosoftfabricodbc.so.

Soluzioni:

1. Reinstalla il pacchetto eseguendo sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Verificare che /usr/lib/libmicrosoftfabricodbc.so esista.
3. Esegui sudo ldconfig per aggiornare la cache della libreria condivisa.

Timeout delle query

Problema: le query si esauriscono su tabelle grandi.

Soluzioni:

1. Aggiungere LargeTableSupport=true alla stringa di connessione.
2. Aggiusta PageSizeBytes per la dimensione del risultato.
3. Aggiungere EnableAsyncPrefetch=1 alla stringa di connessione.
4. Usa una LIMIT clausola per limitare la dimensione del risultato.

Abilitare la registrazione

Abilita il logging dettagliato in una DSN:

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

In alternativa, aggiungi parametri di logging alla stringa di connessione:

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

Il driver supporta i seguenti livelli log:

• TRACE: Include tutte le chiamate API.
• DEBUG: Include informazioni dettagliate sul debug.
• INFO: Include informazioni generali ed è il valore predefinito.
• WARN: Include solo avvertimenti.
• ERROR: Include solo errori.

Abilita il tracciamento unixODBC

Per la diagnostica delle chiamate ODBC di basso livello, aggiungere la seguente configurazione a /etc/odbcinst.ini:

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

Disattiva il tracciamento quando hai finito di risolvere i problemi per evitare sovraccarichi di prestazioni inutili.

Contenuti correlati

• Driver ODBC di Microsoft per Microsoft Fabric Data Engineering
• Runtime di Apache Spark in Fabric
• Runtime Fabric 1.3
• Informazioni sull'API Livy per ingegneria dei dati
• Microsoft JDBC Driver per Microsoft Fabric Data Engineering
• unixODBC