Udostępnij za pośrednictwem


Sterownik microsoft ADO.NET dla inżynierii danych usługi Microsoft Fabric (wersja zapoznawcza)

Ważna

Ta funkcja jest dostępna w wersji zapoznawczej.

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 inżynierii danych sieci szkieletowej umożliwia łączenie obciążeń platformy Spark, wykonywanie zapytań i zarządzanie nimi w usłudze Microsoft Fabric przy użyciu niezawodności i prostoty standardowych wzorców ADO.NET. Oparty na interfejsach API Livy Microsoft Fabric sterownik zapewnia bezpieczną i elastyczną łączność Spark SQL z aplikacjami platformy .NET przy użyciu znanych DbConnection, DbCommand i DbDataReader abstrakcji.

Kluczowe funkcje

  • Zgodny z ADO.NET: pełne wdrożenie abstrakcji ADO.NET (DbConnection, DbCommand, DbDataReader, DbParameter, DbProviderFactory)
  • 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
  • Asynchroniczne ładowanie wstępne: Ładowanie danych w tle w celu zwiększenia wydajności przy większych zestawach wyników
  • Automatyczne ponowne nawiązywanie połączenia: automatyczne odzyskiwanie sesji po błędach połączenia

Uwaga / Notatka

W przypadku platformy Apache Spark typu open source baza danych i schemat są używane synonimowo. Na przykład uruchomienie SHOW SCHEMAS lub SHOW DATABASES w notesie Fabric zwraca ten sam wynik — listę wszystkich schematów w Lakehouse.

Wymagania wstępne

Przed użyciem sterownika Microsoft ADO.NET dla inżynierii danych Microsoft Fabric upewnij się, że masz następujące elementy:

  • Środowisko uruchomieniowe platformy .NET: .NET 8.0 lub nowszy
  • Microsoft Fabric Access: dostęp do obszaru roboczego usługi Microsoft 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

Sterownik microsoft ADO.NET dla usługi Microsoft Fabric Data Engineering w wersji 1.0.0 jest w publicznej wersji zapoznawczej, którą można pobrać z tych linków centrum pobierania.

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="1.0.0" />
</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/v1;" +
    "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

Parametr Opis Przykład
Server Punkt końcowy interfejsu API usługi Microsoft Fabric https://api.fabric.microsoft.com/v1
SparkServerType Identyfikator typu serwera Fabric
FabricWorkspaceID Identyfikator obszaru roboczego usługi Microsoft Fabric (GUID) <workspace-id>
FabricLakehouseID Identyfikator usługi Microsoft Fabric lakehouse (GUID) <lakehouse-id>
AuthFlow Metoda uwierzytelniania AzureCli, , BrowserBased, ClientSecretCredential, ClientCertificateCredential, , AuthAccessTokenFileToken

Parametry opcjonalne

Ustawienia połączenia

Parametr Typ Wartość domyślna Opis
LivySessionTimeoutSeconds Integer 60 Czas w sekundach oczekiwania na utworzenie sesji
LivyStatementTimeoutSeconds Integer 600 Czas w sekundach oczekiwania na wykonanie instrukcji
SessionName Sznurek (automatycznie) Nazwa niestandardowa sesji platformy Spark
AutoReconnect logiczny false Włączanie automatycznego odzyskiwania sesji

Ustawienia puli połączeń

Parametr Typ Wartość domyślna Opis
ConnectionPoolEnabled logiczny true Włącz buforowanie połączeń
MinPoolSize Integer 1 Minimalna liczba połączeń w puli
MaxPoolSize Integer 20 Maksymalna liczba połączeń w puli
ConnectionMaxIdleTimeMs Integer 1800000 Maksymalny czas bezczynności przed odzyskaniem połączenia (30 minut)
MaxLifetimeMs Integer 3600000 Maksymalny okres istnienia połączenia w puli (60 minut)
ValidateConnections logiczny true Weryfikowanie połączeń przed użyciem
ValidationTimeoutMs Integer 5000 Limit czasu weryfikacji połączenia

Ustawienia rejestrowania

Parametr Typ Wartość domyślna Opis
LogLevel Sznurek Information Poziom dziennika: Trace, Debug, Information, Warning, Error
LogFilePath Sznurek (brak) Ścieżka do rejestrowania opartego na plikach

Uwaga / Notatka

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/v1;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli

Z opcjami buforowania połączeń

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

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

