Driver Microsoft ODBC para Microsoft Fabric Data Engineering em Linux

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.
• Modo de alta concorrência: Opte por sessões Livy partilhadas e pré-aquecidas no servidor para reduzir a latência no estabelecimento da ligação e a proliferação do cluster Spark.
• Suporte a tabelas grandes: Tratamento otimizado para conjuntos de resultados grandes com tamanhos de página configuráveis.
• Pré-carregamento 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 pacotes unixodbc e unixodbc-dev.
• libcurl: A dependência HTTP em tempo de execução, como libcurl4 ou o pacote equivalente para a sua distribuição.
• OpenSSL: A dependência de tempo de execução de TLS e criptografia, como openssl e libssl3 ou pacotes equivalentes.
• Acesso ao Fabric: Acesso a um espaço de trabalho do 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

• Descarregue o Microsoft ODBC Driver for Microsoft Fabric Data Engineering em Linux (tar)

Para instalar o driver:

1. Extrair ms-sparksql-odbc-linux-2.0.0.tar.

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

3. Instale o pacote Debian:

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

O pacote instala os seguintes ficheiros:

Instalar um pacote RPM

No RHEL, Fedora ou CentOS, instale o pacote RPM a partir do arquivo de drivers extraído:

sudo dnf install ./microsoft-fabric-odbc-driver-*.x86_64.rpm

Alternativamente, use rpm:

sudo rpm -i microsoft-fabric-odbc-driver-*.x86_64.rpm

Verifique se o RPM registou o condutor:

odbcinst -q -d | grep "Microsoft"

Para desinstalar o pacote RPM, execute:

sudo dnf remove microsoft-fabric-odbc-driver

Instale uma bola de alcatrão

Para distribuições sem suporte a Debian ou pacotes RPM, ou para um local de instalação personalizado, extrai o .tar.gz pacote e executa o seu script de instalação:

tar -xzf microsoft-fabric-odbc-driver-2.0.0-linux-x86_64.tar.gz
cd microsoft-fabric-odbc-driver-2.0.0

# Install to /opt/microsoft/fabricodbc.
sudo ./install.sh

# Or install to a custom writable location.
./install.sh --prefix=$HOME/fabricodbc

O script de instalação suporta estas opções:

Para verificar a instalação padrão do tarball, execute:

odbcinst -q -d
ls -la /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so

Para o desinstalar, execute sudo ./install.sh --uninstall a partir do diretório de pacotes extraídos.

Registar controlador manualmente

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

Ligação com o modo de alta concorrência

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

Para orientações completas de configuração, veja modo de alta concorrência (HC).

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 utilizando o parâmetro AuthFlow na cadeia de ligação ou no DSN.

Métodos de autenticação

Autenticação da CLI do Azure

Utilize a autenticação da 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.

Armazene segredos num cofre de segredos seguro ou em 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};"
)

Autenticação por token de ficheiro

Use autenticação por token de ficheiro em ambientes containerizados e pipelines automatizados onde outro processo escreve um token portador no ficheiro de token conhecido do driver:

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

Para os nomes alternativos de propriedades entre controladores suportados, consulte Nomes alternativos de propriedades entre controladores.

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

Definições de alta concorrência (HC)

Use estes parâmetros para ativar e configurar o modo de alta concorrência (HC). O modo HC é de adesão voluntária. Se não definires LivyMode ou UseHighConcurrency, o driver usa o caminho clássico de sessão única. Para orientações e exemplos, veja Modo de alta concorrência (HC).

Precedência de modos e validação

• LivyMode Tem prioridade sobre UseHighConcurrency quando defines ambos os parâmetros.
• Os valores dos parâmetros não são diferenciados em maiúsculas minúsculas.
• UseHighConcurrency aceita true, 1, yes, ou on para ativar o modo HC. Aceita false, 0, no, ou off para desativar o modo HC.
• Para outros valores não vazios, SQLDriverConnect devolve um erro. A configuração apenas com DSN SQLConnect regista a falha de validação e segue o caminho clássico.

Definições de compatibilidade

O driver aceita TenantPrincipal e PoolMax, incluindo as respetivas alternativas através de variáveis de ambiente, para garantir a compatibilidade com configurações HC anteriores. O controlador interpreta e valida estes valores, mas eles não afetam a correspondência das sessões HC nem a capacidade do pool em tempo de execução. Não dependa deles para isolamento de inquilinos ou limites de ligação.

Alternativas para variáveis de ambiente

