Driver Microsoft ADO.NET para Microsoft Fabric Data Engineering

ADO.NET é uma tecnologia de acesso a dados amplamente adotada no ecossistema .NET que permite às aplicações conectar-se e trabalhar com dados provenientes de bases de dados e plataformas de big data.

O Microsoft ADO.NET Driver for Fabric Data Engineering permite-lhe ligar, consultar e gerir cargas de trabalho Spark no Fabric com a fiabilidade e simplicidade dos padrões padrão ADO.NET. Baseado nas APIs Livy da Fabric, o driver fornece conectividade segura e flexível ao Spark SQL às suas aplicações .NET, utilizando as abstrações familiares DbConnection, DbCommand e DbDataReader.

Principais características

• APIs de ADO.NET: Conhecidas DbConnection, DbCommand, DbDataReader, DbParameter e DbProviderFactory abstrações para conectividade com o Spark SQL
• Autenticação Microsoft Entra ID: Múltiplos fluxos de autenticação, incluindo CLI do Azure, navegador interativo, credenciais de clientes, autenticação baseada em certificados e token de acesso
• Suporte Nativo de Consultas SQL Spark: Execução direta de instruções SQL Spark com consultas parametrizadas
• Suporte Abrangente de Tipos de Dados: Suporte para todos os tipos de dados SQL Spark, incluindo tipos complexos (ARRAY, MAP, STRUCT)
• Pool de Conexões: Gestão integrada de pools de ligações para melhorar o desempenho
• Reutilização de Sessões: Gestão eficiente das sessões Spark para reduzir a latência de arranque
• Sessões de alta concorrência: Opte por partilhar a capacidade Fabric Livy com REPLs separados para sessões HC alugadas simultaneamente
• Pré-busca Assíncrona: Carregamento de dados em segundo plano para melhorar o desempenho com grandes conjuntos de resultados
• Reconexão automática: Recuperação da sessão clássica após falhas de conexão; as falhas de HC são comunicadas para nova tentativa controlada pela aplicação

Pré-requisitos

Antes de usar o driver Microsoft ADO.NET para Engenharia de Dados Fabric, certifique-se de que tem:

• .NET Runtime: .NET 8.0 ou posterior
• Fabric Access: Acesso a um espaço de trabalho Fabric com capacidades de Engenharia de Dados
• Azure Entra ID Credentials: Credenciais apropriadas 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

Descarregar, incluir, referenciar e verificar

Descarregar o pacote NuGet

• Descarregue o driver Microsoft ADO.NET para Fabric Data Engineering (zip)
• Descarregue o driver Microsoft ADO.NET para Engenharia de Dados Fabric (tar)

Pacote NuGet de referência no seu projeto

Inclua o pacote NuGet descarregado no seu projeto e adicione uma referência do pacote ao ficheiro do projeto:

<ItemGroup>
    <PackageReference Include="Microsoft.Spark.Livy.AdoNet" Version="2.0.1" />
</ItemGroup>

Verificar a instalação

Após inclusão e referência, verifique se o pacote está disponível no seu projeto:

using Microsoft.Spark.Livy.AdoNet;

// Verify the provider is registered
var factory = LivyProviderFactory.Instance;
Console.WriteLine($"Provider: {factory.GetType().Name}");

Exemplo de início rápido

using Microsoft.Spark.Livy.AdoNet;

// Connection string with required parameters
string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

// Create and open connection
using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

// Execute a query
using var command = connection.CreateCommand();
command.CommandText = "SELECT 'Hello from Fabric!' as message";

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Formato da cadeia de conexão

Formato básico

O Driver ADO.NET da Microsoft utiliza o formato padrão de cadeia de conexão ADO.NET.

Parameter1=Value1;Parameter2=Value2;...

Parâmetros necessários

Parâmetros opcionais

Definições de ligação

Definições do pool de conexão

Configurações de concorrência elevada

Configurações de registo

Aliases entre drivers: O driver aceita nomes de propriedades JDBC e ODBC além dos nomes nativos de ADO.NET (por exemplo, WorkspaceId mapeia para FabricWorkspaceID, LakehouseId mapeia para FabricLakehouseID). Todos os nomes de propriedades são insensíveis a maiúsculas e minúsculas.

Exemplo de cadeias de conexão

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

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli

Ligação de alta concorrência

Está disponível uma elevada concorrência para ligações Microsoft Fabric. Defina HcEnabled=true; as APIs padrão de ligação e comandos ADO.NET permanecem inalteradas. Utilize o host não versionado da API Fabric para Server; o controlador utiliza FabricVersion=v1 e LivyApiVersion=2023-12-01 por defeito quando constrói o endpoint HC.

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;" +
    "HcEnabled=true;";

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

