Pilote ODBC Microsoft pour Microsoft Fabric Ingénierie des données

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.

Le pilote Microsoft ODBC pour l’ingénierie des données Fabric vous permet de connecter, interroger et gérer des charges de travail Spark dans Fabric avec la fiabilité et la simplicité de la norme ODBC. Basé sur les API Livy de Fabric, le pilote offre une connectivité SQL Spark sécurisée et flexible à vos applications et outils BI compatibles avec C/C++, .NET, Python et autres.

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
• Mode haute concurrence : Optez pour des sessions Livy partagées et chaudes côté serveur pour réduire la latence de démarrage de la connexion et l’étalement du cluster Spark
• 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
• Prise en charge de plusieurs schémas dans un lakehouse : Connectez-vous à un schéma spécifique dans un lakehouse
• Intégration OneLake : Accéder aux données Lakehouse stockées dans OneLake, y compris des tables réparties sur plusieurs schémas, via une interface ODBC unifiée sans configuration de stockage séparée
• 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+
• Fabric Access : Accès à un espace de travail Fabric
• informations d’identification Microsoft Entra ID : informations d’identification appropriées pour l’authentification
• Identifiants de l’espace de travail et du lakehouse : identifiants GUID de votre espace de travail Fabric et de votre lakehouse
• Azure CLI (facultatif) : obligatoire pour la méthode d’authentification Azure CLI

Télécharger et installer MSI

• 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-2.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-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.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 à Fabric et exécuter une requête en utilisant le pilote ODBC Microsoft 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 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;
}

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

Avec le mode de haute concurrence

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

Voir la section du mode High-Concurrency (HC) pour obtenir des instructions complètes de configuration.

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

Vous pouvez spécifier des valeurs d’authentification au format snake case en majuscules, en casse Pascal ou au format numérique. Le pilote accepte également des alias courts tels que Browser, Interactive, CLI, Certificate, Token, et File. Le pilote ignore les soulignements lorsqu’il compare les valeurs.

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

Authentification par jeton de fichier

Utilisez l’authentification par jeton de fichier pour les environnements conteneurisés et les pipelines automatisés où un autre processus écrit un jeton porteur dans le fichier de jeton bien connu du pilote :

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

Le pilote détermine l’emplacement du fichier de jeton sous Windows et Linux.

Alias de propriétés inter-pilotes

Le pilote ODBC accepte certains noms de propriétés ADO.NET et JDBC en plus des noms natifs ODBC. Ce support peut réduire les changements de chaîne de connexion lorsque vous passez d’un pilote Fabric à l’autre.

Le pilote résout 17 alias inter-pilotes à la connexion.

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 forte concurrence (HC)

Utilisez ces paramètres pour activer et configurer le mode haute concurrence (HC). Le mode HC est sur inscription. Si vous ne spécifiez ni LivyMode ni UseHighConcurrency, le pilote utilise le mode classique à session unique. Pour des conseils et des exemples, voir Mode de haute concurrence (HC).

Priorité des modes et validation

• LivyMode a priorité sur UseHighConcurrency lorsque vous définissez les deux paramètres.
• Les valeurs des paramètres ne sont pas sensibles à la casse.
• UseHighConcurrency accepte true, 1, yes, ou on pour activer le mode HC. Il accepte false, 0, no ou off pour désactiver le mode HC.
• Pour d’autres valeurs non vides, SQLDriverConnect renvoie une erreur. En mode DSN uniquement, SQLConnect consigne l’échec de la validation et utilise le chemin classique.

Paramètres de compatibilité

Le pilote accepte TenantPrincipal et PoolMax, ainsi que leurs variables d’environnement de remplacement, afin d’assurer la compatibilité avec les anciennes configurations HC. Le pilote analyse et valide ces valeurs, mais elles n’affectent pas la correspondance des sessions HC ni la capacité du pool d’exécution. Ne comptez pas sur eux pour l’isolement des locataires ou les limites de connexion.

Solutions de repli des variables d’environnement

Le pilote utilise les variables d’environnement suivantes uniquement lorsque le DSN ou le paramètre de chaîne de connexion correspondant n’est pas défini :

Pour FABRIC_ODBC_USE_HC, l’activation via l’environnement uniquement accepte true, 1 ou yes (sans distinction entre majuscules et minuscules). D’autres valeurs désactivent HC. Les on alias et off ne s’appliquent qu’aux valeurs DSN et de la chaîne de connexion.

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

Mode haute concurrence (HC)

Le mode haute concurrence (HC) permet aux connexions ODBC au même espace de travail et au même lakehouse d’être rattachées à des sessions Livy Spark partagées et préchauffées côté serveur, au lieu de provisionner un cluster distinct pour chaque connexion. Utilisez-le pour des charges de travail telles que les tableaux de bord BI, les noyaux de notebooks et les extensions ETL qui ouvrent de nombreuses connexions de courte durée et peuvent partager la capacité Spark gérée par le serveur.

Le mode HC doit être activé volontairement. Si vous ne configurez pas de réglage HC, le pilote utilise le chemin classique d’une seule session.

Choisir un mode de connexion

Utilisez le mode HC lorsque :

• Votre charge de travail ouvre de nombreuses connexions ODBC de courte durée, comme les tableaux de bord BI, les noyaux de notebooks ou l’expansion ETL.
• Les connexions ciblent le même espace de travail et le même lakehouse et peuvent partager une session Spark gérée par le serveur.
• Réduire la latence de démarrage à froid par connexion est important.

Utilisez le mode classique lorsque :

