Microsoft ADO.NET sterownik dla Microsoft Fabric Data Engineering

ADO.NET jest powszechnie przyjętą technologią dostępu do danych w ekosystemie platformy .NET, która umożliwia aplikacjom łączenie się z danymi i pracę z danymi z baz danych i platform danych big data.

Sterownik Microsoft ADO.NET dla Fabric Data Engineering pozwala łączyć się, zapytywać i zarządzać obciążeniami Spark w Fabric z niezawodnością i prostotą standardowych wzorców ADO.NET. Sterownik, oparty na interfejsach API Livy platformy Fabric, zapewnia bezpieczną i elastyczną łączność Spark SQL dla aplikacji .NET przy użyciu znanych abstrakcji DbConnection, DbCommand i DbDataReader.

Kluczowe funkcje

• API ADO.NET: Znane DbConnection, DbCommand, DbDataReader, DbParameter, i DbProviderFactory abstrakcje dla łączności Spark SQL
• Microsoft Entra ID Authentication: wiele przepływów uwierzytelniania, w tym Azure CLI, przeglądarka interaktywna, poświadczenia klienta, uwierzytelnianie oparte na certyfikatach i uwierzytelnianie za pomocą tokenu dostępu
• Obsługa zapytań natywnych spark SQL: bezpośrednie wykonywanie instrukcji Spark SQL z zapytaniami sparametryzowanymi
• Kompleksowa obsługa typów danych: obsługa wszystkich typów danych Spark SQL, w tym typów złożonych (ARRAY, MAP, STRUCT)
• Buforowanie połączeń: wbudowane zarządzanie pulą połączeń dla lepszej wydajności
• Ponowne użycie sesji: wydajne zarządzanie sesjami platformy Spark w celu zmniejszenia opóźnienia uruchamiania
• Sesje o wysokiej współbieżności: Włącz współdzielone zasoby Fabric Livy z oddzielnymi środowiskami REPL dla jednocześnie przydzielanych sesji HC
• Asynchroniczne ładowanie wstępne: Ładowanie danych w tle w celu zwiększenia wydajności przy większych zestawach wyników
• Automatyczne ponowne łączenie: Przywracanie sesji klasycznej po awariach połączenia; błędy HC są zgłaszane na potrzeby ponowienia kontrolowanego przez aplikację

Wymagania wstępne

Przed użyciem sterownika Microsoft ADO.NET dla Fabric Data Engineering, upewnij się, że masz:

• Środowisko uruchomieniowe platformy .NET: .NET 8.0 lub nowszy
• Fabric Access: Dostęp do przestrzeni roboczej Fabric z możliwościami inżynierii danych
• Poświadczenia Azure Entra ID: odpowiednie poświadczenia do uwierzytelniania
• Identyfikatory obszaru roboczego i lakehouse: identyfikatory GUID dla obszaru roboczego Fabric i lakehouse
• Interfejs wiersza polecenia platformy Azure (opcjonalnie): wymagany dla metody uwierzytelniania interfejsu wiersza polecenia platformy Azure

Pobieranie, dołączanie, odwołanie i weryfikowanie

Pobieranie pakietu NuGet

• Pobierz sterownik Microsoft ADO.NET for Fabric Data Engineering (zip)
• Pobierz sterownik Microsoft ADO.NET for Fabric Data Engineering (tar)

Uwzględnij pakiet NuGet w projekcie

Dołącz pobrany pakiet NuGet do projektu i dodaj odwołanie do pakietu do pliku projektu:

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

Weryfikowanie instalacji

Po dodaniu pakietu i odwołaniu się do niego, sprawdź, czy jest on dostępny w projekcie:

using Microsoft.Spark.Livy.AdoNet;

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

Przykład szybkiego startu

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

Format ciągu połączenia

Format podstawowy

Sterownik microsoft ADO.NET używa standardowego formatu parametrów połączenia ADO.NET:

Parameter1=Value1;Parameter2=Value2;...

Wymagane parametry

Parametry opcjonalne

Ustawienia połączenia

Ustawienia puli połączeń

Ustawienia wysokiej współbieżności

Ustawienia rejestrowania

