Controlador ODBC da Microsoft para Microsoft Fabric Data Engineering

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. Baseado nas APIs Livy do Fabric, o driver fornece conectividade Spark SQL segura e flexível às suas aplicações C/C++, .NET, Python e a outras aplicações e ferramentas de BI compatíveis com ODBC.

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 autenticação CLI do Azure, interativa, credenciais de cliente, baseada em certificados e autenticação por token de acesso
• Suporte para consultas SQL Spark: 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, STRUCT)
• Reutilização de sessões: Gestão de sessões integrada para melhorar o desempenho
• Modo de alta concorrência: Optar por sessões partilhadas e quentes do lado do servidor do Livy para reduzir a latência de arranque da ligação e a expansão do cluster Spark
• Suporte a tabelas grandes: Tratamento otimizado para grandes conjuntos de resultados com tamanhos de página configuráveis
• Prefetch assíncrono: Carregamento de dados em segundo plano para melhorar o desempenho
• Suporte a proxys: 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
• Integração OneLake: Aceder aos dados do lakehouse armazenados no OneLake, incluindo tabelas em múltiplos esquemas, através de uma interface ODBC unificada sem configuração de armazenamento separada
• Suporte a elementos de ambiente: Anexar elementos de ambiente Fabric durante a execução do trabalho para aplicarem bibliotecas de espaço de trabalho, propriedades Spark e variáveis a cada sessão
• Custom Spark configuration: Passe as propriedades de configuração do Spark diretamente pela cadeia de ligação para ajustar o comportamento da sessão

Pré-requisitos

Antes de usar o Microsoft ODBC Driver para Engenharia de Dados Microsoft Fabric, certifique-se de que tem:

• Sistema operativo: Windows 10/11 ou Windows Server 2016+
• Fabric Access: Acesso a um espaço de trabalho Fabric
• Credenciais Microsoft Entra ID: Credenciais adequadas para autenticação
• IDs de espaço de trabalho e casa do lago: identificadores GUID para o seu espaço de trabalho Fabric e casa do lago
• CLI do Azure (opcional): Necessário para o método de autenticação CLI do Azure

Download e instalação do MSI

• Descarregar o Microsoft ODBC Driver para Microsoft Fabric Data Engineering (zip)

1. Descarregue o pacote MSI do Driver ODBC da Microsoft para o Microsoft Fabric Data Engineering
2. Clique duas vezes em MicrosoftFabricODBCDriver-2.0.msi.
3. Siga o assistente de instalação e aceite o contrato de licença
4. Escolher diretório de instalação (predefinido: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Concluir a instalação

Instalação silenciosa

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

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

Verificar a instalação

Após a instalação, verifique se o driver está registado:

1. Execute odbcad32.exe (Administrador da Fonte de Dados ODBC)
2. Ir para o separador Drivers
3. Verifique que "Microsoft ODBC Driver for Microsoft Fabric Data Engineering" está listado

Exemplo de início rápido

Este exemplo demonstra como se ligar ao Fabric e executar uma consulta usando o Microsoft ODBC Driver for Microsoft Fabric Data Engineering. Antes de executar este código, certifique-se de que cumpriu os pré-requisitos e instalou o driver.

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

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

Exemplo do .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 da cadeia de conexão

Cadeia básica de ligação

O Driver Microsoft ODBC para Engenharia de Dados Microsoft Fabric utiliza o seguinte formato de string 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

Conexão básica (autenticação CLI do Azure)

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

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

Com registo

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

Com 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

Consulte a secção Modo de Alta Concorrência (HC) para obter instruções completas para a configuração.

Authentication

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering suporta múltiplos métodos de autenticação através do Microsoft Entra ID (anteriormente Azure Active Directory). A autenticação é configurada usando o AuthFlow parâmetro na cadeia de ligação.

Métodos de autenticação

Pode especificar valores de autenticação em snake case em maiúsculas, em Pascal case ou em formato numérico. O driver também aceita pseudónimos curtos como Browser, Interactive, CLI, Certificate, Token, e File. O controlador ignora os carateres de sublinhado quando compara os valores.

Autenticação da CLI do Azure

Melhor para: Desenvolvimento e aplicações interativas

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

Prerequisites:

• CLI do Azure instalado: az --version
• Sessão iniciada: az login

Autenticação interativa do navegador

Melhor para: Aplicações voltadas para utilizadores

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

Comportamento:

• Abre uma janela do navegador para autenticação do utilizador
• As credenciais são armazenadas em cache para ligações subsequentes

Autenticação de credenciais do cliente (service principal)

Ideal para: Serviços automatizados e tarefas 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};"
)