using var command = connection.CreateCommand();
command.CommandText = "SELECT 1 AS value";

object? result = await command.ExecuteScalarAsync();
Console.WriteLine($"Result: {result}");

Para obter orientações completas sobre a configuração, consulte a secção Modo de Alta Concorrência (HC).

Com opções de pool de conexões

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;ConnectionPoolEnabled=true;MaxPoolSize=10

Com reconexão automática e registo

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;AutoReconnect=true;LogLevel=Debug

Authentication

O Microsoft ADO.NET Driver 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 testes

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

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

Prerequisites:

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

Autenticação interativa do navegador

Melhor para: Aplicações voltadas para utilizadores

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=BrowserBased;" +
    "AuthTenantID=<tenant-id>;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync(); // Opens browser for authentication

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

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=ClientSecretCredential;" +
    "AuthTenantID=<tenant-id>;" +
    "AuthClientID=<client-id>;" +
    "AuthClientSecret=<client-secret>;";

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

Parâmetros Exigidos:

• AuthTenantID: ID de inquilino Azure
• AuthClientID: ID da aplicação (cliente) a partir do ID Microsoft Entra
• AuthClientSecret: Segredo do cliente do Microsoft Entra ID

Autenticação baseada em certificado

Ideal para: aplicações empresariais que requerem autenticação baseada em certificado

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=ClientCertificateCredential;" +
    "AuthTenantID=<tenant-id>;" +
    "AuthClientID=<client-id>;" +
    "AuthCertificatePath=C:\\certs\\mycert.pfx;" +
    "AuthCertificatePassword=<password>;";

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

Parâmetros Exigidos:

• AuthTenantID: ID de inquilino Azure
• AuthClientID: ID da aplicação (cliente)
• AuthCertificatePath: Caminho para o ficheiro de certificado PFX/PKCS12
• AuthCertificatePassword: Palavra-passe do certificado

Autenticação de token de acesso

Melhor para: cenários de autenticação personalizados

// Acquire token through your custom mechanism
string accessToken = await AcquireTokenFromCustomSourceAsync();

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AuthAccessToken;" +
    $"AuthAccessToken={accessToken};";

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

Exemplos de utilização

Ligação básica e consulta

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

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

Console.WriteLine($"Connected! Server version: {connection.ServerVersion}");

// Execute a query
using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM employees LIMIT 10";

using var reader = await command.ExecuteReaderAsync();

// Print column names
for (int i = 0; i < reader.FieldCount; i++)
{
    Console.Write($"{reader.GetName(i)}\t");
}
Console.WriteLine();

// Print rows
while (await reader.ReadAsync())
{
    for (int i = 0; i < reader.FieldCount; i++)
    {
        Console.Write($"{reader.GetValue(i)}\t");
    }
    Console.WriteLine();
}

Consultas parametrizadas

using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM orders WHERE order_date >= @startDate AND status = @status";

// Add parameters
command.Parameters.AddWithValue("@startDate", new DateTime(2024, 1, 1));
command.Parameters.AddWithValue("@status", "completed");

using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    Console.WriteLine($"Order: {reader["order_id"]}, Total: {reader["total"]:C}");
}

ExecuteScalar para um único valor

using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM customers";

var count = await command.ExecuteScalarAsync();
Console.WriteLine($"Total customers: {count}");

ExecuteNonQuery para operações DML

// INSERT
using var insertCommand = connection.CreateCommand();
insertCommand.CommandText = @"
    INSERT INTO employees (id, name, department, salary)
    VALUES (100, 'John Doe', 'Engineering', 85000)";

int rowsAffected = await insertCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Inserted {rowsAffected} row(s)"
    : "The insert completed, but the driver didn't return an update count.");

// UPDATE
using var updateCommand = connection.CreateCommand();
updateCommand.CommandText = "UPDATE employees SET salary = 90000 WHERE id = 100";

rowsAffected = await updateCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Updated {rowsAffected} row(s)"
    : "The update completed, but the driver didn't return an update count.");

// DELETE
using var deleteCommand = connection.CreateCommand();
deleteCommand.CommandText = "DELETE FROM employees WHERE id = 100";

rowsAffected = await deleteCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Deleted {rowsAffected} row(s)"
    : "The delete completed, but the driver didn't return an update count.");

Trabalhar com grandes conjuntos de resultados

using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM large_table";

using var reader = await command.ExecuteReaderAsync();

