Controlador ODBC de Microsoft para Microsoft Fabric Data Engineering

ODBC (conectividad abierta de bases de datos) es un estándar ampliamente adoptado que permite a las aplicaciones cliente conectarse y trabajar con datos de bases de datos y plataformas de macrodatos.

El controlador ODBC de Microsoft para Fabric Data Engineering te permite conectar, consultar y gestionar cargas de trabajo de Spark en Fabric con la fiabilidad y simplicidad del estándar ODBC. Construido sobre las APIs de Livy de Fabric, el controlador proporciona conectividad Spark SQL segura y flexible para tus aplicaciones y herramientas de BI compatibles con C/C++, .NET, Python y otras.

Características clave

• Compatible con ODBC 3.x: implementación completa de la especificación ODBC 3.x
• Autenticación Microsoft Entra ID: varios flujos de autenticación, que incluyen autenticación con CLI de Azure, interactiva, de credenciales de cliente, basada en certificados y de tokens de acceso
• Compatibilidad con consultas SQL de Spark: ejecución directa de instrucciones SQL de Spark
• Compatibilidad completa con tipos de datos: compatibilidad con todos los tipos de datos de Spark SQL, incluidos tipos complejos (ARRAY, MAP, STRUCT)
• Reutilización de sesión: administración de sesiones integrada para mejorar el rendimiento
• Modo de alta concurrencia: Opta por sesiones compartidas y cálidas en el lado del servidor para reducir la latencia de inicio de conexión y la expansión del clúster Spark
• Compatibilidad con tablas grandes: control optimizado para grandes conjuntos de resultados con tamaños de página configurables
• Captura previa asincrónica: carga de datos en segundo plano para mejorar el rendimiento
• Compatibilidad con proxy: configuración de proxy HTTP para entornos empresariales
• Soporte multi-esquema para casas lacustres: Conectarse a un esquema específico dentro de una casa lacustre
• Integración OneLake: Acceder a los datos de lakehouse almacenados en OneLake, incluyendo tablas en múltiples esquemas, a través de una interfaz ODBC unificada sin configuración de almacenamiento separada
• Elementos de entorno compatibles: Adjuntar elementos de entorno de Fabric durante la ejecución del trabajo para aplicar bibliotecas del área de trabajo, propiedades de Spark y variables a cada sesión
• Configuración de Spark personalizada: Pase las propiedades de configuración de Spark directamente a través del cadena de conexión para optimizar el comportamiento de la sesión

Prerrequisitos

Antes de usar Microsoft ODBC Driver for Microsoft Fabric Data Engineering, asegúrese de que tiene:

• Sistema operativo: Windows 10/11 o Windows Server 2016+
• Fabric Access: Acceso a un espacio de trabajo Fabric
• Microsoft Entra ID credenciales: credenciales adecuadas para la autenticación
• IDs de espacio de trabajo y casa del lago: identificadores GUID para tu espacio de trabajo en Fabric y la casa del lago
• CLI de Azure (opcional): necesario para el método de autenticación de la CLI de Azure

Descarga e instalación de MSI

• Descargar Microsoft ODBC Driver for Microsoft Fabric Data Engineering (zip)

1. Descargar el paquete MSI del Microsoft ODBC Driver para Microsoft Fabric Data Engineering
2. Haga doble clic en MicrosoftFabricODBCDriver-2.0.msi.
3. Siga el Asistente para la instalación y acepte el contrato de licencia.
4. Elija el directorio de instalación (valor predeterminado: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Completar la instalación

Instalación silenciosa

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

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

Comprobación de la instalación

Después de la instalación, compruebe que el controlador está registrado:

1. Ejecutar odbcad32.exe (Administrador de Orígenes de Datos ODBC)
2. Vaya a la pestaña Controladores
3. Compruebe que aparece "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"

Ejemplo de inicio rápido

Este ejemplo demuestra cómo conectarse a Fabric y ejecutar una consulta utilizando el controlador ODBC de Microsoft para Microsoft Fabric Data Engineering. Antes de ejecutar este código, asegúrese de que ha completado los requisitos previos e instalado el controlador.

Ejemplo de 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;
}

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

Ejemplo de .NET

using System.Data.Odbc;

