Driver Microsoft ODBC para Microsoft Fabric Data Engineering em Linux (Pré-visualização)

ODBC (Open Database Connectivity) é um padrão amplamente adotado que permite que aplicações clientes se liguem e trabalhem com dados provenientes de bases de dados e plataformas de big data.

O Microsoft ODBC Driver for Fabric Data Engineering permite-lhe ligar, consultar e gerir cargas de trabalho Spark no Fabric com a fiabilidade e simplicidade do padrão ODBC. Construído sobre as APIs Livy da Fabric, o driver fornece conectividade Spark SQL segura e flexível para as suas aplicações compatíveis com C/C++, .NET, Python e outras compatíveis com ODBC no Linux.

Principais características

• Compatível com ODBC 3.x: Implementação completa da especificação ODBC 3.x.
• Autenticação Microsoft Entra ID: Múltiplos fluxos de autenticação, incluindo CLI do Azure, credenciais de clientes, autenticação baseada em certificados e autenticação de token de acesso.
• Suporte para consultas Spark SQL: Execução direta de instruções SQL Spark.
• Suporte abrangente de tipos de dados: Suporte para todos os tipos de dados SQL do Spark, incluindo tipos complexos (ARRAY, MAP, e STRUCT).
• Reutilização de sessões: Gestão de sessões integrada para melhorar o desempenho.
• Suporte a tabelas grandes: Tratamento otimizado para conjuntos de resultados grandes com tamanhos de página configuráveis.
• Prefetch assíncrono: Carregamento de dados em segundo plano para melhorar o desempenho.
• Suporte a proxy: Configuração de proxy HTTP para ambientes empresariais.
• Suporte multi-esquema para casas de lago: Ligue-se a um esquema específico dentro de uma casa de lago.

Pré-requisitos

Antes de usar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering no Linux, certifique-se de que tem os seguintes pré-requisitos:

• Sistema operativo: Ubuntu 22.04 ou posterior, Debian 11 ou posterior, ou Red Hat Enterprise Linux (RHEL) 8 ou posterior em x86-64.
• unixODBC: O gestor de drivers ODBC para Linux. Instale os unixodbc pacotes e.unixodbc-dev
• Acesso Fabric: Acesso a um espaço de trabalho Fabric.
• Credenciais Microsoft Entra ID: Credenciais apropriadas para autenticação.
• IDs de espaço de trabalho e casa do lago: Os identificadores GUID para o seu espaço de trabalho Fabric e a casa do lago.
• CLI do Azure (opcional): Obrigatória quando usa autenticação CLI do Azure.

Descarregar e instalar no Linux

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering versão 1.0.0 está disponível em pré-visualização pública.

• Descarregue o Driver Microsoft ODBC para Microsoft Fabric Data Engineering em Linux (zip)

Para instalar o driver:

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

2. Abra um terminal no diretório extraído.

3. Instale o pacote Debian:

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

O pacote instala os seguintes ficheiros:

Driver de registo manual

O pacote regista automaticamente o driver com unixODBC. Para registar o driver manualmente, execute:

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

Verifique a instalação

Verifique se o driver está registado e que a biblioteca está instalada:

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

O odbcinst comando deve indicar [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Desinstalar o driver

Para desinstalar o driver, execute o seguinte comando:

sudo dpkg -r microsoft-fabric-odbc-driver

Este comando remove os ficheiros do driver e desregista o driver do unixODBC.

Exemplo de início rápido

Os exemplos seguintes ligam-se ao Fabric e executam uma consulta SQL no Spark. Cumpra os pré-requisitos e instale o driver antes de executar um exemplo.

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

Exemplo em 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;
}

Constrói e executa o exemplo:

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

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

Formato da cadeia de ligação

Cadeia básica de ligação

Use o seguinte formato de cadeia de ligação:

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

Componentes da corda de ligação

Exemplo de cadeias de conexão

Ligação básica

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

Ligação com opções de desempenho

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

Ligação com a exploração florestal

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

Autenticação

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering suporta múltiplos métodos de autenticação através do Microsoft Entra ID. Configure a autenticação usando o AuthFlow parâmetro na cadeia de ligação ou DSN.

Métodos de autenticação

Autenticação da CLI do Azure

Use autenticação CLI do Azure para desenvolvimento e aplicações interativas.

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)

Antes de se ligar, verifique se a CLI do Azure está instalada e inicie sessão:

az --version
az login

Para instalar o CLI do Azure no Debian ou Ubuntu, use o gestor de pacotes:

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

Autenticação de credenciais do cliente

Use autenticação de credenciais do cliente para serviços automatizados e trabalhos em 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};"
)

Forneça os parâmetros a seguir:

• TenantId: O ID do inquilino da Microsoft Entra.
• ClientId: O ID do aplicativo (cliente).
• ClientSecret: O segredo do cliente.

Armazena segredos num armazenamento secreto seguro ou variáveis de ambiente. Não guarde segredos em cadeias de ligação em texto simples ou ficheiros INI.

Autenticação baseada em certificado

