Pilote Microsoft ODBC pour Microsoft Fabric Data Engineering (préversion)

ODBC (Open Database Connectivity) est une norme largement adoptée qui permet aux applications clientes de se connecter et d’utiliser des données à partir de bases de données et de plateformes Big Data.

Microsoft ODBC Driver for Fabric Data Engineering vous permet de connecter, d’interroger et de gérer des charges de travail Spark dans Microsoft Fabric avec la fiabilité et la simplicité de la norme ODBC. Basé sur les API Livy de Microsoft Fabric, le pilote fournit une connectivité Spark SQL sécurisée et flexible à vos applications .NET, Python et d’autres outils compatibles ODBC et BI.

Fonctionnalités clés

• Conforme ODBC 3.x : mise en œuvre complète de la spécification ODBC 3.x
• Authentification Microsoft Entra ID : plusieurs flux d’authentification, notamment Azure CLI, interactive, informations d’identification du client, authentification par certificat et autentification par jeton d’accès.
• Prise en charge des requêtes Spark SQL : exécution directe d’instructions Spark SQL
• Prise en charge complète des types de données : prise en charge de tous les types de données Spark SQL, y compris les types complexes (ARRAY, MAP, STRUCT)
• Réutilisation de session : gestion de session intégrée pour améliorer les performances
• Prise en charge des tables volumineuses : gestion optimisée pour les jeux de résultats volumineux avec des tailles de page configurables
• Prérécupération asynchrone : chargement des données en arrière-plan pour améliorer les performances
• Prise en charge du proxy : configuration de proxy HTTP pour les environnements d’entreprise
• Support des Lakehouse multiservices : Se connecter à un schéma spécifique dans un Lakehouse
• intégration OneLake : Accéder aux données Lakehouse stockées dans Microsoft OneLake, y compris les tables sur plusieurs schémas, via une interface ODBC unifiée sans configuration de stockage distincte
• Prise en charge des éléments d'environnement : attacher des éléments d’environnement Fabric pendant l'exécution de la tâche pour appliquer des bibliothèques d'espace de travail, des propriétés Spark et des variables à chaque session
• configuration Custom Spark : Passer les propriétés de configuration Spark directement via le chaîne de connexion pour régler le comportement de session

Prerequisites

Avant d’utiliser Microsoft ODBC Driver for Microsoft Fabric Data Engineering, vérifiez que vous disposez des éléments suivants :

• Système d’exploitation : Windows 10/11 ou Windows Server 2016+
• Accès à Microsoft Fabric : accès à un espace de travail Microsoft Fabric
• informations d’identification Microsoft Entra ID : informations d’identification appropriées pour l’authentification
• Identifiants d’espace de travail et de Lakehouse : identificateurs GUID pour votre espace de travail Fabric et votre Lakehouse.
• Azure CLI (facultatif) : obligatoire pour la méthode d’authentification Azure CLI

Télécharger et installer MSI

Microsoft ODBC Driver pour Microsoft Fabric Data Engineering version 1.0.0 est en préversion publique que vous pouvez télécharger à partir de ce lien du centre de téléchargement.

• Télécharger Microsoft ODBC Driver for Microsoft Fabric Data Engineering (zip)

