Pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sur Linux (Aperçu)

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 compatibles C/C++, .NET, Python et autres compatibles ODBC sous Linux.

Fonctionnalités clés

• Conforme à ODBC 3.x : Implémentation complète de la spécification ODBC 3.x.
• Authentification Microsoft Entra ID : Flux d’authentification multiples, incluant Azure CLI, identifiants clients, certificats et authentification par jeton d’accès.
• Prise en charge des requêtes SQL Spark : exécution directe des instructions SQL de Spark.
• Prise en charge complète des types de données : prise en charge de tous les types de données SQL Spark, y compris les types complexes (ARRAY, MAP, et STRUCT).
• Réutilisation des sessions : gestion de session intégrée pour améliorer les performances.
• Prise en charge des grandes tables : Gestion optimisée pour de grands ensembles de résultats avec des tailles de pages configurables.
• Prélecture asynchrone : Chargement des données en arrière-plan pour améliorer les performances.
• Prise en charge des proxy : configuration HTTP des proxy pour les environnements d’entreprise.
• Prise en charge des maisons lacustres multi-schémas : Connectez-vous à un schéma spécifique au sein d’une maison lacustre.

Prerequisites

Avant d’utiliser le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sous Linux, assurez-vous de respecter les prérequis suivants :

• Système d’exploitation : Ubuntu 22.04 ou ultérieur, Debian 11 ou ultérieur, ou Red Hat Enterprise Linux (RHEL) 8 ou ultérieur en x86-64.
• unixODBC : Le gestionnaire de pilotes ODBC pour Linux. Installez les unixodbc packages et unixodbc-dev .
• Accès Fabric : Accès à un espace de travail Fabric.
• Identifiants Microsoft Entra ID : Identifiants appropriés pour l’authentification.
• IDS de l’espace de travail et de la maison du lac : Les identifiants GUID pour votre espace de travail Fabric et votre maison du lac.
• Azure CLI (optionnel) : Obligatoire lorsque vous utilisez l’authentification Azure CLI.

Téléchargez et installez sur Linux

Le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering version 1.0.0 est disponible en aperçu public.

• Téléchargez le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sur Linux (zip)

Pour installer le pilote :

1. Extrayez ms-sparksql-odbc-linux-1.0.0.zip.

2. Ouvrez un terminal dans le répertoire extrait.

3. Installez le package Debian :

   sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb
   

Le paquet installe les fichiers suivants :

Pilote de registre manuel

Le package enregistre automatiquement le pilote auprès de unixODBC. Pour enregistrer manuellement le pilote, exécutez :

sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template

Vérifier l’installation

Vérifiez que le pilote est enregistré et que la bibliothèque est installée :

odbcinst -q -d
ls -la /usr/lib/libmicrosoftfabricodbc.so

La odbcinst commande devrait indiquer [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Désinstaller le pilote

Pour désinstaller le pilote, exécutez la commande suivante :

sudo dpkg -r microsoft-fabric-odbc-driver

Cette commande supprime les fichiers du pilote et désinscrit le pilote d’unixODBC.

Exemple de démarrage rapide

Les exemples suivants se connectent à Fabric et exécutent une requête SQL Spark. Remplissez les prérequis et installez le pilote avant d’exécuter un exemple.

exemple de Python

import pyodbc

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

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 C/C++

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

int main() {
    SQLHENV henv = SQL_NULL_HENV;
    SQLHDBC hdbc = SQL_NULL_HDBC;
    SQLHSTMT hstmt = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

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

    SQLRETURN result = SQLDriverConnect(
        hdbc,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        std::cout << "Connected successfully!" << std::endl;

        SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        result = SQLExecDirect(
            hstmt,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

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

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

        SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
        SQLDisconnect(hdbc);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return 0;
}

Construis et exécute l’exemple :

g++ -o fabric_test fabric_test.cpp -lodbc -std=c++17
./fabric_test

exemple de .NET

using System.Data.Odbc;

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 chaîne de connexion

Chaîne de connexion de base

Utilisez 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

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

Connexion 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

Lien avec la journalisation

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

Authentication

Le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering prend en charge plusieurs méthodes d’authentification via Microsoft Entra ID. Configurez l’authentification en utilisant le AuthFlow paramètre dans la chaîne de connexion ou le DSN.

Méthodes d’authentification

L'authentification de l'Azure CLI

Utilisez l’authentification Azure CLI pour le développement et les applications interactives.

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)

Avant de vous connecter, vérifiez que Azure CLI est installé et connectez-vous :

az --version
az login

Pour installer Azure CLI sur Debian ou Ubuntu, utilisez le gestionnaire de paquets :

sudo apt-get update
sudo apt-get install -y azure-cli

Authentification des identifiants clients

Utilisez l’authentification des identifiants clients pour les services automatisés et les tâches 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};"
)