Use autenticação baseada em certificados para aplicações empresariais que requerem credenciais de certificado.

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

Forneça os parâmetros a seguir:

• TenantId: O ID do inquilino da Microsoft Entra.
• ClientId: O ID do aplicativo (cliente).
• CertificatePath: O caminho para o ficheiro de certificados PFX ou PKCS12.
• CertificatePassword: A palavra-passe do certificado.

Autenticação de token de acesso

Use autenticação de token de acesso quando a sua aplicação adquirir um token através de outro mecanismo.

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

Parâmetros de configuração

Parâmetros necessários

Inclua estes parâmetros em cada cadeia de ligação:

Parâmetros opcionais

Definições de ligação

Configurações de desempenho

Configurações de registo

Definições de proxy

Configuração DSN

No Linux, configure os nomes das fontes de dados (DSNs) em ficheiros INI em vez do registo do Windows.

Criar um DSN

Copie o modelo instalado:

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

Edite ~/.odbc.ini com os detalhes do seu espaço de trabalho 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

Verificar a DSN

Liste as DSNs configuradas e depois teste a ligação:

odbcinst -q -s
isql -v FabricDSN

O isql comando requer as ferramentas de linha de comandos unixODBC.

Usar uma DSN nas aplicações

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

Exemplos de utilização

Testar uma ligação com isql

Inicie uma sessão interativa de SQL:

isql -v FabricDSN

Execute uma única consulta:

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

Trabalho com 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;"
    "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()

Descobrir esquemas e tabelas

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

Mapeamento de tipos de dados

O driver mapeia os tipos de dados SQL do Spark para tipos SQL ODBC:

Diferenças de plataforma

Solução de problemas

Condutor não encontrado

Problema: A ligação falha com [IM002] Data source name not found and no default driver specified.

Soluções:

1. Verifique o registo do condutor executando odbcinst -q -d.
2. Confirma que isso /usr/lib/libmicrosoftfabricodbc.so existe.
3. Registe o condutor executando sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Reinstale o pacote executando sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.

DSN não encontrado

Problema: A ligação falha com [IM002] Data source name not found.

Soluções:

1. Verifique a configuração da DSN executando odbcinst -q -s.
2. Verifica isso ~/.odbc.ini ou /etc/odbc.ini contém a secção DSN.
3. Certifique-se de que o Driver valor corresponde exatamente ao nome do condutor registado.

Falhas de ligação

Problema: O driver não consegue ligar-se ao Fabric.

Soluções:

1. Verifica se o ID do workspace e o ID do lakehouse são GUIDs válidos.
2. Verifique a autenticação do CLI do Azure executando az account show.
3. Certifique-se de que tem as permissões necessárias para o espaço de trabalho do Fabric.
4. Verifique a conectividade de rede e as definições do proxy.

Erros de autenticação

Problema: A autenticação CLI do Azure falha.

Soluções:

1. Corre az login para atualizar as tuas credenciais.
2. Defina a subscrição correta executando az account set --subscription <subscription-id>.
3. Verifique o token executando az account get-access-token --resource https://api.fabric.microsoft.com.
4. Certifique-se de que a sua conta tem as permissões necessárias para o espaço de trabalho Fabric.

Erros de biblioteca partilhada

Problema: O condutor reporta error while loading shared libraries: libmicrosoftfabricodbc.so.

Soluções:

1. Reinstale o pacote executando sudo dpkg -i microsoft-fabric-odbc-driver-1.0.0-Linux.deb.
2. Confirma que isso /usr/lib/libmicrosoftfabricodbc.so existe.
3. Executa sudo ldconfig para atualizar a cache da biblioteca partilhada.

Tempos limite de consulta

Problema: As consultas esgotam em tabelas grandes.

Soluções:

1. Adicionar LargeTableSupport=true à cadeia de conexão.
2. Ajusta PageSizeBytes pelo tamanho do resultado.
3. Adicionar EnableAsyncPrefetch=1 à cadeia de conexão.
4. Use uma LIMIT cláusula para restringir o tamanho do resultado.

Ativar registo de atividades

Permitir o registo detalhado numa DSN:

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

Alternativamente, adicione parâmetros de registo à cadeia de ligação:

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

O driver suporta os seguintes níveis logarítmicos:

• TRACE: Inclui todas as chamadas API.
• DEBUG: Inclui informações detalhadas de depuração.
• INFO: Inclui informação geral e é o padrão.
• WARN: Inclui apenas avisos.
• ERROR: Inclui apenas erros.

Ativar o rastreio unixODBC

Para diagnósticos de chamadas ODBC de baixo nível, adicione a seguinte configuração a /etc/odbcinst.ini:

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

Desligue o rastreamento quando terminar a resolução de problemas para evitar sobrecarga desnecessária de desempenho.

Conteúdo relacionado

• Driver ODBC da Microsoft para Engenharia de Dados do Microsoft Fabric
• Ambientes de execução do Apache Spark no Fabric
• Runtime Fabric 1.3
• O que é a API do Livy para Engenharia de Dados
• Microsoft JDBC Driver para Microsoft Fabric Data Engineering
• unixODBC