Driver ODBC Microsoft per Microsoft Fabric Data Engineering

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. Basato sulle API Livy di Fabric, il driver offre una connettività sicura e flessibile a Spark SQL per le tue applicazioni C/C++, .NET, Python e altre applicazioni compatibili con ODBC, nonché per i tuoi strumenti di BI.

Funzionalità principali

• Conforme a ODBC 3.x: implementazione completa della specifica ODBC 3.x
• Microsoft Entra ID authentication: più flussi di autenticazione, tra cui interfaccia della riga di comando di Azure, interattivo, credenziali client, autenticazione basata su certificato e token di accesso
• Supporto per le query Spark SQL: esecuzione diretta di istruzioni Spark SQL
• Supporto completo dei tipi di dati: supporto per tutti i tipi di dati SPARK SQL, inclusi tipi complessi (ARRAY, MAP, STRUCT)
• Riutilizzo delle sessioni: gestione delle sessioni predefinita per migliorare le prestazioni
• Modalità ad alta concorrenza: Opta per sessioni Livy condivise e calde lato server per ridurre la latenza all'avvio della connessione e la diffusione del cluster Spark
• Supporto di tabelle di grandi dimensioni: gestione ottimizzata per set di risultati di grandi dimensioni con dimensioni di pagina configurabili
• Prelettura asincrona: caricamento dei dati in background per migliorare le prestazioni
• Supporto proxy: configurazione proxy HTTP per ambienti aziendali
• Supporto multi-schema per la casa del lago: Collegarsi a uno schema specifico all'interno di una casa sul lago
• Integrazione OneLake: Accedi ai dati lakehouse memorizzati in OneLake, incluse tabelle su più schemi, tramite un'interfaccia ODBC unificata senza configurazioni di storage separate
• supporto degli elementi dell'ambiente Fabric: Allegare gli elementi dell'ambiente Fabric durante l'esecuzione del processo per applicare le librerie dell'area di lavoro, le proprietà di Spark e le variabili a ogni sessione
• Configurazione di Spark personalizzata: passare le proprietà di configurazione spark direttamente tramite il stringa di connessione per ottimizzare il comportamento della sessione

Prerequisiti

Prima di usare Microsoft ODBC Driver for Microsoft Fabric Data Engineering, assicurarsi di disporre di:

• Sistema operativo: Windows 10/11 o Windows Server 2016+
• Fabric Access: 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: identificatori GUID per il tuo spazio di lavoro Fabric e la casa sul lago
• Interfaccia della riga di comando di Azure (facoltativo): obbligatorio per il metodo di autenticazione dell'interfaccia della riga di comando di Azure

Scaricare e installare MSI

• Scarica Microsoft ODBC Driver for Microsoft Fabric Data Engineering (zip)