Aliasy między sterownikami: Sterownik akceptuje nazwy właściwości JDBC i ODBC oprócz natywnych nazw ADO.NET (np. WorkspaceId mapuje na FabricWorkspaceID, LakehouseId mapuje na FabricLakehouseID). Wszystkie nazwy właściwości są niewrażliwe na wielkość liter.

Przykładowe parametry połączenia

Połączenie podstawowe (uwierzytelnianie Azure CLI)

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

Połączenie o wysokiej współbieżności

Wysoka równocześność jest dostępna dla połączeń Microsoft Fabric. ustaw HcEnabled=true; standardowe API połączenia i poleceń ADO.NET pozostają bez zmian. Używaj niewersjonowanego hosta interfejsu Fabric API w przypadku Server; sterownik podczas tworzenia punktu końcowego HC domyślnie używa FabricVersion=v1 i LivyApiVersion=2023-12-01.

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

Pełne wskazówki dotyczące konfiguracji można znaleźć w sekcji High-Concurrency (HC) Mode .

Z opcjami buforowania połączeń

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

Wraz z automatycznym ponownym nawiązywaniem połączenia i rejestrowaniem

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

Uwierzytelnianie

Sterownik microsoft ADO.NET obsługuje wiele metod uwierzytelniania za pomocą identyfikatora Entra firmy Microsoft (dawniej Azure Active Directory). Uwierzytelnianie jest konfigurowane przy użyciu parametru AuthFlow w parametrach połączenia.

Metody uwierzytelniania

Uwierzytelnianie CLI platformy Azure

Najlepsze dla: Programowanie i testowanie

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:

• Zainstalowany interfejs wiersza polecenia platformy Azure: az --version
• Zalogowano: az login

Uwierzytelnianie za pomocą przeglądarki interakcyjnej

Najlepsze dla: aplikacje przeznaczone dla użytkowników

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

Zachowanie:

• Otwiera okno przeglądarki na potrzeby uwierzytelniania użytkownika
• Poświadczenia są buforowane dla kolejnych połączeń

Uwierzytelnianie poświadczeń klienta (jednostki usługi)

Najlepsze dla: Zautomatyzowane usługi i zadania w tle

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

Wymagane parametry:

• AuthTenantID: Identyfikator dzierżawy platformy Azure
• AuthClientID: Identyfikator aplikacji (klienta) z Microsoft Entra ID
• AuthClientSecret: Tajny klucz klienta od Microsoft Entra ID

Uwierzytelnianie oparte na certyfikatach

Najlepsze rozwiązanie: Aplikacje dla przedsiębiorstw wymagające uwierzytelniania opartego na certyfikatach

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

Wymagane parametry:

• AuthTenantID: Identyfikator dzierżawy platformy Azure
• AuthClientID: Identyfikator aplikacji (klienta)
• AuthCertificatePath: Ścieżka do pliku certyfikatu PFX/PKCS12
• AuthCertificatePassword: Hasło certyfikatu

Uwierzytelnianie tokenu dostępu

Najlepszy dla: niestandardowe scenariusze uwierzytelniania

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

Przykłady użycia

Podstawowe połączenie i zapytanie

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

Zapytania sparametryzowane

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 dla pojedynczych wartości

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

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

ExecuteNonQuery dla operacji 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.");

Praca z dużymi zestawami wyników

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

Odnajdywanie schematów

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

Korzystanie z 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();

Korzystanie z 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...

Tryb wysokiej współbieżności (HC)

Tryb wysokiej współbieżności (HC) pomaga aplikacjom .NET uruchamiać równoczesne obciążenia Spark SQL bez konieczności przydzielania osobnej klasycznej sesji Spark dla każdego połączenia ADO.NET. Fabric może umieszczać zgodne połączenia w tej samej sesji Livy zarządzanej przez serwer, zapewniając każdemu połączeniu izolowaną pętlę odczytu, ewaluacji i wyświetlania (REPL) do wykonywania poleceń.

Model ten może skrócić czas uruchomienia połączenia, uniknąć powtarzającego się aranżowania sesji Spark oraz efektywniej wykorzystać pojemność Fabric Spark. Twoja aplikacja nadal korzysta ze standardowych API ADO.NET, w tym DbConnection, DbCommand, DbDataReader, OpenAsync, oraz Close.