// Connection string with required parameters
string connectionString = 
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand("SELECT 'Hello from Fabric!' as message", connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Formato de la cadena de conexión

Cadena de conexión básica

Microsoft ODBC Driver for Microsoft Fabric Data Engineering usa el siguiente formato de cadena de conexión:

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

Componentes de cadena de conexión

Ejemplos de cadena de conexión

Conexión básica (autenticación de la CLI de Azure)

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

Con las opciones de rendimiento

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

Con la función de registro

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

Con modo de alta concurrencia

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

Consulta la sección Modo de alta concurrencia (HC) para obtener la guía completa de configuración.

Autenticación

Microsoft ODBC Driver for Microsoft Fabric Data Engineering admite varios métodos de autenticación a través de Microsoft Entra ID (anteriormente Azure Active Directory). La autenticación se configura mediante el AuthFlow parámetro en la cadena de conexión.

Métodos de autenticación

Puedes especificar valores de autenticación en formato UPPER_SNAKE_CASE, PascalCase o numérico. El controlador también acepta alias cortos como Browser, Interactive, CLI, Certificate, Token, y File. El controlador ignora los subrayos cuando compara valores.

Autenticación de la CLI de Azure

Ideal para: Desarrollo e aplicaciones interactivas

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

Requisitos previos:

• CLI de Azure instalada: az --version
• Iniciado sesión: az login

Autenticación interactiva del explorador

Mejor para: aplicaciones orientadas al usuario

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

Comportamiento:

• Abre una ventana del explorador para la autenticación de usuario
• Las credenciales se almacenan en caché para las conexiones posteriores

Autenticación de credenciales de cliente (principal de servicio)

Mejor para: Servicios automatizados y trabajos en segundo plano

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

Parámetros necesarios

• TenantId: identificador de inquilino de Azure
• ClientId: ID de aplicación (cliente) de Microsoft Entra ID
• ClientSecret: secreto de cliente de Microsoft Entra ID

procedimientos recomendados

• Almacenamiento de secretos de forma segura (Azure Key Vault, variables de entorno)
• Uso de identidades administradas siempre que sea posible
• Rotación periódica de secretos

Autenticación basada en certificados

Mejor para: Aplicaciones empresariales que requieren autenticación basada en certificados

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

Parámetros necesarios:

• TenantId: identificador de inquilino de Azure
• ClientId: ID de aplicación (cliente)
• CertificatePath: ruta de acceso al archivo de certificado PFX/PKCS12
• CertificatePassword: contraseña de certificado

Autenticación de token de acceso

Mejor para: Escenarios de autenticación personalizados

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

Autenticación mediante token de archivo

Utiliza la autenticación mediante token de archivo para entornos en contenedores y canalizaciones automatizadas en las que otro proceso escribe un token de portador en el archivo de token predefinido del controlador:

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

El controlador resuelve la ubicación del archivo token en Windows y Linux.

Alias de propiedades entre controladores

El controlador ODBC acepta nombres de propiedades seleccionados de ADO.NET y JDBC además de nombres nativos ODBC. Este soporte puede reducir los cambios en la cadena de conexión cuando cambias entre controladores Fabric.

El controlador resuelve 17 alias entre controladores al establecer la conexión.

Parámetros de configuración

Parámetros necesarios

Estos parámetros deben estar presentes en cada cadena de conexión:

Parámetros opcionales

Configuración de conexión

Configuración de rendimiento

Configuración de registro

Configuración del proxy

Configuraciones de alta concurrencia (HC)

Utiliza estos parámetros para habilitar y configurar el modo de alta concurrencia (HC). El modo HC es opcional. Si no configuras LivyMode o UseHighConcurrency, el controlador utiliza la ruta clásica de una sola sesión. Para orientación y ejemplos, véase Modo de alta concurrencia (HC).

Precedencia de modos y validación

• LivyMode tiene prioridad sobre UseHighConcurrency cuando configuras ambos parámetros.
• Los valores de los parámetros no distinguen entre mayúsculas y minúsculas.
• UseHighConcurrency acepta true, 1, yes, o on para activar el modo HC. Acepta false, 0, no, o off para desactivar el modo HC.
• Para otros valores no vacíos, SQLDriverConnect devuelve un error. Solo SQLConnect DSN registra el fallo de validación y utiliza la ruta clásica.

Configuración de compatibilidad

El controlador acepta TenantPrincipal y PoolMax, incluidos sus valores alternativos mediante variables de entorno, para mantener la compatibilidad con configuraciones anteriores de HC. El controlador analiza y valida estos valores, pero estos no afectan a la coincidencia de sesiones de HC ni a la capacidad del pool en tiempo de ejecución. No dependas de ellos para aislamiento de inquilinos ni límites de conexión.

Alternativas variables de entorno

El controlador utiliza las siguientes variables de entorno solo cuando el parámetro DSN o cadena de conexión correspondiente no está activado:

Para FABRIC_ODBC_USE_HC, la habilitación solo para entorno reconoce true, 1 o yes (sin distinguir entre mayúsculas y minúsculas). Otros valores dejan a HC desactivado. Los on alias y off solo se aplican a valores DSN y cadena de conexión.

Parámetros del entorno

Puede adjuntar un elemento de entorno de Fabric a la sesión de Spark iniciada por el controlador. Las bibliotecas, las propiedades y las variables del entorno seleccionado se aplican automáticamente cuando se crea la sesión.

Cadena de conexión de ejemplo con el elemento del entorno:

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

Configuración personalizada de Spark

Puede pasar las propiedades de configuración de Spark directamente en el cadena de conexión. Cualquier parámetro con spark. prefijo se aplica automáticamente a la sesión de Spark en el momento de la creación, lo que le permite invalidar los valores predeterminados de área de trabajo o tiempo de ejecución.

Configuraciones de Spark de ejemplo:

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

Ejemplo de cadena de conexión con propiedades personalizadas de Spark:

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

Modo de alta concurrencia (HC)

El modo de alta concurrencia (HC) permite que las conexiones ODBC al mismo espacio de trabajo y lakehouse se conecten a sesiones Livy Spark compartidas y cálidas en el lado del servidor, en lugar de provisionar un clúster separado para cada conexión. Úsalo para cargas de trabajo como paneles de BI, kernels de cuadernos y ramificaciones de ETL que abren muchas conexiones de corta duración y pueden compartir la capacidad de Spark administrada por el servidor.

El modo HC es opcional. Si no configuras una configuración HC, el controlador usa la ruta clásica de sesión única.

Elegir un modo de conexión

Usa el modo HC cuando:

• Tu carga de trabajo abre muchas conexiones ODBC de corta duración, como paneles de BI, núcleos de cuadernos o procesos ETL distribuidos en paralelo.
• Las conexiones se dirigen al mismo espacio de trabajo y al mismo lago y pueden compartir una sesión de Spark gestionada por el servidor.
• Reducir la latencia de arranque en frío por conexión es importante.

Usa el modo clásico cuando:

• Cada conexión requiere una sesión Spark aislada debido a diferentes configuraciones o al estricto aislamiento de recursos.
• El endpoint de Fabric Livy para el espacio de trabajo objetivo y la casa del lago no soporta el modo HC.

Activar el modo de alta concurrencia

Añade un parámetro de modo de alta concurrencia al DSN o a la cadena de conexión.

Recomendado: Establecer LivyMode

Utilizar LivyMode para seleccionar explícitamente el modo de adquisición de sesión:

LivyMode=HighConcurrency

Los valores admitidos son Classic, HighConcurrencyy Auto. Los valores no distinguen mayúsculas de minúsculas. Auto Actualmente selecciona el modo clásico.

Alternativa: Set UseHighConcurrency

Utiliza la configuración booleana para compatibilidad con configuraciones existentes:

UseHighConcurrency=true

Para activar el modo de alta concurrencia, use true, 1, yes, o on. Para desactivarlo, usa false, 0, no, o off. Los valores no distinguen mayúsculas de minúsculas. SQLDriverConnect rechaza otros valores no vacíos con SQLSTATE HY024. Solo SQLConnect DSN registra el fallo de validación y utiliza el modo clásico.

Parámetros requeridos en modo HC

La activación de HC requiere los siguientes identificadores válidos:

Incluye SessionTag porque influye en la emparejación del servidor para las sesiones calientes.

Emparejamiento de sesiones

El modo HC no garantiza que todas las conexiones reutilicen una sesión existente. Para cada solicitud de adquisición de sesión, el controlador envía:

• El valor SessionTag.
• La configuración efectiva de Spark, incluida la configuración de conf.* y EnvironmentId.

El servicio Fabric Livy evalúa estos valores y decide si adjunta la conexión a una sesión caliente o crea una nueva. Para mejorar la reutilización de sesiones, utiliza valores consistentes entre conexiones que estén destinadas a compartir la capacidad de Spark gestionada por el servidor.

Ejemplos de cadena de conexión

Conexión mínima de HC (autenticación de CLI de Azure):

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

HC con tiempos de espera ajustados:

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 con entorno y anulaciones de Spark conf:

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

Configurar el modo HC en una DSN

Puedes guardar los ajustes de HC en un DSN en lugar de repetirlos en cada cadena de conexión. Cuando una cadena de conexión no especifica un valor, el controlador lee estos ajustes desde la DSN:

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

El controlador también lee los ajustes de solo compatibilidad TenantPrincipal y PoolMax. Para guardar estos ajustes, edita la DSN en odbcad32.exe o usa SQLWritePrivateProfileString. Usa los nombres de parámetros en la tabla de configuración de HC.

Desactivar el modo HC

Puedes desactivar nuevas adquisiciones de sesión HC sin tener que volver a desplegar el controlador. Usa el método que corresponde a cómo activaste el modo HC:

La cadena de conexión y la configuración de DSN tienen prioridad sobre la alternativa basada en variables de entorno. Estos cambios afectan solo a nuevas conexiones. Las sesiones de HC existentes siguen activas hasta que se liberan.

Comprender el comportamiento del runtime de HC

• Validación:SQLDriverConnect rechaza valores HC booleanos y enteros positivos inválidos con SQLSTATE HY024. Rechaza un LivyMode no válido y valores de WorkspaceId, LakehouseId y IdempotencyKey no válidos o demasiado grandes con SQLSTATE HY000. Un valor de compatibilidad TenantPrincipal sobredimensionado también devuelve HY000. Para SQLConnect solo con DSN, el controlador registra errores habituales de validación de HC y utiliza el modo clásico. Los valores confidenciales demasiado grandes siguen haciendo fallar la conexión.
• Datos sensibles: El controlador excluye o elimina IdempotencyKey otros campos sensibles de los registros HC y de la salida de diagnóstico.
• Cancelación: La cancelación del extracto es cooperativa. El trabajo del servidor ya en curso finaliza correctamente en lugar de interrumpirse de inmediato.
• Interruptores automáticos: Los modos HC y clásico usan interruptores automáticos separados. Agotar un modo no afecta al otro.
• Base de datos inicial: Las conexiones HC no ejecutan la instrucción inicial USE del Database parámetro. Ejecuta USE <database> después de conectar o usa nombres de tablas totalmente cualificados.
• Diagnóstico: Configura LogLevel=DEBUG para registrar las decisiones de adquisición HC, sondeo, liberación y mapeo de errores. Para una solución de problemas específica, establece LIVY_HC_VERBOSE=1 para que incluya diagnósticos HTTP de HC adicionales depurados.

Configurar una DSN

Cree un DSN del sistema

1. Abrir el administrador de ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Creación de un nuevo DSN del sistema

   • Vaya a la pestaña "DSN del sistema"
   • Seleccione "Agregar".
   • Seleccione "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
   • Seleccione "Finish" (Finalizar).

3. Configuración de las opciones de DSN

   • Nombre del origen de datos: escriba un nombre único (por ejemplo, FabricODBC)
   • Descripción: Descripción opcional
   • ID del espacio de trabajo: GUID de tu espacio de trabajo de Fabric
   • Identificador de Lakehouse: GUID de Fabric Lakehouse
   • Autenticación: Selección del método de autenticación
   • Id. de entorno (opcional): escriba el GUID del elemento de entorno de Fabric que se va a adjuntar durante la creación de la sesión.
   • Modo Livy (opcional): Establecer en HighConcurrency para activar el modo HC
   • Etiqueta de sesión (opcional): Introduce una etiqueta operativa no sensible para la coincidencia de sesión HC
   • Configuración de opciones adicionales según sea necesario

4. Probar conexión

   • Seleccione "Probar conexión" para comprobar la configuración.
   • Seleccione "Aceptar" para guardar.

Uso de DSN en aplicaciones

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

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

Ejemplos de uso

Conexión básica y consulta

Pitón

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

Trabajar con grandes conjuntos de resultados

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

Ejecutar sentencias 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;
}

