Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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.
- Pobierz sterownik Microsoft ADO.NET dla Microsoft Fabric Data Engineering (zip)
- Pobierz sterownik Microsoft ADO.NET dla Microsoft 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="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:
- Sprawdź, czy
FabricWorkspaceIDiFabricLakehouseIDsą prawidłowymi identyfikatorami GUID - Sprawdź uwierzytelnianie Azure CLI:
az account show - Upewnij się, że masz odpowiednie uprawnienia obszaru roboczego usługi Fabric
- 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 loginaby 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
LIMITdo 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