Veuillez fournir les paramètres suivants :

• TenantId: L’ID du locataire Microsoft Entra.
• ClientId: ID d’application (client).
• ClientSecret: Le secret client.

Stockez les secrets dans un stockage secret sécurisé ou dans des variables d’environnement. Ne stockez pas de secrets dans des chaînes de connexion en texte clair ou dans des fichiers INI.

Authentification basée sur un certificat

Utilisez l’authentification basée sur des certificats pour les applications d’entreprise nécessitant des identifiants de certificat.

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=/path/to/cert.pfx;"
    "CertificatePassword=<password>;"
)

Veuillez fournir les paramètres suivants :

• TenantId: L’ID du locataire Microsoft Entra.
• ClientId: ID d’application (client).
• CertificatePath: Le chemin vers le fichier de certificat PFX ou PKCS12.
• CertificatePassword: Le mot de passe du certificat.

Authentification par jeton d’accès

Utilisez l’authentification du jeton d’accès lorsque votre application acquiert un jeton via un autre mécanisme.

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 requis

Incluez ces paramètres 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

Configuration DSN

Sous Linux, configurez les noms des sources de données (DSN) dans les fichiers INI au lieu du registre Windows.

Créer un DSN

Copiez le modèle installé :

cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template ~/.odbc.ini

Modification ~/.odbc.ini avec les détails de votre espace de travail Fabric :

[FabricDSN]
Description    = Microsoft Fabric Data Engineering
Driver         = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId    = <workspace-id>
LakehouseId    = <lakehouse-id>
AuthFlow       = AZURE_CLI
LogLevel       = INFO
# LogFile      = /tmp/fabric_odbc.log
# LargeTableSupport = true
# ReuseSession = true

Vérifier le DSN

Listez les DSN configurés, puis testez la connexion :

odbcinst -q -s
isql -v FabricDSN

La isql commande nécessite les outils de ligne de commande unixODBC.

Utiliser un DSN dans les applications

conn = pyodbc.connect("DSN=FabricDSN")

using var connection = new OdbcConnection("DSN=FabricDSN");
await connection.OpenAsync();

SQLRETURN result = SQLConnect(
    hdbc,
    (SQLCHAR*)"FabricDSN",
    SQL_NTS,
    NULL,
    0,
    NULL,
    0);

Exemples d’utilisation

Tester une connexion avec isql

Commencez une session SQL interactive :

isql -v FabricDSN

Lancer une seule requête :

echo "SELECT 1 AS test" | isql -v FabricDSN -b

Travail avec de grands ensembles de résultats

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;"
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT * FROM large_table")

row_count = 0
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break

    for row in rows:
        row_count += 1

    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

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

Découvrez les schémas et les tables

import pyodbc

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

cursor.execute("SHOW TABLES")
for table in cursor.fetchall():
    print(table)

cursor.execute("DESCRIBE employees")
for column in cursor.fetchall():
    print(column)

cursor.execute("SHOW SCHEMAS")
for schema in cursor.fetchall():
    print(schema)

