Condividi tramite


Microsoft ODBC Driver for Microsoft Fabric Data Engineering (anteprima)

Importante

Questa funzionalità si trova in 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
  • Autenticazione ID Microsoft Entra: più flussi di autenticazione, tra cui Azure CLI, interattiva, credenziali client, autenticazione basata su certificati e token di accesso
  • Supporto alle query SQL di Spark: esecuzione diretta di istruzioni SQL di Spark
  • 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 incorporata per migliorare le prestazioni
  • Supporto per 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 di Multi-Schema Lakehouse: connettersi a uno schema specifico all'interno di una Lakehouse

Annotazioni

In Apache Spark open source, il database e lo schema vengono usati come sinonimi. Ad esempio, l'esecuzione di SHOW SCHEMAS o SHOW DATABASES in un notebook di Fabric restituisce lo stesso risultato, ovvero un elenco di tutti gli schemi in Lakehouse.

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
  • Azure Entra ID Credentials: 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

Download e installazione 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.

  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 invisibile all'utente

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

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

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

Componente Descrzione Example
AUTISTA Identificatore del driver ODBC {Microsoft ODBC Driver for Microsoft Fabric Data Engineering}
WorkspaceId Identificatore dell'area di lavoro di Microsoft Fabric (GUID) xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
LakehouseId Identificatore Microsoft Fabric lakehouse (GUID) xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
AuthFlow Metodo di autenticazione AZURE_CLI, INTERACTIVE, CLIENT_CREDENTIAL, , CLIENT_CERTIFICATE, ACCESS_TOKEN

Stringhe di connessione di esempio

Connessione di base (autenticazione CLI 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 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

Valore AuthFlow Descrzione
AZURE_CLI Sviluppo con le credenziali dell'interfaccia della riga di comando di Azure
INTERACTIVE Autenticazione interattiva basata su browser
CLIENT_CREDENTIAL Principale del servizio con segreto del client
CLIENT_CERTIFICATE Principale del servizio con certificato
ACCESS_TOKEN Token di accesso a portatore pre-acquisito

Autenticazione CLI 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 del 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:

Parametro TIPO Descrzione Example
WorkspaceId UUID (Identificatore Unico Universale) Identificatore dell'area di lavoro di Microsoft Fabric 4bbf89a8-...
LakehouseId UUID (Identificatore Unico Universale) Identificatore del lakehouse di Microsoft Fabric d8faa650-...
AuthFlow string Tipo di flusso di autenticazione AZURE_CLI

Parametri facoltativi

Impostazioni di connessione

Parametro TIPO Predefinito Descrzione
Banca dati string None Database specifico a cui collegarsi
Ambito string https://api.fabric.microsoft.com/.default Ambito OAuth

Impostazioni delle prestazioni

Parametro TIPO Predefinito Descrzione
RiutilizzaSessione Boolean true Riutilizzare la sessione Spark esistente
LargeTableSupport Boolean false Abilitare le ottimizzazioni per set di risultati di grandi dimensioni
EnableAsyncPrefetch Boolean false Abilitare la prelettura dei dati in background
DimensionePaginaByte Integer 18874368 (18 MB) Dimensioni pagina per la paginazione dei risultati (1-18 MB)

Impostazioni di registrazione

Parametro TIPO Predefinito Descrzione
LogLevel string INFO Livello di log: TRACE, DEBUG, INFO, WARN, ERROR
Logfile string odbc_driver.log Percorso del file di log (assoluto o relativo)

Impostazioni proxy

Parametro TIPO Predefinito Descrzione
UseProxy Boolean false Abilitare il proxy
ProxyHost string None Nome host proxy
ProxyPort Integer None Porta proxy
ProxyUsername string None Nome utente autenticazione proxy
ProxyPassword string None Password di autenticazione proxy

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"
    • Fare clic su "Aggiungi"
    • Selezionare "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
    • Fare clic su "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
    • Configurare impostazioni aggiuntive in base alle esigenze
  4. Test connessione

    • Fare clic su "Test connessione" per verificare le impostazioni
    • Fare clic su "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

Connessione e query 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()

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

Mapping dei tipi di dati

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

Tipo SQL Spark Tipo SQL ODBC Tipo C/C++ Tipo Python Tipo di .NET
BOOLEAN SQL_BIT SQLCHAR bool bool
BYTE SQL_TINYINT SQLSCHAR int sbyte
BREVE SQL_SMALLINT SQLSMALLINT int short
INT SQL_INTEGER SQLINTEGER int int
LONG SQL_BIGINT SQLBIGINT int lungo
FLOAT SQL_REAL SQLREAL galleggiare galleggiare
DOPPIO SQL_DOUBLE SQLDOUBLE galleggiare doppio
DECIMALE SQL_DECIMAL SQLCHAR* decimal.Decimal decimal
filo SQL_VARCHAR SQLCHAR* str corda
VARCHAR(n) SQL_VARCHAR SQLCHAR* str corda
CHAR(n) SQL_CHAR SQLCHAR* str corda
BINARY SQL_BINARY SQLCHAR* bytes byte[]
DATTERO SQL_TYPE_DATE SQL_DATE_STRUCT datetime.date Data e ora
TIMESTAMP SQL_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT datetime.datetime Data e ora
ARRAY SQL_VARCHAR SQLCHAR* str (JSON) corda
MAP SQL_VARCHAR SQLCHAR* str (JSON) corda
STRUCT SQL_VARCHAR SQLCHAR* str (JSON) corda

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

Problemi comuni

Errori di connessione

Problema: Impossibile 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:

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

Timeout delle query

Problema: timeout delle query su tabelle di grandi dimensioni

Soluzioni:

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

Abilita registrazione

Per la risoluzione dei problemi, 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

Abilitare la traccia ODBC di Windows per la diagnostica di basso livello e disattivarla quando non è necessaria per ottenere prestazioni ottimali:

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