int rowCount = 0;
while (await reader.ReadAsync())
{
    // Process each row
    ProcessRow(reader);
    rowCount++;

    if (rowCount % 10000 == 0)
    {
        Console.WriteLine($"Processed {rowCount} rows...");
    }
}

Console.WriteLine($"Total rows processed: {rowCount}");

Descoberta de esquema

// List all tables
using var showTablesCommand = connection.CreateCommand();
showTablesCommand.CommandText = "SHOW TABLES";

using var tablesReader = await showTablesCommand.ExecuteReaderAsync();
Console.WriteLine("Available tables:");
while (await tablesReader.ReadAsync())
{
    int tableNameOrdinal = tablesReader.GetOrdinal("tableName");
    Console.WriteLine($"  {tablesReader.GetString(tableNameOrdinal)}");
}

// Describe table structure
using var describeCommand = connection.CreateCommand();
describeCommand.CommandText = "DESCRIBE employees";

using var schemaReader = await describeCommand.ExecuteReaderAsync();
Console.WriteLine("\nTable structure for 'employees':");
while (await schemaReader.ReadAsync())
{
    Console.WriteLine($"  {schemaReader["col_name"]}: {schemaReader["data_type"]}");
}

// Show databases
using var dbCommand = connection.CreateCommand();
dbCommand.CommandText = "SHOW DATABASES";

using var dbReader = await dbCommand.ExecuteReaderAsync();
Console.WriteLine("\nAvailable databases:");
while (await dbReader.ReadAsync())
{
    Console.WriteLine($"  {dbReader.GetString(0)}");
}

Usando LivyConnectionStringBuilder

using Microsoft.Spark.Livy.AdoNet;

var builder = new LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    ConnectionPoolingEnabled = true,
    MaxPoolSize = 10
};

using var connection = new LivyConnection(builder.ConnectionString);
await connection.OpenAsync();

Usando o DbProviderFactory

using System.Data.Common;
using Microsoft.Spark.Livy.AdoNet;

// Register the provider factory (typically done at application startup)
DbProviderFactories.RegisterFactory("Microsoft.Spark.Livy.AdoNet", LivyProviderFactory.Instance);

// Create connection using factory
var factory = DbProviderFactories.GetFactory("Microsoft.Spark.Livy.AdoNet");

using var connection = factory.CreateConnection();
connection.ConnectionString = connectionString;

await connection.OpenAsync();

using var command = factory.CreateCommand();
command.Connection = connection;
command.CommandText = "SELECT * FROM employees LIMIT 5";

using var reader = await command.ExecuteReaderAsync();
// Process results...

Modo de alta concorrência (HC)

O modo de alta concorrência (HC) ajuda as aplicações .NET a executar cargas de trabalho SQL Spark simultâneas sem provisionar uma sessão clássica Spark separada para cada ligação ADO.NET. O Fabric pode colocar ligações compatíveis na mesma sessão Livy gerida pelo servidor, fornecendo a cada ligação um ciclo Ler-Avaliar-Imprimir (REPL) isolado para a execução de instruções.

Este modelo pode reduzir o tempo de arranque da ligação, evitar o provisionamento repetido das sessões Spark e utilizar a capacidade do Fabric Spark de forma mais eficiente. A sua aplicação continua a usar APIs padrão ADO.NET, incluindo DbConnection, DbCommand, DbDataReader, OpenAsync, e Close.

O modo HC é de adesão voluntária. Se não o ativares, o driver usa o caminho de sessão clássico do Livy.

Escolha entre o modo HC e o modo clássico

Use o modo HC quando:

• Um serviço ASP.NET processa pedidos simultâneos que abrem ligações e executam consultas Spark SQL.
• Um serviço de processamento em segundo plano, uma tarefa agendada ou um pipeline de dados paralelo cria picos de ligações ADO.NET.
• Várias conexões apontam para o mesmo espaço de trabalho do Fabric e o mesmo lakehouse e utilizam configurações do Spark compatíveis.
• Reduzir o tempo de arranque da ligação e o provisionamento repetido das sessões Spark é importante.
• A sua carga de trabalho pode usar capacidade Spark partilhada e gerida pelo servidor, mantendo a execução de instruções isolada pelo REPL.

Use o modo clássico quando:

• A sua aplicação utiliza apenas uma ou algumas ligações duradouras.
• Cada ligação requer uma sessão Spark dedicada para carga de trabalho rigorosa ou isolamento de recursos.
• As ligações requerem configurações Spark substancialmente diferentes que não deveriam partilhar uma sessão subjacente.
• 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.

Como funcionam as conexões HC