conn.close()

Mappage de types de données

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

Différences de plateforme

Troubleshooting

Conducteur non trouvé

Problème : La connexion échoue avec [IM002] Data source name not found and no default driver specified.

Solutions :

1. Vérifiez l’enregistrement des pilotes en exécutant odbcinst -q -d.
2. Vérifiez qu’elle /usr/lib/libmicrosoftfabricodbc.so existe.
3. Enregistrez le conducteur en exécutant sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Réinstallez le package en exécutant sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN introuvable

Problème : La connexion échoue avec [IM002] Data source name not found.

Solutions :

1. Vérifiez la configuration DSN en exécutant odbcinst -q -s.
2. Vérifiez cela ~/.odbc.ini ou /etc/odbc.ini contient la section DSN.
3. Assurez-vous que la Driver valeur correspond exactement au nom du conducteur enregistré.

Échecs de connexion

Problème : Le pilote ne peut pas se connecter à Fabric.

Solutions :

1. Vérifiez que l’ID de l’espace de travail et l’identifiant de la maison du lac sont des GUID valides.
2. Vérifiez l’authentification Azure CLI en exécutant az account show.
3. Assurez-vous d’avoir les autorisations requises pour l’espace de travail Fabric.
4. Vérifiez la connectivité réseau et les paramètres proxy.

Erreurs d’authentification

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

Solutions :

1. Cours az login pour rafraîchir tes identifiants.
2. Réglez l’abonnement correct en exécutant az account set --subscription <subscription-id>.
3. Vérifie le jeton en exécutant az account get-access-token --resource https://api.fabric.microsoft.com.
4. Assurez-vous que votre compte dispose des autorisations requises pour l’espace de travail Fabric.

Erreurs de bibliothèque partagée

Problème : Le conducteur signale error while loading shared libraries: libmicrosoftfabricodbc.so.

Solutions :

1. Réinstallez le package en exécutant sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Vérifiez qu’elle /usr/lib/libmicrosoftfabricodbc.so existe.
3. Exécutez sudo ldconfig pour rafraîchir le cache de la bibliothèque partagée.

Délais d’expiration des requêtes

Problème : Les requêtes s’épuisent sur de grandes tables.

Solutions :

1. Ajouter LargeTableSupport=true à la chaîne de connexion.
2. Ajustez PageSizeBytes la taille du résultat.
3. Ajouter EnableAsyncPrefetch=1 à la chaîne de connexion.
4. Utilisez une LIMIT clause pour limiter la taille du résultat.

Activer la journalisation

Activez la journalisation détaillée dans un DSN :

[FabricDSN]
LogLevel = DEBUG
LogFile  = /tmp/fabric_odbc_debug.log

Sinon, ajoutez des paramètres de journalisation à la chaîne de connexion :

LogLevel=DEBUG;LogFile=/tmp/fabric_odbc_debug.log;

Le pilote prend en compte les niveaux logaritaires suivants :

• TRACE: Inclut tous les appels API.
• DEBUG: Inclut des informations détaillées sur le débogage.
• INFO: Inclut des informations générales et est la norme par défaut.
• WARN: Inclut uniquement les avertissements.
• ERROR: Inclut uniquement les erreurs.

Activer le traçage unixODBC

Pour les diagnostics d’appels ODBC de bas niveau, ajoutez la configuration suivante à /etc/odbcinst.ini:

[ODBC]
Trace     = yes
TraceFile = /tmp/odbc_trace.log

Désactivez le traçage une fois le dépannage terminé pour éviter une surcharge de performance inutile.

Contenu connexe

• Microsoft ODBC Driver for Microsoft Fabric Data Engineering
• Runtimes Apache Spark dans Fabric
• Fabric Runtime 1.3
• Présentation de l’API Livy pour l’ingénierie des données
• Microsoft JDBC Driver for Microsoft Fabric Data Engineering
• unixODBC