1. Scaricare il pacchetto MSI del Microsoft ODBC Driver for Microsoft Fabric Data Engineering.
2. Fare doppio clic su MicrosoftFabricODBCDriver-2.0.msi.
3. Seguire l'installazione guidata e accettare il contratto di licenza
4. Scegliere la directory di installazione (impostazione predefinita: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Completare l'installazione

Installazione silenziosa

# Silent installation
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /l*v install.log

Verifica l'installazione

Dopo l'installazione, verificare che il driver sia registrato:

1. Esegui odbcad32.exe (Amministratore origine dati ODBC)
2. Passare alla scheda Driver
3. Verificare che sia elencato "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"

Esempio di avvio rapido

Questo esempio dimostra come connettersi a Fabric ed eseguire una query utilizzando il driver Microsoft ODBC per Microsoft Fabric Data Engineering. Prima di eseguire questo codice, assicurarsi di aver completato i prerequisiti e installato il driver.

Esempio di C/C++

#include <windows.h>
#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);
    SQLSetEnvAttr(
        environment,
        SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3,
        0);
    SQLAllocHandle(SQL_HANDLE_DBC, environment, &connection);

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

    SQLRETURN result = SQLDriverConnectA(
        connection,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);
        result = SQLExecDirectA(
            statement,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(statement) == SQL_SUCCESS) {
                SQLGetData(
                    statement,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, statement);
        SQLDisconnect(connection);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, connection);
    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Esempio di Python

import pyodbc

# Connection string with required parameters
connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

# Connect and execute query
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 .NET

using System.Data.Odbc;

// Connection string with required parameters
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 della stringa di connessione

Stringa di connessione di base

Microsoft ODBC Driver for Microsoft Fabric Data Engineering usa il formato di stringa di connessione seguente:

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 (autenticazione dell'interfaccia della riga di comando di Azure)

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

Con le opzioni di prestazioni

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

Con la registrazione

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=odbc_driver.log

Con modalità ad alta concorrenza

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

Consulta la sezione modalità High-Concurrency (HC) per istruzioni complete sulla configurazione.

Authentication

Microsoft ODBC Driver for Microsoft Fabric Data Engineering supporta più metodi di autenticazione tramite Microsoft Entra ID (in precedenza Azure Active Directory). L'autenticazione viene configurata usando il AuthFlow parametro nella stringa di connessione.

Metodi di autenticazione

Puoi specificare i valori di autenticazione in snake case maiuscolo, Pascal case o in forma numerica. Il driver accetta anche alias brevi come Browser, Interactive, CLI, Certificate, Token, e File. Il driver ignora i sottolineamenti quando confronta i valori.

Autenticazione dell’interfaccia della riga di comando di Azure

Ideale per: sviluppo e applicazioni interattive

# Python Example
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)

Prerequisites:

• Interfaccia della riga di comando di Azure installata: az --version
• Autenticato: az login

Autenticazione interattiva del browser

Ideale per: applicazioni rivolte agli utenti

# Python Example
connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=INTERACTIVE;"
    "TenantId=<tenant-id>;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Comportamento:

• Apre una finestra del browser per l'autenticazione utente
• Le credenziali vengono memorizzate nella cache per le connessioni successive

Autenticazione delle credenziali client (principale del servizio)

Ideale per: servizi automatizzati e processi 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};"
)

Parametri obbligatori

• TenantId: ID tenant di Azure
• ClientId: ID dell'applicazione (client) di Microsoft Entra ID
• ClientSecret: segreto del client da Microsoft Entra ID

Procedure consigliate

• Archiviare i segreti in modo sicuro (Azure Key Vault, variabili di ambiente)
• Usare le identità gestite quando possibile
• Ruotare regolarmente i segreti

Autenticazione basata su certificati

Ideale per: applicazioni aziendali che richiedono l'autenticazione basata su certificati

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=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

Parametri obbligatori:

• TenantId: ID tenant di Azure
• ClientId: ID applicazione (cliente)
• CertificatePath: percorso del file di certificato PFX/PKCS12
• CertificatePassword: password del certificato

Autenticazione del token di accesso

Ideale per: scenari di autenticazione personalizzati

# Acquire token through custom mechanism
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};"
)

Autenticazione del file token

Usa l'autenticazione tramite file di token per gli ambienti containerizzati e le pipeline automatizzate in cui un altro processo scrive un token bearer nel file di token predefinito del driver:

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

Il driver risolve la posizione del file token su Windows e Linux.

Alias di proprietà cross-driver

Il driver ODBC accetta nomi di proprietà selezionati ADO.NET e JDBC oltre ai nomi ODBC nativi. Questo supporto può ridurre i cambiamenti di stringa di connessione quando si passa tra driver Fabric.

Il driver risolve 17 alias tra driver al momento della connessione.

Parametri di configurazione

Parametri obbligatori

Questi parametri devono essere presenti in ogni stringa di connessione:

Parametri facoltativi

Impostazioni di connessione

Impostazioni delle prestazioni

Impostazioni di registrazione

Impostazioni proxy

Impostazioni ad alta concorrenza (HC)

Utilizzare questi parametri per abilitare e configurare la modalità ad alta concorrenza (HC). La modalità HC è facoltativa. Se non imposti LivyMode o UseHighConcurrency, il driver utilizza il classico percorso a sessione singola. Per indicazioni ed esempi, vedi modalità ad alta concorrenza (HC).

Precedenza modale e validazione

• LivyMode ha la precedenza rispetto UseHighConcurrency a quando imposti entrambi i parametri.
• I valori dei parametri non distinguono tra maiuscole e minuscole.
• UseHighConcurrency accetta true, 1, yes o on per abilitare la modalità HC. Accetta false, 0, no o off per disabilitare la modalità HC.
• Per altri valori non vuoti, SQLDriverConnect restituisce un errore. Solo SQLConnect DSN registra il fallimento di validazione e utilizza il percorso classico.

