Microsoft Fabric Veri Mühendisliği için Microsoft ADO.NET sürücüsü (önizleme)

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

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:

  1. FabricWorkspaceID ve FabricLakehouseID doğru GUID'ler olduğunu doğrulayın.
  2. Azure CLI kimlik doğrulamayı denetleyin: az account show
  3. Uygun Fabric çalışma alanı izinlerine sahip olduğunuzdan emin olun
  4. 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