Use executeDml con las instrucciones INSERT, UPDATE o DELETE. El recuento de filas reportado depende de si el resultado contiene un recuento de actualizaciones reconocido por el controlador.

Detección de esquemas

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

Asignación de tipos de datos

El controlador asigna los tipos de datos de Spark SQL a tipos de SQL ODBC:

Integración de herramientas de BI

Microsoft Excel

1. Abrir Excel - Datos ->> Obtener datos -> de otros orígenes -> desde ODBC
2. Seleccione el DSN configurado (por ejemplo, FabricODBC)
3. Autenticación si se le solicita
4. Examinar y seleccionar tablas
5. Cargar datos en la hoja de cálculo de Excel

Power BI Escritorio

1. Abrir Power BI Desktop-> Obtener datos :> ODBC
2. Selección del DSN configurado
3. Examinar el catálogo de datos y seleccionar tablas
4. Transformación de datos según sea necesario
5. Creación de visualizaciones

SQL Server Management Studio (Servidor vinculado)

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

Solución de problemas

En esta sección se proporcionan instrucciones para resolver problemas comunes que pueden surgir al usar Microsoft ODBC Driver for Microsoft Fabric Data Engineering.

Problemas comunes

En las secciones siguientes se describen problemas comunes y sus soluciones:

Fallos de conexión