Server=https://api.fabric.microsoft.com/v1;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

Wartość AuthFlow Opis Najlepsze dla
AzureCli Używa buforowanych poświadczeń Azure CLI Programowanie i testowanie
BrowserBased Interakcyjne uwierzytelnianie oparte na przeglądarce Aplikacje dostępne dla użytkowników
ClientSecretCredential Podmiot usługi z kluczem tajnym klienta Zautomatyzowane usługi, zadania w tle
ClientCertificateCredential Jednostka usługi z certyfikatem Aplikacje dla przedsiębiorstw
AuthAccessToken Wstępnie uzyskany token dostępu nosiciela Scenariusze uwierzytelniania niestandardowego

Uwierzytelnianie CLI platformy Azure

Najlepsze dla: Programowanie i testowanie

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

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

Uwaga / Notatka

Zdecydowanie zalecamy unikanie twardych poświadczeń kodowania, takich jak hasła, klucze, wpisy tajne, tokeny lub certyfikaty w kodzie. Zamiast tego użyj usługi Azure Key Vault, aby bezpiecznie przechowywać te wartości i pobierać je w czasie wykonywania.

Przykłady użycia

Podstawowe połączenie i zapytanie

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com/v1;" +
    "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($"Inserted {rowsAffected} row(s)");

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

rowsAffected = await updateCommand.ExecuteNonQueryAsync();
Console.WriteLine($"Updated {rowsAffected} row(s)");

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

rowsAffected = await deleteCommand.ExecuteNonQueryAsync();
Console.WriteLine($"Deleted {rowsAffected} row(s)");

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())
{
    Console.WriteLine($"  {tablesReader.GetString(0)}");
}

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

Korzystanie z LivyConnectionStringBuilder

using Microsoft.Spark.Livy.AdoNet;

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

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

Mapowanie typu danych

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

Typ Spark SQL typ .NET DbType
BOOLEAN bool logiczny
TINYINT sbyte SByte
SMALLINT short Int16
INT int Int32
BIGINT long Int64
FLOAT float Single
PODWÓJNY double Double
DZIESIĘTNE (p, s) decimal Decimal
STRING string Sznurek
VARCHAR(n) string Sznurek
CHAR(n) string Sznurek
BINARY byte[] Binary
DATE DateTime Termin
TIMESTAMP DateTime Data i czas
TABLICA<T> T[] lub string (JSON) Obiekt
MAP<K,V> Dictionary<K,V> lub string (JSON) Obiekt
STRUCT object lub string (JSON) Obiekt

Praca z typami złożonymi

Typy złożone (ARRAY, MAP, STRUCT) są domyślnie zwracane jako ciągi JSON:

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

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

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    // Complex types returned as JSON strings
    string arrayJson = reader.GetString(0);  // e.g., "[1, 2, 3]"
    string mapJson = reader.GetString(1);    // e.g., "{\"key\": \"value\"}"
    string structJson = reader.GetString(2); // e.g., "{\"field1\": 1, \"field2\": \"text\"}"

    // Parse with System.Text.Json
    var array = JsonSerializer.Deserialize<int[]>(arrayJson);
    var map = JsonSerializer.Deserialize<Dictionary<string, string>>(mapJson);
}

Troubleshooting

Ta sekcja zawiera wskazówki dotyczące rozwiązywania typowych problemów, które mogą wystąpić podczas korzystania ze sterownika microsoft ADO.NET dla inżynierii danych usługi Microsoft Fabric.

Typowe problemy

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

Awarie połączenia

Problem: Nie można nawiązać połączenia z usługą Microsoft 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 instrukcji: LivyStatementTimeoutSeconds=300
  • Użyj klauzuli LIMIT do ograniczenia rozmiaru wyniku podczas rozwoju.
  • Upewnij się, że klaster Spark ma odpowiednie zasoby

Upłynięcie limitu czasu tworzenia sesji

Problem: Przekroczono limit czasu połączenia podczas tworzenia sesji

Rozwiązania:

  • Zwiększ limit czasu sesji: LivySessionTimeoutSeconds=120
  • 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 włączenie szczegółowego rejestrowania może pomóc zidentyfikować główną przyczynę problemów. Rejestrowanie można włączyć za pomocą parametrów połączenia lub programowo.

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

LogLevel=Debug

Możesz też skonfigurować programowo:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

// Logging is automatically integrated with the connection

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