Tryb HC wymaga włączenia. Jeśli go nie włączysz, sterownik korzysta z klasycznej ścieżki sesji Livy.

Wybierz między trybem HC a klasycznym

Używaj trybu HC, gdy:

• Usługa ASP.NET obsługuje jednoczesne żądania otwierające połączenia i uruchamiające Spark SQL.
• Usługa pracownicza, zaplanowane zadanie lub równoległy potok danych generuje serie połączeń ADO.NET.
• Wiele połączeń jest skierowanych do tej samej przestrzeni roboczej Fabric i domku nad jeziorem oraz wykorzystuje kompatybilne konfiguracje Spark.
• Skrócenie czasu uruchamiania połączenia i powtarzającego się udostępniania sesji w Spark jest ważne.
• Twoje obciążenie robocze może korzystać ze współdzielonej pojemności platformy Spark zarządzanej przez serwer, przy jednoczesnym zachowaniu izolacji wykonywania instrukcji przez REPL.

Użyj trybu klasycznego, gdy:

• Twoja aplikacja korzysta tylko z jednego lub kilku długotrwałych połączeń.
• Każde połączenie wymaga dedykowanej sesji Spark do ścisłej izolacji obciążenia lub zasobów.
• Połączenia wymagają znacznie innych konfiguracji Sparka, które nie powinny współdzielić bazowej sesji.
• Punkt końcowy usługi Fabric Livy dla docelowego obszaru roboczego i lakehouse nie obsługuje trybu HC.

Jak działają połączenia HC

Gdy aplikacja wywołuje Open lub OpenAsync, a żadne zgodne połączenie z puli nie jest dostępne, sterownik:

1. Żąda sesji HC od Fabric.
2. Czeka, aż sesja będzie gotowa, maksymalnie do skonfigurowanego limitu czasu uzyskania.
3. Łączy połączenie ADO.NET z przypisaną sesją HC i REPL.
4. Kieruje komendy, zapytania, żądania anulowania oraz operacje czyszczenia za pośrednictwem punktów końcowych HC.

Oddzielne, jednocześnie dzierżawione sesje HC używają oddzielnych REPL-ów. Polecenia w ramach jednego połączenia współdzielą sesję HC i REPL danego połączenia.

Pulowanie po stronie klienta jest domyślnie włączone. Zamknięcie lub usunięcie kwalifikującego się połączenia zwykle powoduje zwrócenie jego fizycznej sesji HC i REPL do puli lokalnej dla procesu w celu ponownego użycia; nie musi jednak zwalniać tego przypisania po stronie zdalnej. Po wyłączeniu puli połączeń zamknięcie fizycznego połączenia powoduje wyczyszczenie HC. Kontynuuj używanie using instrukcji, aby logiczne połączenia wracały szybko.

Włącz tryb HC

Tryb HC wymaga włączenia. Jeśli pominiesz hcEnabled lub ustawisz false, sterownik używa klasycznej ścieżki sesji Livy.

Ustaw właściwość hcEnabled na true, aby uzyskać sesję HC:

hcEnabled=true;

Konfiguruj pakowanie sesji

HcSessionTag udostępnia wskazówkę po stronie serwera dotyczącą grupowania zgodnych sesji HC w bazowej sesji Livy. Pasujący tag nie gwarantuje przypisania do tej samej sesji bazowej.

Jeśli pominiesz znacznik lub podasz pustą wartość albo wartość składającą się wyłącznie z białych znaków, sterownik nie wyśle jej w żądaniu uzyskania. Pominięcie tagu nie wyłącza trybu HC ani pakowania po stronie serwisowej. Ustaw jawny tag, gdy powiązane instancje aplikacji lub obciążenia mają być traktowane jako korzystające ze współdzielonej pojemności. Użyj stabilnej, niewrażliwej etykiety operacyjnej, takiej jak reporting-service lub nightly-etl. Nie zawieraj sekretów, tokenów dostępu, danych osobowych, identyfikatorów klientów ani tekstów zapytań.