Problema: No se puede conectar a Fabric

Soluciones:

1. Verifica que el ID del espacio de trabajo y el ID de Lakehouse sean GUIDs correctos
2. Compruebe la autenticación de la CLI de Azure: az account show
3. Asegúrese de que tiene los permisos adecuados del área de trabajo de Fabric.
4. Comprobación de la conectividad de red y la configuración del proxy

Errores de autenticación

Problema: error de autenticación con la CLI de Azure

Soluciones:

• Ejecución az login para actualizar las credenciales
• Compruebe el inquilino correcto: az account set --subscription <subscription-id>
• Comprobar la validez del token: az account get-access-token --resource https://api.fabric.microsoft.com

Tiempos de espera de consulta agotados

Problema: Las consultas agotan el tiempo de espera en tablas grandes

Soluciones:

• Habilitar LargeTableSupport=true
• Ajuste PageSizeBytes para un tamaño de fragmento óptimo
• Habilite la captura previa asincrónica: EnableAsyncPrefetch=1
• Utilice la cláusula LIMIT para restringir el tamaño del resultado

Habilitar registro

Al solucionar problemas, habilitar el registro detallado puede ayudarle a identificar la causa principal de los problemas. Puede habilitar el registro a través de la cadena de conexión.

Para habilitar el registro detallado:

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

Niveles de registro:

• DEBUG: Información de depuración detallada y el nivel de registro más detallado del controlador
• INFO: información general (valor predeterminado)
• WARN: solo advertencias
• ERROR: solo errores

Seguimiento de ODBC

Para diagnósticos de bajo nivel, puede habilitar el trazado ODBC de Windows para capturar llamadas detalladas a la API ODBC y el comportamiento del controlador. Recuerde desactivar el seguimiento cuando no sea necesario para mantener un rendimiento óptimo.

Para habilitar el seguimiento de ODBC:

1. Abrir odbcad32.exe
2. Vaya a la pestaña "Seguimiento"
3. Establecer la ruta de acceso del archivo de seguimiento (por ejemplo, C:\temp\odbctrace.log)
4. Seleccione "Iniciar seguimiento ahora".
5. Reproducir el problema
6. Seleccione "Detener seguimiento ahora".

Contenido relacionado

• Controlador Microsoft ODBC para Microsoft Fabric Data Engineering en Linux
• Runtimes de Apache Spark en Fabric
• Fabric Runtime 1.3
• ¿Qué es Livy API para ingeniería de datos?
• Microsoft controlador JDBC para ingeniería de datos de Microsoft Fabric