Driver Microsoft ODBC per Microsoft Fabric Data Engineering (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.

Microsoft ODBC Driver for Fabric Data Engineering consente di connettere, eseguire query e gestire carichi di lavoro Spark in Microsoft Fabric con affidabilità e semplicità dello standard ODBC. Basato sulle API Livy di Microsoft Fabric, il driver offre connettività SPARK SQL sicura e flessibile a .NET, Python e altri strumenti di BUSINESS intelligence e applicazioni compatibili con ODBC.

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
• 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 per Lakehouse multi-schema: collegarsi a uno schema specifico all'interno di una Lakehouse
• integrazione di OneLake: i dati di Access Lakehouse archiviati in Microsoft OneLake, incluse le tabelle tra più schemi, tramite un'interfaccia ODBC unificata senza una configurazione di archiviazione separata
• 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+
• Microsoft Fabric Access: accesso a un'area di lavoro di Microsoft Fabric
• credenziali Microsoft Entra ID: credenziali appropriate per l'autenticazione
• ID area di lavoro e Lakehouse: identificatori GUID per il tuo workspace e lakehouse Fabric
• 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

Microsoft ODBC Driver per Microsoft Fabric Data Engineering versione 1.0.0 è disponibile in anteprima pubblica e scaricabile dal seguente link del Centro download.

• 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-1.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-1.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-1.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

In questo esempio viene illustrato come connettersi a Microsoft Fabric ed eseguire una query usando Microsoft ODBC Driver for Microsoft Fabric Data Engineering. Prima di eseguire questo codice, assicurarsi di aver completato i prerequisiti e installato il driver.

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

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

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

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

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

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 è possibile connettersi a Microsoft Fabric

Soluzioni:

1. Verificare che l'ID dell'area di lavoro e l'ID Lakehouse siano GUID 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:

• TRACE: livello di massima verbosità, include tutte le chiamate API
• DEBUG: informazioni dettagliate sul debug
• 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

• 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