Driver ODBC da Microsoft para Microsoft Fabric Data Engineering (Prévia)

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 da Fabric, o driver fornece conectividade Spark SQL segura e flexível para as suas aplicações e ferramentas de BI compatíveis com .NET, Python e outras 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
• 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

O Microsoft ODBC Driver para Microsoft Fabric Data Engineering versão 1.0.0 está em pré-visualização pública, que pode ser descarregado neste link do centro de downloads.

• 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. Faça duplo clique MicrosoftFabricODBCDriver-1.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-1.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-1.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 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

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

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

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

Configuração 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
   • 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()

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. Verifica que o ID do workspace e o Lakehouse ID são os GUIDs corretos
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:

• TRACE: O mais verboso, inclui todas as chamadas de API
• DEBUG: Informação detalhada de depuração
• 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