1. Téléchargez le pilote ODBC de Microsoft pour l'ingénierie des données de Microsoft Fabric dans le package MSI
2. Double-cliquez sur MicrosoftFabricODBCDriver-1.0.msi
3. Suivez l’Assistant Installation et acceptez le contrat de licence
4. Choisir le répertoire d’installation (par défaut : C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Terminer l’installation

Installation silencieuse

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

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

Vérifier l’installation

Après l’installation, vérifiez que le pilote est inscrit :

1. Exécuter odbcad32.exe (administrateur de source de données ODBC)
2. Accédez à l’onglet Pilotes
3. Vérifier que « Microsoft ODBC Driver for Microsoft Fabric Data Engineering » est répertorié

Exemple de démarrage rapide

Cet exemple montre comment se connecter à Microsoft Fabric et exécuter une requête à l’aide de Microsoft ODBC Driver pour Microsoft Fabric Data Engineering. Avant d’exécuter ce code, vérifiez que vous avez rempli les prérequis et installé le pilote.

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

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

Format de la chaîne de connexion

Chaîne de connexion de base

Microsoft ODBC Driver for Microsoft Fabric Data Engineering utilise le format de chaîne de connexion suivant :

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

Composants de chaîne de connexion

Exemples de chaîne de connexion

Connexion de base (authentification Azure CLI)

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

Avec les options de performance

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

Avec l'enregistrement des logs

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 prend en charge plusieurs méthodes d’authentification via Microsoft Entra ID (anciennement Azure Active Directory). L’authentification est configurée à l’aide du AuthFlow paramètre dans la chaîne de connexion.

Méthodes d’authentification

L'authentification de l'Azure CLI

Idéal pour : Développement et applications interactives

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

Conditions préalables :

• Azure CLI installé : az --version
• Connecté : az login

Authentification interactive du navigateur

Idéal pour : applications accessibles par l’utilisateur

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

Comportement :

• Ouvre une fenêtre de navigateur pour l’authentification utilisateur
• Les informations d’identification sont mises en cache pour les connexions suivantes

Authentification des informations d’identification du client (principal de service)

Idéal pour : services automatisés et travaux en arrière-plan

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

Paramètres obligatoires

• TenantId: ID de locataire Azure
• ClientId: ID d’application (client) de Microsoft Entra ID
• ClientSecret: Secret client de l'ID Microsoft Entra

Bonnes pratiques

• Stocker les secrets en toute sécurité (Azure Key Vault, variables d’environnement)
• Utiliser des identités managées lorsque cela est possible
• Changer régulièrement les secrets

Authentification basée sur un certificat

Idéal pour : les applications d’entreprise nécessitant une authentification basée sur des certificats

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

Paramètres obligatoires :

• TenantId: ID de locataire Azure
• ClientId: ID d’application (client)
• CertificatePath: chemin d’accès au fichier de certificat PFX/PKCS12
• CertificatePassword: Mot de passe du certificat

Authentification par jeton d’accès

Idéal pour : scénarios d’authentification personnalisés

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

Paramètres de configuration

Paramètres obligatoires

Ces paramètres doivent être présents dans chaque chaîne de connexion :

Paramètres facultatifs

Paramètres de connexion

Paramètres de performances

Paramètres de journalisation

Paramètres du proxy

Paramètres de l’environnement

Vous pouvez attacher un élément d’environnement Fabric à la session Spark démarrée par le pilote. Les bibliothèques, les propriétés Spark et les variables de l’environnement sélectionné sont automatiquement appliquées lors de la création de la session.

Exemple de chaîne de connexion avec un élément d'environnement :

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

Configuration Spark personnalisée

Vous pouvez transmettre des propriétés de configuration Spark directement dans le chaîne de connexion. Tout paramètre précédé d’un spark. préfixe est automatiquement appliqué à la session Spark au moment de la création, ce qui vous permet de remplacer les paramètres par défaut de l’espace de travail ou du runtime.

Exemples de configurations Spark :

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

Exemple de chaîne de connexion avec des propriétés Spark personnalisées :

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

Configuration DSN

Créer un DSN de système

1. Ouvrir l’administrateur ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Créer un nouveau DSN système

   • Ouvrez l’onglet « Système DSN »
   • Sélectionnez « Ajouter ».
   • Sélectionnez « Microsoft ODBC Driver for Microsoft Fabric Data Engineering »
   • Sélectionnez « Terminer »

3. Configurer les paramètres DSN

   • Nom de la source de données : entrez un nom unique (par exemple, FabricODBC)
   • Description : Description facultative
   • ID de l'espace de travail: GUID de votre espace de travail Fabric
   • ID Lakehouse : L'ID de votre lakehouse Fabric
   • Authentification : Sélectionner une méthode d’authentification
   • Environment ID (facultatif) : entrez le GUID de l’élément d’environnement Fabric à attacher lors de la création de session
   • Configurer des paramètres supplémentaires en fonction des besoins

4. Tester la connexion

   • Sélectionnez « Tester la connexion » pour vérifier les paramètres
   • Sélectionnez « OK » pour enregistrer

Utiliser DSN dans les applications

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

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

Exemples d’utilisation

Connexion et requête de base

Python

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

Utilisation de jeux de résultats volumineux

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

Découverte de schéma

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

Mappage de types de données

Le pilote mappe les types de données Spark SQL aux types SQL ODBC :

Intégration de l'outil BI

Microsoft Excel

1. Ouvrir Excel - Données ->> Obtenir des données -> à partir d’autres sources -> à partir d’ODBC
2. Sélectionnez votre DSN configuré (par exemple, FabricODBC)
3. S’authentifier si vous y êtes invité
4. Parcourir et sélectionner des tables
5. Charger des données dans une feuille de calcul Excel

Power BI Desktop

1. Ouvrir Power BI Desktop -> Obtenir des données -> ODBC
2. Sélectionnez votre DSN configuré
3. Parcourir le catalogue de données et sélectionner des tables
4. Transformer les données en fonction des besoins
5. Créer des visualisations

SQL Server Management Studio (serveur lié)

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

Résolution des problèmes

Cette section fournit des conseils pour résoudre les problèmes courants que vous pouvez rencontrer lors de l’utilisation de Microsoft ODBC Driver pour Microsoft Fabric Data Engineering.

Problèmes courants

Les sections suivantes décrivent les problèmes courants et leurs solutions :

Échecs de connexion

Problème : Impossible de se connecter à Microsoft Fabric

Solutions :

1. Vérifier que l’ID de l’espace de travail et l’ID Lakehouse sont des GUID corrects
2. Vérifiez l’authentification Azure CLI : az account show
3. Vérifiez que vous disposez des autorisations appropriées pour l’espace de travail Fabric
4. Vérifier la connectivité réseau et les paramètres de proxy

Erreurs d’authentification

Problème : l’authentification échoue avec Azure CLI

Solutions :

• Exécuter az login pour actualiser les informations d’identification
• Vérifiez le locataire correct : az account set --subscription <subscription-id>
• Vérifiez la validité du jeton : az account get-access-token --resource https://api.fabric.microsoft.com

Délais d’expiration des requêtes

Problème : Les requêtes expirent sur des tables volumineuses

Solutions :

• Activer LargeTableSupport=true
• Ajuster PageSizeBytes pour une taille de bloc optimale
• Activez la prérécupération asynchrone : EnableAsyncPrefetch=1
• Utilisez la clause LIMIT pour restreindre la taille des résultats

Activation de la journalisation

Lors de la résolution des problèmes, l’activation de la journalisation détaillée peut vous aider à identifier la cause racine des problèmes. Vous pouvez activer la journalisation via la chaîne de connexion.

Pour activer la journalisation détaillée :

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

Niveaux de journalisation :

• TRACE: La plus détaillée, inclut tous les appels d'API
• DEBUG: Informations de débogage détaillées
• INFO: Informations générales (par défaut)
• WARN: Avertissements uniquement
• ERROR: erreurs uniquement

Suivi ODBC

Pour les diagnostics de bas niveau, vous pouvez activer le suivi ODBC Windows pour capturer les appels d’API ODBC détaillés et le comportement du pilote. N’oubliez pas de désactiver le suivi lorsqu’il n’est pas nécessaire de maintenir des performances optimales.

Pour activer le suivi ODBC :

1. Ouvrir odbcad32.exe
2. Accédez à l’onglet « Suivi »
3. Définir le chemin du fichier de trace (par exemple, C:\temp\odbctrace.log)
4. Sélectionnez « Démarrer le suivi maintenant »
5. Reproduire le problème
6. Sélectionnez « Arrêter le suivi maintenant »

Contenu connexe

• Environnements d'exécution Apache Spark dans Fabric
• Fabric Runtime 1.3
• Présentation de l’API Livy pour l’ingénierie des données
• Microsoft pilote JDBC pour l’ingénierie des données Microsoft Fabric