Impostazioni di compatibilità

Il driver supporta TenantPrincipal e PoolMax, inclusi i corrispondenti valori di fallback tramite variabili di ambiente, per garantire la compatibilità con le precedenti configurazioni HC. Il driver analizza e valida questi valori, ma non influiscono sull'abbinamento delle sessioni HC o sulla capacità del pool runtime. Non affidarti a loro per l'isolamento degli inquilini o i limiti di connessione.

Rilievi variabili ambientali

Il driver utilizza le seguenti variabili di ambiente solo quando il parametro DSN o stringa di connessione corrispondente non è impostato:

Per FABRIC_ODBC_USE_HC, l'abilitazione limitata all'ambiente riconosce true, 1 o yes (senza distinzione tra maiuscole e minuscole). Altri valori mantengono HC disabilitato. Gli on alias e off si applicano solo ai valori DSN e delle stringhe di connessione.

Impostazioni ambiente

È possibile collegare un elemento di ambiente Fabric alla sessione Spark avviata dal driver. Le librerie, le proprietà spark e le variabili dell'ambiente selezionato vengono applicate automaticamente quando viene creata la sessione.

Stringa di connessione di esempio con un item dell'ambiente:

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

Configurazione di Spark personalizzata

È possibile passare le proprietà di configurazione di Spark direttamente nel stringa di connessione. Qualsiasi parametro preceduto spark. da viene applicato automaticamente alla sessione Spark in fase di creazione, consentendo di eseguire l'override delle impostazioni predefinite dell'area di lavoro o del runtime.

Configurazioni spark di esempio:

spark.sql.shuffle.partitions=200
spark.sql.adaptive.enabled=true
spark.sql.autoBroadcastJoinThreshold=10485760

Esempio di stringa di connessione con proprietà Spark personalizzate:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;spark.sql.shuffle.partitions=200;spark.sql.adaptive.enabled=true

Modalità ad alta concorrenza (HC)

La modalità High Concurrency (HC) permette alle connessioni ODBC allo stesso spazio di lavoro e allo stesso lakehouse di collegarsi a sessioni Livy Spark condivise e calde lato server invece di fornire un cluster separato per ogni connessione. Usalo per carichi di lavoro come dashboard BI, kernel di notebook e fan-out ETL che aprono molte connessioni di breve durata e possono condividere la capacità Spark gestita dal server.

La modalità HC è facoltativa. Se non configuri un'impostazione HC, il driver usa il classico percorso a sessione singola.

Scegliere una modalità di connessione

Usa la modalità HC quando:

• Il tuo carico di lavoro apre molte connessioni ODBC di breve durata, come dashboard BI, kernel di notebook o fan-out ETL.
• Le connessioni mirano allo stesso spazio di lavoro e allo stesso lago e possono condividere una sessione Spark gestita dal server.
• Ridurre la latenza di avvio a freddo per connessione è importante.

Usa la modalità classica quando:

• Ogni connessione richiede una sessione Spark isolata a causa delle diverse configurazioni di Spark o di un isolamento rigoroso delle risorse.
• L'endpoint Fabric Livy per lo spazio di lavoro target e lakehouse non supporta la modalità HC.

Abilita la modalità ad alta concorrenza

Aggiungi un parametro per la modalità a elevata concorrenza al DSN o alla stringa di connessione.

Consigliato: Set LivyMode

Usare LivyMode per selezionare esplicitamente la modalità acquisizione sessione:

LivyMode=HighConcurrency

I valori supportati sono Classic, HighConcurrencye Auto. I valori non fanno distinzione tra maiuscole e minuscole. Auto Attualmente seleziona la modalità classica.

Alternativa: Set UseHighConcurrency

Usa l'impostazione booleana per la compatibilità con le configurazioni esistenti:

UseHighConcurrency=true

Per abilitare la modalità ad alta concorrenza, usare true, 1, yes, o on. Per disabilitarla, usa false, 0, no, o off. I valori non fanno distinzione tra maiuscole e minuscole. SQLDriverConnect rifiuta altri valori non vuoti con SQLSTATE HY024. Solo DSN SQLConnect registra l’errore di convalida e utilizza la modalità classica.