• Chaque connexion nécessite une session Spark isolée en raison de configurations Spark différentes ou d’une isolation stricte des ressources.
• Le point de terminaison Fabric Livy pour l’espace de travail cible et le lakehouse ne prend pas en charge le mode HC.

Activer le mode de haute concurrence

Ajoutez un paramètre de mode haute concurrence au DSN ou à la chaîne de connexion.

Recommandé : Définir LivyMode

Utilisez LivyMode pour sélectionner explicitement le mode acquisition de session :

LivyMode=HighConcurrency

Les valeurs prises en charge sont Classic, HighConcurrencyet Auto. Les valeurs ne sont pas sensibles à la majuscule. Auto Il sélectionne actuellement le mode classique.

Alternative : Définir UseHighConcurrency

Utilisez le paramètre booléen pour la compatibilité avec les configurations existantes :

UseHighConcurrency=true

Pour désactiver le mode de haute concurrence, utilisez true, 1, yes, ou on. Pour le désactiver, utilisez false, 0, no, ou off. Les valeurs ne sont pas sensibles à la majuscule. SQLDriverConnect rejette les autres valeurs non vides avec SQLSTATE HY024. Le DSN uniquement SQLConnect enregistre l’échec de validation et utilise le mode classique.

Paramètres requis en mode HC

L’activation HC nécessite les identifiants valides suivants :

Incluez-le SessionTag car cela influence l’appariement côté serveur pour les sessions chaudes.

Correspondance de session

Le mode HC ne garantit pas que chaque connexion réutilise une session existante. Pour chaque demande d’acquisition de session, le pilote envoie :

• La valeur SessionTag.
• La configuration effective de Spark, y compris les paramètres conf.* et EnvironmentId.

Le service Fabric Livy évalue ces valeurs et décide s’il faut associer la connexion à une session chaude ou en créer une nouvelle. Pour améliorer la réutilisation des sessions, utilisez des valeurs cohérentes entre les connexions destinées à partager la capacité Spark gérée par le serveur.

Exemples de chaîne de connexion

Connexion HC minimale (Azure CLI auth) :

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

HC avec temps d’arrêt réglés :

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 avec un environnement et les contours de la conf 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"
)

Configurez le mode HC dans un DSN

Vous pouvez stocker les paramètres HC dans un DSN au lieu de les répéter dans chaque chaîne de connexion. Lorsqu'une chaîne de connexion ne spécifie pas de valeur, le pilote lit ces paramètres depuis le DSN :

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

Le pilote lit également les paramètres réservés à la compatibilité TenantPrincipal et PoolMax. Pour sauvegarder ces paramètres, modifie le DSN dans odbcad32.exe ou utilise SQLWritePrivateProfileString. Utilisez les noms des paramètres dans la table des paramètres HC.

Désactiver le mode HC

Vous pouvez désactiver la création de nouvelles sessions HC sans redéployer le pilote. Utilisez la méthode qui correspond à la façon dont vous avez activé le mode HC :

Les paramètres de la chaîne de connexion et du DSN prévalent sur la solution de repli via les variables d’environnement. Ces changements n’affectent que les nouvelles connexions. Les sessions HC existantes continuent jusqu’à leur sortie.

Comprendre le comportement du runtime HC

• Validation :SQLDriverConnect rejette les valeurs HC booléennes invalides et les valeurs entières positives avec SQLSTATE HY024. Il rejette une valeur LivyMode non valide ainsi que des valeurs WorkspaceId, LakehouseId et IdempotencyKey non valides ou trop grandes, avec le code SQLSTATE HY000. Une valeur de compatibilité TenantPrincipal surdimensionnée renvoie HY000également . Pour le DSN uniquement SQLConnect, le pilote enregistre les échecs de validation HC ordinaires et utilise le mode classique. Les valeurs sensibles à la sécurité surdimensionnées échouent toujours à la connexion.
• Données sensibles : Le pilote exclut ou efface IdempotencyKey d’autres champs sensibles des journaux HC et des résultats de diagnostic.
• Annulation : L’annulation de relevé est coopérative. Les tâches du serveur déjà en cours d’exécution se terminent proprement au lieu d’être interrompues immédiatement.
• Disjoncteurs : Les modes HC et classique utilisent des disjoncteurs séparés. Épuiser un mode n’affecte pas l’autre.
• Base de données initiale : Les connexions HC n’exécutent pas l’instruction initiale USE pour le Database paramètre. Exécutez USE <database> après avoir connecté ou utilisez des noms de table entièrement qualifiés.
• Diagnostic : Régler LogLevel=DEBUG pour enregistrer les décisions d’acquisition, de sondage, de publication et de cartographie d’erreurs HC. Pour un dépannage ciblé, définissez LIVY_HC_VERBOSE=1 pour inclure des diagnostics HTTP HC supplémentaires expurgés.

Configurez un 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
   • Mode Livy (optionnel) : Définir sur HighConcurrency pour activer le mode HC
   • Libellé de session (optionnel) : Saisissez un libellé opérationnel non sensible pour la mise en correspondance des sessions HC
   • 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()

Exécuter les instructions 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;
}

Utilisez executeDml avec les instructions INSERT, UPDATE ou DELETE. Le nombre de lignes indiqué dépend de la présence, dans le résultat, d’un nombre de mises à jour reconnu par le pilote.

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

Solutions :

1. Vérifiez que l’ID de l’espace de travail et l’ID du lakehouse sont des GUID valides
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 :

• DEBUG: Informations de débogage détaillées et niveau de journalisation du pilote le plus verbeux
• 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

• Pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sous Linux
• 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