Driver ODBC da Microsoft para Engenharia de Dados do Microsoft Fabric (versão prévia)

O ODBC (Open Database Connectivity) é um padrão amplamente adotado que permite que os aplicativos cliente se conectem e trabalhem com dados de bancos de dados e plataformas de Big Data.

O Microsoft ODBC Driver for Fabric Data Engineering permite que você se conecte, consulte e gerencie cargas de trabalho do Spark no Microsoft Fabric com a confiabilidade e a simplicidade do padrão ODBC. Baseado nas APIs Livy do Microsoft Fabric, o driver fornece conectividade segura e flexível do Spark SQL com seu .NET, Python e outros aplicativos compatíveis com ODBC e ferramentas de BI.

Características principais

• Compatível com ODBC 3.x: implementação completa da especificação ODBC 3.x
• Autenticação do Microsoft Entra ID: vários fluxos de autenticação, incluindo CLI do Azure, interativo, credenciais do cliente, autenticação baseada em certificado e token de acesso
• Suporte à consulta SQL do Spark: execução direta de instruções SQL do Spark
• Suporte a tipos de dados abrangentes: suporte para todos os tipos de dados SQL do Spark, incluindo tipos complexos (ARRAY, MAP, STRUCT)
• Reutilização de sessão: gerenciamento de sessão interno para melhorar o desempenho
• Suporte à tabela grande: manipulação otimizada para grandes conjuntos de resultados com tamanhos de página configuráveis
• Pré-busca assíncrona: carregamento de dados em segundo plano para melhorar o desempenho
• Suporte a proxy: configuração de proxy HTTP para ambientes empresariais
• Suporte para Lakehouse com múltiplos esquemas: conecte-se a um esquema específico dentro de um Lakehouse
• integração OneLake: dados do Access Lakehouse armazenados no Microsoft OneLake, incluindo tabelas em vários esquemas, por meio de uma interface ODBC unificada sem configuração de armazenamento separada
• suporte a itens Environment: Anexar itens de ambiente Fabric durante a execução do trabalho para aplicar bibliotecas de workspace, propriedades do Spark e variáveis a cada sessão
• Custom Spark configuration: passe as propriedades de configuração do Spark diretamente pela string de conexão para ajustar o comportamento da sessão

Pré-requisitos

Antes de usar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering, verifique se você tem:

• Sistema operacional: Windows 10/11 ou Windows Server 2016+
• Microsoft Fabric Access: Acesso a um workspace do Microsoft Fabric
• Credenciais do Microsoft Entra ID: credenciais adequadas para autenticação
• IDs do Workspace e Lakehouse: identificadores GUID para o seu Workspace do Fabric e Lakehouse
• CLI do Azure (opcional): necessário para o método de autenticação da CLI do Azure

Baixar e instalar o MSI

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering versão 1.0.0 está em versão prévia pública que você pode baixar neste link do centro de download.

• Baixar Driver ODBC da Microsoft para Data Engineering do Microsoft Fabric (zip)