O driver utiliza as seguintes variáveis de ambiente apenas quando o parâmetro correspondente DSN ou string de ligação não está definido:

Para FABRIC_ODBC_USE_HC, a ativação apenas por ambiente reconhece true, 1 ou yes (sem distinção entre maiúsculas e minúsculas). Outros valores deixam o modo HC desativado. Os on aliases e off aplicam-se apenas a valores DSN e de strings de ligação.

Modo de alta concorrência (HC)

O modo de alta concorrência (HC) permite que as ligações ODBC ao mesmo espaço de trabalho e lakehouse se associem a sessões partilhadas, já ativas, do Livy Spark no servidor, em vez de aprovisionar um cluster separado para cada ligação. Utilize-o para cargas de trabalho como painéis de BI, kernels de notebooks e expansão ETL que abrem muitas ligações de curta duração e podem partilhar capacidade Spark gerida pelo servidor.

O modo HC é de adesão voluntária. Se não configurar uma configuração HC, o controlador utiliza o modo clássico de sessão única.

Escolha um modo de ligação

Use o modo HC quando:

• A sua carga de trabalho abre muitas ligações ODBC de curta duração, como painéis de BI, núcleos de notebooks ou ramificação de ETL.
• As ligações visam o mesmo espaço de trabalho e a mesma casa do lago e podem partilhar uma sessão Spark gerida pelo servidor.
• Reduzir a latência de arranque a frio por ligação é importante.

Use o modo clássico quando:

• Cada ligação requer uma sessão Spark isolada devido a diferentes configurações Spark ou isolamento estrito de recursos.
• O ponto final do Fabric Livy para o espaço de trabalho de destino e o armazém de dados não é compatível com o modo HC.

Ativar o modo de alta concorrência

Adicione um parâmetro de modo de alta concorrência ao DSN ou à cadeia de ligação.

Recomendado: Definir LivyMode

Use LivyMode para selecionar explicitamente o modo de aquisição de sessão:

LivyMode=HighConcurrency

Os valores suportados são Classic, HighConcurrencye Auto. Valores não são sensíveis a maiúsculas e minúsculas. Auto Atualmente seleciona o modo clássico.

Alternativa: Set UseHighConcurrency

Use a definição booleana para compatibilidade com configurações existentes:

UseHighConcurrency=true

Para ativar o modo de alta concorrência, use true, 1, yes, ou on. Para o desativar, use false, 0, no, ou off. Valores não são sensíveis a maiúsculas e minúsculas. SQLDriverConnect rejeita outros valores não vazios com SQLSTATE HY024. Apenas SQLConnect DSN regista a falha de validação e usa o modo clássico.

Também pode ativar o modo de alta concorrência para a shell atual utilizando variáveis de ambiente:

export FABRIC_ODBC_USE_HC=true
export FABRIC_ODBC_WORKSPACE_ID=<workspace-id>
export FABRIC_ODBC_LAKEHOUSE_ID=<lakehouse-id>
export FABRIC_ODBC_SESSION_TAG=bi-dashboard

Parâmetros necessários no modo HC

A ativação HC requer os seguintes identificadores válidos:

Inclui SessionTag porque influencia o matching do lado do servidor para sessões quentes.

Associação de sessões

O modo HC não garante que todas as ligações reutilizam uma sessão existente. Para cada solicitação de obtenção de sessão, o controlador envia:

• O valor SessionTag.
• A configuração efetiva do Spark, incluindo as definições de conf.* e EnvironmentId.

O serviço Fabric Livy avalia estes valores e decide se deve ligar a ligação a uma sessão quente ou criar uma nova sessão. Para melhorar a reutilização da sessão, utilize valores consistentes entre as ligações que pretendam partilhar a capacidade do Spark gerido pelo servidor.

Exemplo de cadeias de conexão

Ligação mínima do HC com autenticação da CLI do Azure:

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

Conexão HC com tempos limite 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

Ligação do HC a um ambiente e substituições da configuração do 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 com o 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 o modo HC numa DSN Linux

Em vez de repetir as definições de HC em cada cadeia de ligação, guarde-as em ~/.odbc.ini para um DSN específico de utilizador ou em /etc/odbc.ini para um DSN de âmbito do sistema.

[FabricHCDSN]
Description               = Microsoft Fabric Data Engineering with HC mode
Driver                    = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId               = <workspace-id>
LakehouseId               = <lakehouse-id>
AuthFlow                  = AZURE_CLI
LivyMode                  = HighConcurrency
SessionTag                = bi-dashboard
AcquireTimeoutSeconds     = 300
HeartbeatTimeoutInSecond  = 600

