Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Önemli
Bu özellik önizleme aşamasındadır.
ADO.NET, .NET ekosisteminde uygulamaların veritabanlarından ve büyük veri platformlarından verilere bağlanmasını ve verilerle çalışmasını sağlayan yaygın olarak benimsenen bir veri erişim teknolojisidir.
Microsoft ADO.NET Driver for Fabric Data Engineering, standart ADO.NET kalıplarının güvenilirliği ve sadeliğiyle Fabric'te Spark iş yüklerini bağlamanıza, sorgulamanıza ve yönetmenize olanak tanır. Fabric'in Livy API'leri üzerine inşa edilen sürücü, tanıdık DbConnection, DbCommand, ve DbDataReader soyutlamalar kullanarak .NET uygulamalarınıza güvenli ve esnek Spark SQL bağlantısı sağlar.
Temel özellikler
-
ADO.NET Uyumlu: ADO.NET soyutlamalarının tam uygulaması (
DbConnection,DbCommand,DbDataReader,DbParameter,DbProviderFactory) - Microsoft Entra Id Kimlik Doğrulaması: Azure CLI, etkileşimli tarayıcı, istemci kimlik bilgileri, sertifika tabanlı ve erişim belirteci kimlik doğrulaması gibi birden çok kimlik doğrulama akışı
- Spark SQL Yerel Sorgu Desteği: Parametreli sorgularla Spark SQL deyimlerinin doğrudan yürütülmesi
- Kapsamlı Veri Türü Desteği: Karmaşık türler (ARRAY, MAP, STRUCT) dahil olmak üzere tüm Spark SQL veri türleri için destek
- Bağlantı Havuzu: Gelişmiş performans için yerleşik bağlantı havuzu yönetimi
- Oturumu Yeniden Kullanma: Başlangıç gecikme süresini azaltmak için verimli Spark oturum yönetimi
- Async Prefetch: Büyük sonuç kümeleriyle gelişmiş performans için arka plan verilerini yükleme
- Otomatik Yeniden Bağlanma: Bağlantı hatalarından sonra otomatik oturum kurtarma
Uyarı
Açık kaynak Apache Spark'ta veritabanı ve şema eş anlamlı olarak kullanılır. Örneğin, çalıştırmak SHOW SCHEMAS veya SHOW DATABASES bir Fabric defterinde aynı sonucu döndürür — göl evindeki tüm şemaların listesi.
Önkoşullar
Microsoft ADO.NET Driver for Fabric Data Engineering'i kullanmadan önce, aşağıdaki özelliklere sahip olduğunuzdan emin olun:
- .NET Çalışma Zamanı: .NET 8.0 veya üzeri
- Fabric Erişimi: Veri Mühendisliği yeteneklerine sahip bir Fabric çalışma alanına erişim
- Azure Entra Id Kimlik Bilgileri: Kimlik doğrulaması için uygun kimlik bilgileri
- Çalışma Alanı ve Lakehouse Kimlikleri: Fabric çalışma alanınız ve lakehouse'unuz için GUID tanımlayıcıları
- Azure CLI (isteğe bağlı): Azure CLI kimlik doğrulama yöntemi için gereklidir
İndirme, ekleme, başvuru ve doğrulama
NuGet paketini indirme
Microsoft ADO.NET Driver for Fabric Data Engineering sürüm 1.0.0, bu indirme merkezi bağlantılarından indirebileceğiniz halka açık önizleme aşamasında.
- Download Microsoft ADO.NET Driver for Fabric Data Engineering (zip)
- Microsoft ADO.NET Driver for Fabric Data Engineering (tar) indir
Projenizde NuGet paketine başvurma
İndirilen NuGet paketini projenize ekleyin ve pakete ilişkin bir başvuruyu proje dosyanıza ekleyin:
<ItemGroup>
<PackageReference Include="Microsoft.Spark.Livy.AdoNet" Version="1.0.0" />
</ItemGroup>
Yüklemeyi doğrulama
Ekleme ve başvurudan sonra paketin projenizde kullanılabilir olduğunu doğrulayın:
using Microsoft.Spark.Livy.AdoNet;
// Verify the provider is registered
var factory = LivyProviderFactory.Instance;
Console.WriteLine($"Provider: {factory.GetType().Name}");
Hızlı başlangıç örneği
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));
}
Bağlantı dizesi biçimi
Temel biçim
Microsoft ADO.NET Sürücüsü standart ADO.NET bağlantı dizesi biçimini kullanır:
Parameter1=Value1;Parameter2=Value2;...
Gerekli parametreler
| Parametre | Açıklama | Example |
|---|---|---|
Server |
Fabric API uç noktası | https://api.fabric.microsoft.com/v1 |
SparkServerType |
Sunucu türü tanımlayıcısı | Fabric |
FabricWorkspaceID |
Fabric workspace identifier (GUID) | <workspace-id> |
FabricLakehouseID |
Fabric göl evi tanımlayıcısı (GUID) | <lakehouse-id> |
AuthFlow |
Kimlik doğrulama yöntemi |
AzureCli, BrowserBased, ClientSecretCredential, , ClientCertificateCredential, AuthAccessToken, FileToken |
İsteğe bağlı parametreler
Bağlantı ayarları
| Parametre | Türü | Varsayılan | Açıklama |
|---|---|---|---|
LivySessionTimeoutSeconds |
Tamsayı | 60 |
Oturum oluşturmayı bekleme süresi saniye cinsinden |
LivyStatementTimeoutSeconds |
Tamsayı | 600 |
Deyimin yürütülmesini bekleme süresi saniye cinsinden |
SessionName |
Dize | (otomatik) | Spark oturumu için özel ad |
AutoReconnect |
Boolean | false |
Otomatik oturum kurtarmayı etkinleştirme |
Bağlantı havuzu ayarları
| Parametre | Türü | Varsayılan | Açıklama |
|---|---|---|---|
ConnectionPoolEnabled |
Boolean | true |
Bağlantı havuzunu etkinleştirme |
MinPoolSize |
Tamsayı | 1 |
Havuzdaki minimum bağlantı sayısı |
MaxPoolSize |
Tamsayı | 20 |
Havuzdaki en fazla bağlantı sayısı |
ConnectionMaxIdleTimeMs |
Tamsayı | 1800000 |
Bağlantı geri dönüştürülmeden önce en fazla boşta kalma süresi (30 dk) |
MaxLifetimeMs |
Tamsayı | 3600000 |
Havuza alınan bağlantının maksimum ömrü (60 dakika) |
ValidateConnections |
Boolean | true |
Kullanmadan önce bağlantıları doğrulama |
ValidationTimeoutMs |
Tamsayı | 5000 |
Bağlantı doğrulaması için zaman aşımı |
Kayıt ayarları
| Parametre | Türü | Varsayılan | Açıklama |
|---|---|---|---|
LogLevel |
Dize | Information |
Günlük düzeyi: Trace, Debug, Information, Warning, Error |
LogFilePath |
Dize | (yok) | Dosya tabanlı günlük kaydı yolu |
Uyarı
Sürücüler arası takma adlar: Sürücü, yerel ADO.NET adlarına ek olarak JDBC ve ODBC özellik adlarını kabul eder (örneğin, WorkspaceIdFabricWorkspaceID haritası, LakehouseIdFabricLakehouseID haritası). Tüm özellik adları büyük/küçük harfe duyarlı değildir.
Örnek bağlantı dizeleri
Temel bağlantı (Azure CLI kimlik doğrulaması)
Server=https://api.fabric.microsoft.com/v1;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli
Bağlantı havuzu seçenekleriyle
Server=https://api.fabric.microsoft.com/v1;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;ConnectionPoolEnabled=true;MinPoolSize=2;MaxPoolSize=10
Otomatik yeniden bağlanma ve günlüğe kaydetme ile
Server=https://api.fabric.microsoft.com/v1;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;AutoReconnect=true;LogLevel=Debug
Kimlik Doğrulaması
Microsoft ADO.NET Sürücüsü, Microsoft Entra ID (eski adıYla Azure Active Directory) aracılığıyla birden çok kimlik doğrulama yöntemini destekler. Kimlik doğrulaması, bağlantı dizesindeki AuthFlow parametresi kullanılarak yapılandırılır.
Kimlik doğrulama yöntemleri
| AuthFlow Değeri | Açıklama | En Uygun |
|---|---|---|
AzureCli |
Azure CLI önbelleğe alınmış kimlik bilgilerini kullanır | Geliştirme ve test |
BrowserBased |
Etkileşimli tarayıcı tabanlı kimlik doğrulaması | Kullanıcıya yönelik uygulamalar |
ClientSecretCredential |
İstemci sırrı ile hizmet asıl | Otomatik hizmetler, arka plan işleri |
ClientCertificateCredential |
Sertifika ile hizmet sorumlusu | Kurumsal uygulamalar |
AuthAccessToken |
Önceden alınan taşıyıcı erişim belirteci | Özel kimlik doğrulama senaryoları |
Azure CLI kimlik doğrulaması
En iyi kullanımı: Geliştirme ve test için
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:
- Azure CLI yüklü:
az --version - Oturum açıldı:
az login
Etkileşimli tarayıcı kimlik doğrulaması
En iyi kullanım: Kullanıcıya yönelik uygulamalar
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
Davranış:
- Kullanıcı kimlik doğrulaması için bir tarayıcı penceresi açar
- Kimlik bilgileri sonraki bağlantılar için önbelleğe alınır
İstemci kimlik bilgileri (hizmet sorumlusu) kimlik doğrulaması
En iyi: Otomatik hizmetler ve arka plan işleri
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();
Gerekli parametreler:
-
AuthTenantID: Azure kiracı kimliği -
AuthClientID: Microsoft Entra Id'den uygulama (istemci) kimliği -
AuthClientSecret: Microsoft Entra ID'den istemci sırrı
Sertifika tabanlı kimlik doğrulaması
En iyisi: Sertifika tabanlı kimlik doğrulaması gerektiren kurumsal uygulamalar
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();
Gerekli parametreler:
-
AuthTenantID: Azure kiracı kimliği -
AuthClientID: Uygulama (istemci) kimliği -
AuthCertificatePath: PFX/PKCS12 sertifika dosyasının yolu -
AuthCertificatePassword: Sertifika parolası
Erişim belirteci kimlik doğrulaması
En iyisi: Özel kimlik doğrulama senaryoları
// 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();
Uyarı
Kodunuzda parolalar, anahtarlar, gizli diziler, belirteçler veya sertifikalar gibi kimlik bilgilerini sabit kodlamaktan kaçınmanızı kesinlikle öneririz. Bunun yerine, bu değerleri güvenli bir şekilde depolamak ve çalışma zamanında almak için Azure Key Vault kullanın.
Kullanım örnekleri
Temel bağlantı ve sorgu
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();
}
Parametreli sorgular
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 yöntemi, tek değerler için kullanılır.
using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM customers";
var count = await command.ExecuteScalarAsync();
Console.WriteLine($"Total customers: {count}");
DML işlemleri için ExecuteNonQuery
// 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)");
Büyük sonuç kümeleriyle çalışma
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}");
Şema keşfi
// 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"]}");
}
LivyConnectionStringBuilder'ı kullanma
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();
DbProviderFactory'yi Kullanarak
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...
Veri türü eşlemesi
Sürücü Spark SQL veri türlerini .NET türleriyle eşler:
| Spark SQL Türü | .NET Türü | DbType |
|---|---|---|
| BOOLEAN | bool |
Boolean |
| TINYINT | sbyte |
SByte |
| SMALLINT (Küçük Tamsayı) | short |
Int16 |
| INT | int |
Int32 |
| BIGINT | long |
Int64 |
| FLOAT | float |
Single |
| ÇİFT | double |
Double |
| ONDALıK(p,s) | decimal |
Ondalık |
| STRING | string |
Dize |
| VARCHAR(n) | string |
Dize |
| CHAR(n) | string |
Dize |
| BINARY | byte[] |
İkilik |
| DATE | DateTime |
Tarih |
| TIMESTAMP | DateTime |
Tarih Saat |
| DIZI<T> |
T[] veya string (JSON) |
Nesne |
| MAP<K,V> |
Dictionary<K,V> veya string (JSON) |
Nesne |
| Yapı |
object veya string (JSON) |
Nesne |
Karmaşık türlerle çalışma
Karmaşık türler (ARRAY, MAP, STRUCT) varsayılan olarak JSON dizeleri olarak döndürülür:
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);
}
Sorun giderme
Bu bölüm, Microsoft ADO.NET Driver for Fabric Data Engineering'i kullanırken karşılaşabileceğiniz yaygın sorunları çözmek için rehberlik sağlar.
Yaygın sorunlar
Aşağıdaki bölümlerde yaygın sorunlar ve çözümleri açıklanmaktadır:
Bağlantı hataları
Sorun: Fabric'e bağlanamıyor
Çözümler:
-
FabricWorkspaceIDveFabricLakehouseIDdoğru GUID'ler olduğunu doğrulayın. - Azure CLI kimlik doğrulamayı denetleyin:
az account show - Uygun Fabric çalışma alanı izinlerine sahip olduğunuzdan emin olun
- Ağ bağlantısını doğrula
api.fabric.microsoft.com
Kimlik doğrulama hataları
Sorun: Azure CLI ile kimlik doğrulaması başarısız oluyor
Çözümler:
- Kimlik bilgilerini yenilemek için komutunu çalıştırın
az login - Doğru kiracıyı doğrulayın:
az account set --subscription <subscription-id> - Belirteç geçerliliğini denetleyin:
az account get-access-token --resource https://api.fabric.microsoft.com
Sorgu zaman aşımları
Sorun: Büyük tablolarda sorguların zaman aşımına uğraması
Çözümler:
- Komut zaman aşımını artırma:
LivyStatementTimeoutSeconds=300 - Geliştirme sırasında sonuç boyutunu kısıtlamak için yan tümcesi kullanın
LIMIT - Spark kümesinin yeterli kaynağa sahip olduğundan emin olun
Oturum oluşturma zaman aşımı
Sorun: Oturum oluşturma sırasında bağlantı zaman aşımına uğradı
Çözümler:
- Oturum zaman aşımını artırın:
LivySessionTimeoutSeconds=120 - Ağ Yapısı kapasitesi uygunluğunu kontrol et
- Çalışma alanının oturum sınırlarına ulaşmadığını doğrulama
Log kaydını etkinleştir
Sorunları giderirken, ayrıntılı günlüğe kaydetmeyi etkinleştirmek sorunların kök nedenini belirlemenize yardımcı olabilir. Bağlantı dizesi aracılığıyla veya programatik olarak günlüğü etkinleştirebilirsiniz.
Bağlantı dizesi aracılığıyla ayrıntılı günlüğe kaydı etkinleştirmek için:
LogLevel=Debug
Veya program aracılığıyla yapılandırın:
using Microsoft.Extensions.Logging;
var loggerFactory = LoggerFactory.Create(builder =>
{
builder.AddConsole();
builder.SetMinimumLevel(LogLevel.Debug);
});
// Logging is automatically integrated with the connection
Log seviyeleri:
-
Trace: En ayrıntılı, tüm API çağrılarını içerir -
Debug: Ayrıntılı hata ayıklama bilgileri -
Information: Genel bilgiler (varsayılan) -
Warning: Yalnızca uyarılar -
Error: Sadece hatalar