Parametri richiesti in modalità HC

L'attivazione HC richiede i seguenti identificatori validi:

Includi SessionTag perché influenza il matching lato server per le sessioni calde.

Abbinamento delle sessioni

La modalità HC non garantisce che ogni connessione riutilizzi una sessione esistente. Per ogni richiesta di acquisizione di sessione, il pilota invia:

• Il valore SessionTag.
• La configurazione effettiva di Spark, inclusi conf.* i parametri e EnvironmentId.

Il servizio Fabric Livy valuta questi valori e decide se collegare la connessione a una sessione calda o crearne una nuova. Per migliorare il riutilizzo delle sessioni, utilizza valori coerenti tra le connessioni che sono destinate a condividere la capacità di Spark gestita dal server.

Esempi di stringhe di connessione

Connessione minima HC (autenticazione interfaccia della riga di comando di Azure):

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

HC con timeout ottimizzati:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

HC con ambiente e sovrascritture della conferenza Spark:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python (pyodbc):

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

Configura la modalità HC in un DSN

Puoi memorizzare le impostazioni HC in un DSN invece di ripeterle in ogni stringa di connessione. Quando una stringa di connessione non specifica un valore, il driver legge queste impostazioni dal DSN:

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

Il driver legge anche le impostazioni di sola compatibilità TenantPrincipal e PoolMax. Per salvare queste impostazioni, modifica il DSN in odbcad32.exe oppure usa SQLWritePrivateProfileString. Usa i nomi dei parametri nella tabella delle impostazioni HC.

Disabilita la modalità HC

Puoi disabilitare l'avvio di nuove sessioni HC senza ridistribuire il driver. Usa il metodo che corrisponde a come hai abilitato la modalità HC:

Le impostazioni della stringa di connessione e del DSN hanno la precedenza rispetto al meccanismo di fallback basato sulle variabili d'ambiente. Questi cambiamenti riguardano solo le nuove connessioni. Le sessioni HC esistenti continuano fino a quando non vengono rilasciate.

Comprendere il comportamento del runtime di HC

• Validazione:SQLDriverConnect rifiuta valori HC booleani e valori interi positivi invalidi con SQLSTATE HY024. Rifiuta un valore LivyMode non valido e valori WorkspaceId, LakehouseId e IdempotencyKey non validi o troppo grandi con SQLSTATE HY000. Un valore di compatibilità TenantPrincipal sovradimensionato restituisce HY000anch'esso . Per la sola SQLConnectDSN, il driver registra i normali fallimenti di validazione HC e utilizza la modalità classica. I valori critici per la sicurezza di dimensioni eccessive continuano ancora a causare il fallimento della connessione.
• Dati sensibili: Il driver esclude o cancella IdempotencyKey altri campi sensibili dai log HC e dagli output diagnostici.
• Cancellazione: La cancellazione dell'estratto conto è cooperativa. Il lavoro sul server già in corso si conclude in modo pulito invece di essere terminato immediatamente.
• Interruttori automatici: Le modalità HC e classica utilizzano interruttori separati. Esaurire una modalità non influisce sull'altra.
• Database iniziale: Le connessioni HC non eseguono l'istruzione iniziale USE per il Database parametro. Esegui USE <database> dopo esserti connesso oppure usa nomi di tabella completamente qualificati.
• Diagnostica: Impostare LogLevel=DEBUG per registrare l'acquisizione HC, il polling, il rilascio e le decisioni di mappatura degli errori. Per una risoluzione mirata dei problemi, configura LIVY_HC_VERBOSE=1 per includere ulteriori diagnostiche HC HTTP ripulite.

Configura un DSN

Creare un DSN di sistema

1. Aprire l'amministratore ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Creare un nuovo DSN di sistema

   • Passare alla scheda "DSN di sistema"
   • Selezionare "Aggiungi"
   • Selezionare "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
   • Selezionare "Fine"