Quando a sua aplicação chama Open ou OpenAsync e não está disponível nenhuma ligação em pool compatível, o controlador:

1. Solicita uma sessão HC ao Fabric.
2. Espera que a sessão fique pronta, até ao tempo limite de aquisição configurado.
3. Liga a ligação ADO.NET à sessão HC atribuída e ao REPL.
4. Encaminha comandos, consultas, pedidos de cancelamento e operações de limpeza através dos endpoints HC.

Sessões HC separadas alugadas em simultâneo usam REPLs separados. Os comandos na mesma ligação partilham a sessão HC e o REPL dessa ligação.

O agrupamento no cliente está ativado por predefinição. Fechar ou eliminar uma ligação elegível normalmente devolve a sua sessão HC física e o REPL ao pool local do processo para reutilização; não liberta necessariamente a atribuição remotamente. Com o agrupamento de ligações desativado, o fecho da ligação física efetua a limpeza de HC. Continue a utilizar instruções using para que as ligações lógicas sejam devolvidas prontamente.

Ativar o modo HC

O modo HC é de adesão voluntária. Se omitir hcEnabled ou o definir como false, o controlador utiliza o caminho clássico da sessão Livy.

Defina a propriedade hcEnabled como verdadeira para obter uma sessão HC:

hcEnabled=true;

Configurar agrupamento de sessões

HcSessionTag fornece uma dica do lado do servidor para agrupar sessões HC compatíveis numa sessão Livy subjacente. Uma etiqueta correspondente não garante a colocação na mesma sessão subjacente.

Se omitir a etiqueta ou fornecer um valor vazio ou composto apenas por espaços em branco, o controlador não a inclui no pedido de aquisição. Omitir a etiqueta não desativa o modo HC nem o empacotamento no lado do serviço. Defina uma etiqueta explícita quando instâncias ou cargas de trabalho relacionadas devem ser consideradas para capacidade partilhada. Use um rótulo operacional estável e não sensível, como reporting-service ou nightly-etl. Não inclua segredos, tokens de acesso, dados pessoais, identificadores de clientes ou texto de consulta.

A configuração do Spark também afeta a compatibilidade da sessão. Use HcConfOverrides para fornecer as definições do Spark incluídas na lista de permissões para a criação de sessões do HC:

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;AuthFlow=AzureCli;HcEnabled=true;HcConfOverrides="spark.executor.memory=8g;spark.executor.cores=4";

Para múltiplas substituições, coloque o valor completo HcConfOverrides entre aspas. Um ponto e vírgula sem aspas inicia outra propriedade da cadeia de ligação externa; não faz parte de HcConfOverrides. O analisador aceita valores entre aspas simples ou duplas, preserva pontos e vírgulas e sinais iguais dentro dos valores entre aspas, e decodifica aspas duplicadas correspondentes ('' ou ""). Os espaços em branco em torno dos nomes das propriedades e nas extremidades dos valores sem aspas são ignorados. Os espaços em branco dentro dos valores não entre aspas e todos os espaços em branco dentro dos valores entre aspas são preservados. Valores vazios sobrepõem-se aos predeterminados do ambiente, e a última propriedade duplicada vence.

Também pode deixar que LivyConnectionStringBuilder trate das aspas:

var builder = new Microsoft.Spark.Livy.AdoNet.LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    HcEnabled = true,
    HcConfOverrides = "spark.executor.memory=8g;spark.executor.cores=4"
};

string connectionString = builder.ConnectionString;

Estes exemplos requerem o Microsoft ADO.NET Driver versão 2.0.1 ou posterior. Adicione os identificadores do seu espaço de trabalho e do lago antes de abrir uma ligação. Ambos os overrides são enviados no pedido de criação de sessão HC como entradas separadas conf . Cada substituição deve usar uma destas chaves que distinguem maiúsculas de minúsculas:

• spark.sql.shuffle.partitions
• spark.executor.memory
• spark.executor.cores
• spark.driver.memory
• spark.sql.ansi.enabled
• spark.sql.legacy.timeParserPolicy
• spark.sql.session.timeZone
• livy.rsc.client.connect.timeout
• livy.rsc.server.idle-timeout

As citações mal formadas são rejeitadas sem incluir o conteúdo da cadeia de ligação no erro de análise sintática.

Use etiquetas e valores de configuração consistentes entre ligações que pretendam partilhar capacidade. O Fabric determina se um pedido pode usar uma sessão existente ou se requer outra sessão.

Configurar a temporização da aquisição

Utilize as seguintes definições para controlar quanto tempo o controlador aguarda por uma sessão HC:

Para a maioria das cargas de trabalho, mantém os valores padrão. Aumente o tempo limite de aquisição apenas quando a inicialização da capacidade demorar regularmente mais de cinco minutos.

Use o modo HC com agrupamento de ligações

O modo HC e o agrupamento de ligações do ADO.NET atuam em camadas diferentes:

• O modo HC gere a capacidade partilhada do Fabric Spark e as sessões Livy no servidor.
• O pooling de ligações ADO.NET reutiliza recursos de ligação geridos pelo driver na aplicação cliente.

Podes ativar ambas as funcionalidades. O agrupamento de ligações reduz o estabelecimento repetido de ligações no lado do cliente, enquanto o modo HC reduz a criação repetida de sessões Spark no lado do servidor. Dimensione o pool de ligação para a concorrência esperada da aplicação em vez de usar um pool grande para criar trabalho paralelo desnecessário.

No modo HC, AutoReconnect=true não repete transparentemente um comando falhado após um erro de sessão estagnada. A aplicação recebe a exceção e deve decidir se é seguro repetir a operação.

Desativar o modo HC

Para usar o modo clássico para novas ligações, remova HcEnabled da cadeia de ligação ou defina-a parafalse:

HcEnabled=false

A alteração afeta novas ligações e não descarrega as sessões HC acumuladas existentes. Encerrar ou eliminar ligações lógicas normalmente; as sessões físicas elegíveis podem permanecer no pool de clientes até serem desativadas.

ADO.NET limitações

• As transações não são suportadas.
• Os comandos suportam apenas o modo de comando por texto. Os modos de comando de procedimento armazenado e de tabela direta não são suportados.
• Prepare Não faz nada.
• Um comando deve conter uma instrução; o texto do comando com múltiplas instruções é rejeitado.
• Use ligações separadas e simultaneamente abertas para cargas de trabalho concorrentes. Os comandos numa mesma ligação partilham a mesma sessão e REPL.

Mapeamento de tipos de dados

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

Trabalhar com tipos complexos

O caminho de resultados HC não serializa de forma fiável valores nativos aninhados de ARRAY, MAP ou STRUCT como JSON. Converter valores complexos em strings JSON no Spark SQL antes de os desserializar:

using System.Text.Json;
using System.Collections.Generic;

using var command = connection.CreateCommand();
command.CommandText = """
    SELECT
        to_json(array_column) AS array_json,
        to_json(map_column) AS map_json,
        to_json(struct_column) AS struct_json
    FROM complex_table
    LIMIT 1
    """;

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    string arrayJson = reader.GetString(0);
    string mapJson = reader.GetString(1);
    string structJson = reader.GetString(2);

    var array = JsonSerializer.Deserialize<int[]>(arrayJson);
    var map = JsonSerializer.Deserialize<Dictionary<string, string>>(mapJson);
}

Troubleshooting

Esta secção fornece orientações para resolver problemas comuns que possa encontrar ao utilizar o Microsoft ADO.NET Driver for 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 FabricWorkspaceID e FabricLakehouseID são 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. Verificar a conectividade de rede a api.fabric.microsoft.com

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:

• Aumentar o tempo limite da instrução: LivyStatementTimeoutSeconds=1200.
• Usar a cláusula LIMIT para restringir o tamanho do resultado durante o desenvolvimento.
• Garantir que o cluster Spark dispõe de recursos adequados

Tempo de espera excedido na conexão ou na aquisição de HC

Problema: Uma ligação expira enquanto espera por uma ligação em pool ou uma sessão HC

Soluções:

• Para o tempo de espera do conjunto de clientes e o estabelecimento da ligação HTTP, consulte HttpConnectionTimeoutInSeconds.
• Para aquisição de HC, aumentar hcAcquireTimeoutSeconds dentro do intervalo suportado de 120 a 3.600 segundos.
• Verifique a disponibilidade de capacidade da rede Fabric
• Verificar se o workspace ainda não atingiu os limites de sessão

Ativar log

Ao resolver problemas, registos detalhados podem ajudar a identificar a causa raiz. Configurar o registo através da cadeia de ligação:

Para permitir registos detalhados através da cadeia de ligação:

LogLevel=Debug;LogFilePath=<path-to-log-file>

Se não definir LogFilePath ou uma configuração global de registo, o controlador grava os registos em %LOCALAPPDATA%\FabricSparkAdoNet\Logs no Windows.

Níveis de log:

• Trace: O mais verboso, inclui todas as chamadas de API
• Debug: Informação detalhada de depuração
• Information: Informação geral (predefinição)
• Warning: Apenas avisos
• Error: Apenas erros

Conteúdo relacionado

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