1. Baixar o pacote MSI do Microsoft ODBC Driver para Engenharia de Dados do Microsoft Fabric
2. Clique duas vezes MicrosoftFabricODBCDriver-1.0.msi
3. Siga o assistente de instalação e aceite o contrato de licença
4. Escolha o diretório de instalação (padrão: 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

Verifique a instalação

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

1. Executar odbcad32.exe (Administrador da Fonte de Dados ODBC)
2. Navegue até a guia Drivers
3. Verifique se "Microsoft ODBC Driver for Microsoft Fabric Data Engineering" está listado

Exemplo de início rápido

Este exemplo demonstra como se conectar ao Microsoft Fabric e executar uma consulta usando o Microsoft ODBC Driver for Microsoft Fabric Data Engineering. Antes de executar esse código, verifique se você concluiu 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 de .NET

using System.Data.Odbc;

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

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

Console.WriteLine("Connected successfully!");

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

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

Formato da cadeia de conexão

Cadeia de conexão básica

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering usa o seguinte formato de cadeia de conexão:

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

Componentes da cadeia de conexão

Cadeias de conexão de exemplo

Conexão básica (autenticação da 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 o registro de logs

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

Autenticação

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering dá suporte a vários métodos de autenticação por meio da ID do Microsoft Entra (anteriormente Azure Active Directory). A autenticação é configurada usando o AuthFlow parâmetro na cadeia de conexão.

Métodos de autenticação

Autenticação da CLI do Azure

Melhor para: desenvolvimento e aplicativos interativos

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

Pré-requisitos:

• CLI do Azure instalada: az --version
• Conectado: az login

Autenticação interativa do navegador

Melhor para: aplicativos voltados para o usuário

# 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 usuário
• As credenciais são armazenadas em cache para conexões subsequentes

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

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

Parâmetros necessários

• TenantId: ID do locatário do Azure
• ClientId: ID do aplicativo (cliente) da Microsoft Entra ID
• ClientSecret: segredo do cliente do Microsoft Entra ID

Práticas recomendadas

• Armazenar segredos com segurança (Azure Key Vault, variáveis de ambiente)
• Usar identidades gerenciadas quando possível
• Alternar segredos regularmente

Autenticação baseada em certificado

Melhor para: aplicativos empresariais que exigem 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 necessários:

• TenantId: ID do locatário do Azure
• ClientId: ID do aplicativo (cliente)
• CertificatePath: caminho para o arquivo de certificado PFX/PKCS12
• CertificatePassword: senha 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

Esses parâmetros devem estar presentes em todas as cadeias de conexão:

Parâmetros opcionais

Configurações de conexão

Configurações de desempenho

Configurações de registro em log

Configurações de proxy

Configurações de ambiente

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

Exemplo de cadeia de conexão com um 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

Você pode passar as propriedades de configuração do Spark diretamente no cadeia de conexão. Qualquer parâmetro prefixado com spark. é aplicado automaticamente à sessão do Spark no momento da criação, permitindo que você substitua os padrões de workspace ou runtime.

Exemplo 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 de DSN

Criar um DSN do sistema

1. Abrir Administrador ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Criar um novo DSN do sistema

   • Vá para a aba "DSN do Sistema"
   • Selecione "Adicionar"
   • Selecione "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
   • Selecione "Concluir"

3. Definir configurações de DSN

   • Nome da fonte de dados: insira um nome exclusivo (por exemplo, FabricODBC)
   • Descrição: descrição opcional
   • ID do espaço de trabalho: GUID do espaço de trabalho do Fabric
   • ID do Lakehouse: O GUID do Lakehouse do Fabric
   • Autenticação: selecionar método de autenticação
   • Environment ID (opcional): insira o GUID do item de ambiente Fabric a ser anexado durante a criação da sessão
   • Definir configurações adicionais conforme necessário

4. Testar Conexão

   • Selecione "Testar Conexão" para verificar as configurações
   • Selecione "OK" para salvar

Usar DSN em aplicativos

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

Conexão e consulta básicas

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

Trabalhando 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 tipo de dados

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

Integração de ferramentas de BI

Microsoft Excel

1. Abrir o Excel –> Dados –> Obter dados –> de outras fontes –> do ODBC
2. Selecione o DSN configurado (por exemplo, FabricODBC)
3. Autentique-se se solicitado
4. Navegar e selecionar tabelas
5. Carregar dados na planilha do Excel

Power BI Desktop

1. Abrir o Power BI Desktop –> Obter Dados –> ODBC
2. Selecione o DSN configurado
3. Navegar no catálogo de dados e selecionar tabelas
4. Transformar dados conforme necessário
5. Criar visualizações

SQL Server Management Studio (Servidor Vinculado)

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

Resolução de problemas

Esta seção fornece diretrizes para resolver problemas comuns que você pode encontrar ao usar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering.

Problemas comuns

As seções a seguir descrevem problemas comuns e suas soluções:

Falhas na conexão

Problema: não é possível se conectar ao Microsoft Fabric

Soluções:

1. Verificar se o ID do Workspace e o ID do Lakehouse são GUIDs corretos
2. Verifique a autenticação da CLI do Azure: az account show
3. Verifique se você tem permissões de workspace apropriadas do Fabric
4. Verificar as configurações de proxy e conectividade de rede

Erros de autenticação

Problema: a autenticação falha com a CLI do Azure

Soluções:

• Executar az login para atualizar credenciais
• Verifique o locatário 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 estão atingindo o tempo limite em tabelas grandes

Soluções:

• Habilitar LargeTableSupport=true
• Ajustar PageSizeBytes para o tamanho ideal do bloco
• Habilitar pré-busca assíncrona: EnableAsyncPrefetch=1
• Usar LIMIT cláusula para restringir o tamanho do resultado

Habilitar registro de log

Ao solucionar problemas, habilitar o log detalhado pode ajudá-lo a identificar a causa raiz dos problemas. Você pode habilitar o registro em log por meio da cadeia de conexão.

Para habilitar o registro em log detalhado:

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

Níveis de log:

• TRACE: mais detalhado, inclui todas as chamadas à API
• DEBUG: informações detalhadas de depuração
• INFO: informações gerais (padrão)
• WARN: somente avisos
• ERROR: apenas erros

Rastreamento ODBC

Para diagnósticos de baixo nível, você pode habilitar o rastreamento ODBC do Windows para capturar chamadas detalhadas da API ODBC e o comportamento do driver. Lembre-se de desativar o rastreamento quando não for necessário para manter o desempenho ideal.

Para habilitar o rastreamento ODBC:

1. Abrir odbcad32.exe
2. Vá para a guia "Rastreamento"
3. Definir caminho do arquivo de rastreamento (por exemplo, C:\temp\odbctrace.log)
4. Selecione "Iniciar Rastreamento Agora"
5. Reproduzir o problema
6. Selecione "Parar Rastreamento Agora"

Conteúdo relacionado

• Ambientes de execução do Apache Spark no Azure Fabric
• Fabric Runtime 1.3
• O que é a API livy para engenharia de dados
• Microsoft JDBC Driver for Microsoft Fabric Data Engineering