3. Configurare le impostazioni DSN

   • Nome origine dati: immettere un nome univoco (ad esempio, FabricODBC)
   • Descrizione: Descrizione facoltativa
   • ID area di lavoro: GUID del workspace di Fabric
   • ID Lakehouse: GUID del lakehouse di Fabric
   • Autenticazione: selezionare il metodo di autenticazione
   • ID ambiente (facoltativo): inserire il GUID dell'ambiente Fabric da collegare durante la creazione della sessione
   • Modalità Livio (opzionale): impostato su HighConcurrency per abilitare la modalità HC
   • Tag di sessione (opzionale): Inserisci un'etichetta operativa non sensibile per la corrispondenza della sessione HC
   • Configurare impostazioni aggiuntive in base alle esigenze

4. Test connessione

   • Selezionare "Test connessione" per verificare le impostazioni
   • Selezionare "OK" per salvare

Usare DSN nelle applicazioni

# Python - Connect using DSN
conn = pyodbc.connect("DSN=FabricODBC")

// .NET - Connect using DSN
using var connection = new OdbcConnection("DSN=FabricODBC");
await connection.OpenAsync();

Esempi di utilizzo

Query e connessione di base

Pitone

import pyodbc

def main():
    connection_string = (
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;"
        "ReuseSession=true;"
    )
    
    conn = pyodbc.connect(connection_string, timeout=30)
    cursor = conn.cursor()
    
    print("Connected successfully!")
    
    # Show available tables
    print("\nAvailable tables:")
    cursor.execute("SHOW TABLES")
    for row in cursor.fetchall():
        print(f"  {row}")
    
    # Query data
    print("\nQuery results:")
    cursor.execute("SELECT * FROM employees LIMIT 10")
    
    # Print column names
    columns = [desc[0] for desc in cursor.description]
    print(f"Columns: {columns}")
    
    # Print rows
    for row in cursor.fetchall():
        print(row)
    
    conn.close()

if __name__ == "__main__":
    main()

.NET

using System.Data.Odbc;

class Program
{
    static async Task Main(string[] args)
    {
        string connectionString = 
            "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
            "WorkspaceId=<workspace-id>;" +
            "LakehouseId=<lakehouse-id>;" +
            "AuthFlow=AZURE_CLI;" +
            "ReuseSession=true;";

        using var connection = new OdbcConnection(connectionString);
        await connection.OpenAsync();
        
        Console.WriteLine("Connected successfully!");

        // Show available tables
        Console.WriteLine("\nAvailable tables:");
        using (var cmd = new OdbcCommand("SHOW TABLES", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine($"  {reader.GetString(0)}");
            }
        }

        // Query data
        Console.WriteLine("\nQuery results:");
        using (var cmd = new OdbcCommand("SELECT * FROM employees LIMIT 10", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            // Print column names
            var columns = new List<string>();
            for (int i = 0; i < reader.FieldCount; i++)
            {
                columns.Add(reader.GetName(i));
            }
            Console.WriteLine($"Columns: {string.Join(", ", columns)}");

            // Print rows
            while (await reader.ReadAsync())
            {
                var values = new object[reader.FieldCount];
                reader.GetValues(values);
                Console.WriteLine(string.Join("\t", values));
            }
        }
    }
}

Utilizzo di set di risultati di grandi dimensioni

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;"  # 18 MB pages
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

# Execute large query
cursor.execute("SELECT * FROM large_table")

# Process in batches
row_count = 0
while True:
    rows = cursor.fetchmany(1000)  # Fetch 1000 rows at a time
    if not rows:
        break
    
    for row in rows:
        # Process row
        row_count += 1
        
    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

Esecuzione delle istruzioni DML

bool executeDml(SQLHDBC connection, const char* sql, const char* description) {
    SQLHSTMT statement = SQL_NULL_HSTMT;
    SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);

    std::cout << "Executing: " << description << std::endl;
    SQLRETURN result = SQLExecDirectA(
        statement,
        (SQLCHAR*)sql,
        SQL_NTS);

    bool succeeded = SQL_SUCCEEDED(result);
    if (succeeded) {
        SQLLEN rowCount;
        SQLRowCount(statement, &rowCount);
        std::cout << "Rows affected: " << rowCount << std::endl;
    }

    SQLFreeHandle(SQL_HANDLE_STMT, statement);
    return succeeded;
}