Konfiguracja Spark wpływa także na zgodność sesji. Użyj HcConfOverrides, aby określić ustawienia Spark z listy dozwolonych na potrzeby tworzenia sesji HC:

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

Dla wielu przejęć podaj całą HcConfOverrides wartość. Niecytowany średnik rozpoczyna kolejną właściwość zewnętrznego ciągu połączeń; nie przedłuża HcConfOverrides. Parser akceptuje wartości ujęte w pojedynczy lub podwójny cudzysłów, zachowuje średniki i znaki równości wewnątrz wartości ujętych w cudzysłów oraz dekoduje podwojone cudzysłowy tego samego typu ('' lub ""). Białe znaki wokół nazw właściwości oraz na początku i na końcu wartości nieujętych w cudzysłowy są ignorowane. Białe przestrzenie w niecytowanych wartościach oraz wszystkie odstępy wewnątrz cytowanych wartości są zachowane. Wartości puste nadpisują domyślne ustawienia środowiska, a ostatnia zduplikowana właściwość wygrywa.

Możesz też powierzyć LivyConnectionStringBuilder wycenę:

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;

Te przykłady wymagają sterownika Microsoft ADO.NET w wersji 2.0.1 lub nowszej. Dodaj identyfikatory swojego miejsca pracy i domów nad jeziorem przed otwarciem połączenia. Oba nadpisania są wysyłane w żądaniu HC create-session jako oddzielne elementy conf. Każde nadpisanie musi używać jednego z następujących kluczy z rozróżnieniem wielkości liter:

• 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

Nieprawidłowe cudzysłowy są odrzucane bez dołączania zawartości parametrów połączenia do komunikatu błędu analizy składniowej.

Używaj spójnych tagów i wartości konfiguracyjnych między połączeniami, które mają współdzielić pojemność. Fabric określa, czy żądanie może korzystać z istniejącej sesji, czy wymaga innej sesji.

Konfiguruj czas akwizycji

Użyj następujących ustawień, aby kontrolować, jak długo sterownik czeka na sesję HC:

Dla większości obciążeń zachowaj wartości domyślne. Czas na przejęcie wydłużaj tylko wtedy, gdy uruchomienie mocy regularnie trwa dłużej niż pięć minut.

Użyj trybu HC z pulą połączeń

Tryb HC i pula połączeń ADO.NET dotyczą różnych warstw:

• Tryb HC zarządza współdzieloną pojemnością usługi Fabric Spark oraz sesjami Livy na serwerze.
• Pula połączeń w ADO.NET umożliwia ponowne wykorzystywanie zasobów połączeń zarządzanych przez sterownik w aplikacji klienckiej.

Możesz włączyć obie funkcje. Pula połączeń zmniejsza powtarzające się konfiguracje połączeń po stronie klienta, podczas gdy tryb HC ogranicza powtarzające się aprowizowanie sesji Spark po stronie serwera. Dostosuj rozmiar puli połączeń do oczekiwanego poziomu współbieżności aplikacji, zamiast używać dużej puli, co prowadzi do zbędnej pracy równoległej.

W trybie HC AutoReconnect=true nie odtwarza automatycznie nieudanego polecenia po błędzie nieaktualnej sesji. Aplikacja otrzymuje wyjątek i musi zdecydować, czy ponowne wykonanie operacji jest bezpieczne.

Wyłącz tryb HC

Aby użyć trybu klasycznego dla nowych połączeń, usuń HcEnabled z parametry połączenia lub ustaw go na:false

HcEnabled=false

Zmiana dotyczy nowych połączeń i nie usuwa istniejących połączonych sesji HC. Zamykaj lub usuwaj połączenia logiczne w normalny sposób; odpowiednie sesje fizyczne mogą pozostać w puli klienta do czasu ich wycofania.

ograniczenia ADO.NET

• Transakcje nie są obsługiwane.
• Polecenia obsługują wyłącznie tryb poleceń tekstowych. Tryby poleceń „procedura składowana” i „bezpośredni dostęp do tabeli” nie są obsługiwane.
• Prepare Nic nie robi.
• Polecenie musi zawierać jedno zdanie; tekst polecenia wieloinstrukcyjny jest odrzucany.
• Używaj oddzielnych, jednocześnie otwartych połączeń dla równoczesnych obciążeń. Polecenia w ramach jednego połączenia współdzielą sesję i REPL.