Parâmetros necessários

• TenantId: ID de inquilino Azure
• ClientId: ID da aplicação (cliente) a partir do ID Microsoft Entra
• ClientSecret: Segredo do cliente do Microsoft Entra ID

Melhores práticas

• Armazenar segredos de forma segura (Azure Key Vault, variáveis de ambiente)
• Use identidades geridas sempre que possível
• Alterne os segredos regularmente

Autenticação baseada em certificado

Ideal para: aplicações empresariais que requerem autenticação baseada em 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=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

Parâmetros exigidos:

• TenantId: ID de inquilino Azure
• ClientId: ID da aplicação (cliente)
• CertificatePath: Caminho para o ficheiro de certificado PFX/PKCS12
• CertificatePassword: Palavra-passe do certificado

Autenticação de token de acesso

Melhor para: cenários de autenticação 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};"
)

Autenticação por token de ficheiro

Utilize a autenticação por token de ficheiro para ambientes em contentores e pipelines automatizados, nos quais outro processo escreve um token bearer no ficheiro de token predefinido do controlador:

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

O driver resolve a localização do ficheiro token no Windows e Linux.

Nomes alternativos de propriedades entre controladores

O driver ODBC aceita nomes selecionados de propriedades ADO.NET e JDBC, além dos nomes ODBC nativos. Este suporte pode reduzir alterações na cadeia de ligação quando se passa entre drivers Fabric.

O controlador resolve 17 aliases entre controladores ao estabelecer a ligação.

Parâmetros de configuração

Parâmetros necessários

Estes parâmetros devem estar presentes em cada cadeia de conexã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 é opcional. 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 de recurso de 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 HC desativado. Os on aliases e off aplicam-se apenas a valores DSN e de strings de ligação.

Definições do ambiente

Podes anexar um item do ambiente Fabric à sessão Spark iniciada pelo driver. As bibliotecas, propriedades do Spark e variáveis do ambiente selecionado são automaticamente aplicadas quando a sessão é criada.

Exemplo de cadeia de conexão com item de ambiente:

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

Configuração personalizada do Spark

Podes passar as propriedades de configuração do Spark diretamente na cadeia de ligação. Qualquer parâmetro com o prefixo spark. é automaticamente aplicado à sessão Spark no momento da criação, permitindo-lhe sobrepor os predeterminados do workspace ou do tempo de execução.

Exemplos de configurações do Spark:

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