Depois de guardares o DSN, verifica-o e testa a ligação.

odbcinst -q -s
isql -k -v "DSN=FabricHCDSN;"

Quando uma cadeia de ligação não especifica um valor, o driver lê estas definições do DSN:

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

O controlador também lê as definições apenas de compatibilidade TenantPrincipal e PoolMax. Use os nomes dos parâmetros na tabela de definições HC.

Desativar o modo HC

Podes desativar novas aquisições de sessão HC sem redistribuir o driver. Usa o método que corresponde à forma como ativaste o modo HC:

As definições da cadeia de ligação e do DSN têm prioridade sobre a alternativa da variável de ambiente. Estas alterações afetam apenas novas ligações. As sessões de HC existentes mantêm-se ativas até serem libertadas.

Compreenda o comportamento em tempo de execução do HC

• Validação:SQLDriverConnect rejeita valores booleanos de HC e inteiros positivos inválidos com SQLSTATE HY024. Rejeita um valor inválido de LivyMode e valores inválidos ou demasiado grandes de WorkspaceId, LakehouseId e IdempotencyKey com SQLSTATE HY000. Um valor de compatibilidade TenantPrincipal sobredimensionado também devolve HY000. Para apenas SQLConnectDSN, o driver regista falhas normais de validação HC e utiliza o modo clássico. Valores sensíveis do ponto de vista da segurança demasiado grandes continuam a fazer falhar a ligação.
• Dados sensíveis: O driver exclui ou elimina IdempotencyKey outros campos sensíveis dos registos HC e da saída de diagnóstico.
• Cancelamento: O cancelamento do extrato é cooperativo. O trabalho do servidor já em curso é concluído de forma controlada, em vez de ser interrompido imediatamente.
• Disjuntores: Os modos HC e clássico usam disjuntores separados. Esgotar um modo não afeta o outro.
• Base de dados inicial: As ligações HC não executam a instrução inicial USE para o Database parâmetro. Execute USE <database> após estabelecer a ligação ou utilize nomes de tabelas completamente qualificados.
• Diagnósticos: Configure LogLevel=DEBUG para registar decisões relativas à aquisição, sondagem, libertação e mapeamento de erros de HC. Para uma resolução de problemas direcionada, configure LIVY_HC_VERBOSE=1 para incluir diagnósticos HTTP adicionais do HC anonimizados.

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

Se ~/.odbc.ini existir, adicione a nova secção DSN sem substituir o ficheiro existente. Copie o modelo instalado apenas quando criar o ficheiro:

if [ -e "$HOME/.odbc.ini" ]; then
    echo "Preserve ~/.odbc.ini and add the new DSN section manually."
else
    cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template "$HOME/.odbc.ini"
fi

Edite o ~/.odbc.ini com os dados do seu espaço de trabalho do 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 -k -v "DSN=FabricDSN;"

O isql comando requer as ferramentas de linha de comandos unixODBC. A opção -k utiliza SQLDriverConnect, o que permite ao controlador processar atributos de ligação por DSN.

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 -k -v "DSN=FabricDSN;"

Execute uma única consulta:

echo "SELECT 1 AS test" | isql -k -v "DSN=FabricDSN;" -b

Utilize -k para DSNs do Fabric para que isql se ligue através de SQLDriverConnect em vez de SQLConnect.

Trabalhe 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. Verifica que /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-2.0.0-Linux.deb.

Controlador não encontrado após a instalação de um ficheiro tar

Problema: O condutor está registado, mas a biblioteca partilhada não está presente no caminho registado.

Soluções:

1. Verifique se /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so existe.
2. Executar novamente sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Se usaste um prefixo personalizado, verifica se o caminho do driver registado usa o mesmo prefixo.

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. Verifique se ~/.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. Verifique se o ID do espaço de trabalho 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-2.0.0-Linux.deb.
2. Verifique se /usr/lib/libmicrosoftfabricodbc.so existe.
3. Executa sudo ldconfig para atualizar a cache da biblioteca partilhada.

Tempos limite de consulta

Problema: As consultas expiram em tabelas grandes.

Soluções:

1. Adicionar LargeTableSupport=true à cadeia de conexão.
2. Ajuste PageSizeBytes para o 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

Ativar o registo detalhado num 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:

• DEBUG: Inclui informação detalhada de depuração e é o nível de registo do controlador mais verboso.
• 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