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

Important

Cette fonctionnalité est en version préliminaire.

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.

Note

Dans Apache Spark open source, la base de données et le schéma sont utilisés comme synonymes. Par exemple, en exécutant SHOW SCHEMAS ou SHOW DATABASES dans un notebook Fabric, on obtient le même résultat : une liste de tous les schémas dans la maison du lac.

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.

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 :

Fichier Emplacement installé
Bibliothèque de pilotes /usr/lib/libmicrosoftfabricodbc.so
Modèle d’enregistrement des pilotes /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template
Modèle de configuration DSN /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template
Licence /usr/share/doc/microsoft-fabric-odbc-driver/LICENSE
Guide d’utilisation /usr/share/doc/microsoft-fabric-odbc-driver/USAGE_Linux.md

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

Component Description Example
DRIVER Identificateur de pilote ODBC {Microsoft ODBC Driver for Microsoft Fabric Data Engineering}
WorkspaceId Identifiant d’espace de travail Fabric (GUID) 4bbf89a8-66bb-443f-91af-df31e6a7560b
LakehouseId Identifiant Fabric de la maison lacustre (GUID) d8faa650-1343-496b-b9cc-d4168a676f90
AuthFlow Méthode d’authentification AZURE_CLI, CLIENT_CREDENTIAL, CLIENT_CERTIFICATE, ou ACCESS_TOKEN

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

AuthFlow valeur Description
AZURE_CLI Développement à l’aide des informations d’identification Azure CLI
CLIENT_CREDENTIAL Directeur de service avec un secret client
CLIENT_CERTIFICATE Directeur de service avec un certificat
ACCESS_TOKEN Jeton de porteur d'accès préacquis

Note

L’authentification interactive par navigateur n’est pas disponible sur les serveurs Linux sans interface audio. Utilisez plutôt Azure CLI, identifiants clients, authentification basée sur certificat ou jeton d’accès.

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ètre Type Description Example
WorkspaceId Identifiant Unique Universel (UUID) Identificateur de l’espace de travail Fabric 4bbf89a8-...
LakehouseId Identifiant Unique Universel (UUID) Identifiant Fabric de la maison lacustre d8faa650-...
AuthFlow String Type de flux d’authentification AZURE_CLI

Paramètres facultatifs

Paramètres de connexion

Paramètre Type Default Description
Database String Aucun Base de données spécifique à laquelle se connecter
Scope String https://api.fabric.microsoft.com/.default Étendue OAuth

Paramètres de performances

Paramètre Type Default Description
ReuseSession Boolean true Réutiliser une session Spark existante
LargeTableSupport Boolean false Activer les optimisations pour les jeux de résultats volumineux
EnableAsyncPrefetch Boolean false Activer la prérécupération des données en arrière-plan
PageSizeBytes Integer 18874368 (18 Mo) Taille de page pour la pagination des résultats de 1 à 18 Mo

Paramètres de journalisation

Paramètre Type Default Description
LogLevel String INFO Niveau logarithmique : TRACE, DEBUG, INFO, WARN, ou ERROR
LogFile String odbc_driver.log Chemin de fichier journal absolu ou relatif

Paramètres du proxy

Paramètre Type Default Description
UseProxy Boolean false Activer un proxy
ProxyHost String Aucun Nom d’hôte proxy
ProxyPort Integer Aucun Port proxy
ProxyUsername String Aucun Nom d’utilisateur d’authentification par procuration
ProxyPassword String Aucun Mot de passe d’authentification proxy

Configuration DSN

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

Fichier Scope Accès
/etc/odbc.ini DSN à l’échelle du système Exige sudo
~/.odbc.ini DSN spécifiques à chaque utilisateur Utilisateur actuel uniquement

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 :

Type Spark SQL Type SQL ODBC Type C/C++ Type Python Type .NET
BOOLEAN SQL_BIT SQLCHAR bool bool
BYTE SQL_TINYINT SQLSCHAR int sbyte
SHORT SQL_SMALLINT SQLSMALLINT int short
INT SQL_INTEGER SQLINTEGER int int
LONG SQL_BIGINT SQLBIGINT int long
FLOAT SQL_REAL SQLREAL float float
DOUBLE SQL_DOUBLE SQLDOUBLE float double
DECIMAL SQL_DECIMAL SQLCHAR* decimal.Decimal decimal
STRING SQL_VARCHAR SQLCHAR* str string
VARCHAR(n) SQL_VARCHAR SQLCHAR* str string
CHAR(n) SQL_CHAR SQLCHAR* str string
BINARY SQL_BINARY SQLCHAR* bytes byte[]
DATE SQL_TYPE_DATE SQL_DATE_STRUCT datetime.date DateTime
TIMESTAMP SQL_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT datetime.datetime DateTime
ARRAY SQL_VARCHAR SQLCHAR* Chaîne JSON string
MAP SQL_VARCHAR SQLCHAR* Chaîne JSON string
STRUCT SQL_VARCHAR SQLCHAR* Chaîne JSON string

Différences de plateforme

Fonctionnalité Windows Linux
Directeur de pilotage Microsoft ODBC Driver Manager unixODBC
Binaire du pilote microsoftfabricodbc.dll libmicrosoftfabricodbc.so
Configuration DSN Registre et interface graphique Windows /etc/odbc.ini et ~/.odbc.ini
Enregistrement des pilotes Registre et odbcad32.exe odbcinst -i -d -f
Client HTTP WinHTTP libcurl
TLS Support intégré de Windows Openssl
Authentification par certificat Windows CryptoAPI OpenSSL avec fichiers RS256 et PEM ou PFX
Authentification interactive Fenêtre du navigateur Non disponible sur les serveurs sans interface
Emballage Programme d’installation MSI Paquet Linux

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

  • Last updated on