Mapowanie typu danych

Sterownik mapuje typy danych Spark SQL na typy platformy .NET:

Praca z typami złożonymi

Ścieżka wynikowa HC nie serializuje w sposób niezawodny natywnych zagnieżdżonych wartości typu ARRAY, MAP ani STRUCT do formatu JSON. Konwertuj wartości złożone na ciągi JSON w Spark SQL przed deserializacją:

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

Ta sekcja dostarcza wskazówek dotyczących rozwiązania typowych problemów, na które możesz się spotkać podczas korzystania ze sterownika Microsoft ADO.NET for Fabric Data Engineering.

Typowe problemy

W poniższych sekcjach opisano typowe problemy i ich rozwiązania:

Awarie połączenia

Problem: Nie można połączyć się z Fabric

Rozwiązania:

1. Sprawdź, czy FabricWorkspaceID i FabricLakehouseID są prawidłowymi identyfikatorami GUID
2. Sprawdź uwierzytelnianie Azure CLI: az account show
3. Upewnij się, że masz odpowiednie uprawnienia obszaru roboczego usługi Fabric
4. Zweryfikuj łączność sieciową z api.fabric.microsoft.com

Błędy uwierzytelniania

Problem: Uwierzytelnianie kończy się niepowodzeniem za pomocą Azure CLI

Rozwiązania:

• Uruchom az login aby odświeżyć poświadczenia
• Sprawdź poprawnego dzierżawcę: az account set --subscription <subscription-id>
• Sprawdź ważność tokenu: az account get-access-token --resource https://api.fabric.microsoft.com

Limit czasu zapytania

Problem: Limit czasu zapytań w dużych tabelach

Rozwiązania:

• Zwiększ limit czasu wykonywania instrukcji: LivyStatementTimeoutSeconds=1200.
• Użyj klauzuli LIMIT do ograniczenia rozmiaru wyniku podczas rozwoju.
• Upewnij się, że klaster Spark ma odpowiednie zasoby

Limit czasu połączenia lub akwizycji HC

Problem: Upływa limit czasu połączenia podczas oczekiwania na połączenie z puli lub sesję HC

Rozwiązania:

• W przypadku oczekiwania na połączenie z puli klientów i ustanawiania połączenia HTTP zapoznaj się z HttpConnectionTimeoutInSeconds.
• Aby uzyskać HC, zwiększ wartość hcAcquireTimeoutSeconds do wartości z obsługiwanego zakresu od 120 do 3600 sekund.
• Sprawdzanie dostępności pojemności sieci szkieletowej
• Sprawdź, czy obszar roboczy nie osiągnął limitów sesji

Włącz rejestrowanie

Podczas rozwiązywania problemów szczegółowe logowanie może pomóc zidentyfikować przyczynę źródłową. Skonfiguruj rejestrowanie za pomocą parametrów połączenia:

Aby włączyć szczegółowe rejestrowanie za pośrednictwem parametrów połączenia:

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

Jeśli nie ustawisz LogFilePath ani globalnej konfiguracji rejestrowania, sterownik zapisuje dzienniki w lokalizacji %LOCALAPPDATA%\FabricSparkAdoNet\Logs w systemie Windows.

Poziomy logów:

• Trace: Najbardziej szczegółowy, obejmuje wszystkie wywołania interfejsu API
• Debug: Szczegółowe informacje o debugowaniu
• Information: Ogólne informacje (ustawienie domyślne)
• Warning: Tylko ostrzeżenia
• Error: Tylko błędy

Treści powiązane

• Środowiska uruchomieniowe platformy Apache Spark w Fabric
• Środowisko uruchomieniowe Fabric 1.3
• Co to jest interfejs API Livy do inżynierii danych
• Microsoft JDBC Driver for Fabric Data Engineering
• Sterownik ODBC firmy Microsoft dla rozwiązania Fabric do inżynierii danych