Exemplo de string de conexão com propriedades personalizadas do 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 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.

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 HC mínima (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

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

HC com 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 (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

Podes guardar as definições HC num DSN em vez de as repetir em cada cadeia de ligação. 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. Para guardar estas definições, edite a DSN em odbcad32.exe ou use SQLWritePrivateProfileString. 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.

Configurar um DSN

Criar um sistema DSN

1. Abrir o Administrador ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Criar Novo Sistema DSN

   • Vá ao separador "System DSN"
   • Selecione "Adicionar"
   • Selecione "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
   • Selecione "Terminar"

3. Configurar as Definições da DSN

   • Nome da Fonte de Dados: Insira um nome único (por exemplo, FabricODBC)
   • Descrição: Descrição opcional
   • ID do espaço de trabalho: GUID do seu espaço de trabalho Fabric
   • Lakehouse ID: O seu GUID do Lakehouse Fabric
   • Autenticação: Selecionar método de autenticação
   • ID de Ambiente (opcional): Introduza o GUID do item de ambiente Fabric a anexar durante a criação da sessão
   • Modo Livy (opcional): Defina como HighConcurrency para ativar o modo HC
   • Etiqueta da sessão (opcional): Introduza uma etiqueta operacional não sensível para correspondência de sessões do HC
   • Configure definições adicionais conforme necessário

4. Testar conexão

   • Selecione "Testar Ligação" para verificar as definições
   • Selecione "OK" para guardar

Utilizar DSN em aplicações

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

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

Exemplos de utilização

Ligação básica e consulta

Python

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

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

Executar instruções 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 com as instruções INSERT, UPDATE ou DELETE. A contagem de linhas reportada depende se o resultado contém uma contagem de atualizações reconhecida pelo driver.

Descoberta de esquema

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

Mapeamento de tipos de dados

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

Integração com ferramentas de BI

Microsoft Excel

1. Abrir Excel -> Dados -> Obter Dados -> De Outras Fontes -> Do ODBC
2. Selecione o seu DSN configurado (por exemplo, FabricODBC)
3. Autentique se for solicitado
4. Navegue e selecione tabelas
5. Carregar dados numa folha de cálculo Excel

Power BI Desktop

1. Abrir Power BI Desktop -> Obter Dados -> ODBC
2. Selecione o seu DSN configurado
3. Navegue pelo catálogo de dados e selecione tabelas
4. Transformar dados conforme necessário
5. Criar visualizações

SQL Server Management Studio (Servidor Ligado)

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

Solução de problemas

Esta secção fornece orientações para resolver problemas comuns que possa encontrar ao utilizar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering.

Problemas comuns

As secções seguintes descrevem problemas comuns e as suas soluções:

Falhas de ligação

Problema: Não consigo ligar 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. Verificar a autenticação do CLI do Azure: az account show
3. Garante que tens as permissões adequadas 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 falha com o CLI do Azure

Soluções:

• Executar az login para atualizar as credenciais
• Verifique o inquilino correto: az account set --subscription <subscription-id>
• Verificar a validade do token: az account get-access-token --resource https://api.fabric.microsoft.com

Tempos limite da consulta

Problema: Consultas a exceder o tempo limite em tabelas muito grandes

Soluções:

• Ativar LargeTableSupport=true
• Ajusta PageSizeBytes para o tamanho ótimo do bloco
• Ativar a pré-busca assíncrona: EnableAsyncPrefetch=1
• Use LIMIT cláusula para restringir o tamanho do resultado

Ativar log

Ao resolver problemas, ativar registos detalhados pode ajudar a identificar a causa raiz dos problemas. Podes ativar o registo através da cadeia de ligação.

Para permitir registos detalhados:

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

Níveis de log:

• DEBUG: Informações detalhadas de depuração e o nível de registo do controlador mais detalhado
• INFO: Informação geral (predefinição)
• WARN: Apenas avisos
• ERROR: Apenas erros

Rastreio ODBC

Para diagnósticos de baixo nível, pode ativar o rastreamento ODBC do Windows para capturar chamadas detalhadas de API ODBC e o comportamento dos drivers. Lembre-se de desligar o rastreamento quando não for necessário para manter o desempenho ideal.

Para ativar o rastreamento ODBC:

1. Abrir odbcad32.exe
2. Ir ao separador "Traçar"
3. Definir o caminho do ficheiro de rastreio (por exemplo, C:\temp\odbctrace.log)
4. Selecione "Começar a Rastrear Agora"
5. Reproduza o problema
6. Selecione "Parar de Rastrear Agora"

Conteúdo relacionado

• Microsoft ODBC Driver para Microsoft Fabric Data Engineering em Linux
• 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