Usa executeDml con le istruzioni INSERT, UPDATE o DELETE. Il conteggio delle righe segnalato dipende dal fatto che il risultato contenga un conteggio degli aggiornamenti riconosciuto dal driver.

Rilevazione dello schema

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

# List all tables
print("Tables in current default schema / database:")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
for table in tables:
    print(f"  {table}")

# Describe table structure
print("\nTable structure for 'employees':")
cursor.execute("DESCRIBE employees")
for col in cursor.fetchall():
    print(f"  {col}")

# List schemas (for multi-schema Lakehouses)
print("\nAvailable schemas:")
cursor.execute("SHOW SCHEMAS")
for db in cursor.fetchall():
    print(f"  {db}")

conn.close()

Mappatura del tipo di dati

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

Integrazione degli strumenti di business intelligence

Microsoft Excel

1. Aprire Excel -> Dati -> Recupera dati -> Da altre origini -> Da ODBC
2. Selezionare il DSN configurato (ad esempio, FabricODBC)
3. Eseguire l'autenticazione se richiesto
4. Esplorare e selezionare le tabelle
5. Caricare i dati nel foglio di lavoro di Excel

Power BI Desktop per analisi dati

1. Aprire Power BI Desktop -> Recupera dati -> ODBC
2. Selezionare il DSN configurato
3. Esplorare il catalogo dati e selezionare le tabelle
4. Trasformare i dati in base alle esigenze
5. Creare visualizzazioni

SQL Server Management Studio (server collegato)

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

Risoluzione dei problemi

In questa sezione vengono fornite indicazioni per la risoluzione dei problemi comuni che possono verificarsi quando si usa Microsoft ODBC Driver for Microsoft Fabric Data Engineering.

Problemi comuni

Le sezioni seguenti descrivono i problemi comuni e le relative soluzioni:

Errori di connessione

Problema: Non riesco a collegarsi a Fabric

Soluzioni:

1. Verifica che l'ID dello spazio di lavoro e l'ID della casa del lago siano i GID corretti
2. Controllare l'autenticazione della CLI di Azure: az account show
3. Assicurati di possedere le autorizzazioni appropriate per l'area di lavoro Fabric.
4. Controllare la connettività di rete e le impostazioni proxy

Errori di autenticazione

Problema: l'autenticazione non riesce con l'interfaccia della riga di comando di Azure

Soluzioni:

• Eseguire az login per aggiornare le credenziali
• Verificare il tenant corretto: az account set --subscription <subscription-id>
• Controllare la validità del token: az account get-access-token --resource https://api.fabric.microsoft.com

Timeout query

Problema: timeout delle query su tabelle di grandi dimensioni

Soluzioni:

• Abilitare LargeTableSupport=true
• Regolare PageSizeBytes per la dimensione ottimale del blocco
• Abilitare la lettura asincrona: EnableAsyncPrefetch=1
• Usare LIMIT la clausola per limitare le dimensioni dei risultati

Abilitare la registrazione

Durante la risoluzione dei problemi, l'abilitazione della registrazione dettagliata consente di identificare la causa radice dei problemi. È possibile abilitare la registrazione tramite la stringa di connessione.

Per abilitare la registrazione dettagliata:

LogLevel=DEBUG;LogFile=C:\temp\odbc_driver_debug.log;

Livelli di log:

• DEBUG: Informazioni di debug dettagliate e il livello di log del driver più dettagliato
• INFO: informazioni generali (impostazione predefinita)
• WARN: Solo avvertimenti
• ERROR: solo errori

Tracciamento ODBC

Per la diagnostica di basso livello, è possibile abilitare la traccia ODBC di Windows per acquisire chiamate API ODBC dettagliate e il comportamento del driver. Ricordarsi di disattivare il tracciamento quando non è necessario per mantenere prestazioni ottimali.

Per abilitare la traccia ODBC:

1. Apri odbcad32.exe
2. Passare alla scheda "Traccia"
3. Impostare il percorso del file di traccia (ad esempio, C:\temp\odbctrace.log)
4. Selezionare "Avvia traccia adesso"
5. Riprodurre il problema
6. Selezionare "Arresta traccia adesso"

Contenuti correlati

• Microsoft ODBC Driver per Microsoft Fabric Data Engineering su Linux
• 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