ไดรเวอร์ Microsoft ADO.NET สําหรับ Microsoft Fabric Data Engineering

ADO.NET เป็นเทคโนโลยีการเข้าถึงข้อมูลที่นํามาใช้อย่างแพร่หลายในระบบนิเวศ .NET ที่ช่วยให้แอปพลิเคชันสามารถเชื่อมต่อและทํางานกับข้อมูลจากฐานข้อมูลและแพลตฟอร์มข้อมูลขนาดใหญ่ได้

ไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering ช่วยให้คุณเชื่อมต่อ สืบค้น และจัดการงาน Spark ใน Fabric ด้วยความน่าเชื่อถือและความเรียบง่ายของรูปแบบมาตรฐาน ADO.NET ไดรเวอร์นี้สร้างขึ้นบน Fabric Livy APIs เพื่อให้การเชื่อมต่อ Spark SQL ที่ปลอดภัยและยืดหยุ่นกับแอปพลิเคชัน .NET ของคุณโดยใช้ , DbConnection, และDbCommandนามธรรมที่คุ้นเคยDbDataReader

คุณลักษณะสำคัญ

• ADO.NET APIs: นามธรรมที่คุ้นเคย DbConnection, DbCommand, DbDataReader, , DbParameter, และDbProviderFactoryนามธรรมสําหรับการเชื่อมต่อ Spark SQL
• การรับรองความถูกต้องของ Microsoft Entra ID: โฟลว์การรับรองความถูกต้องหลายรายการ รวมถึง Azure CLI, เบราว์เซอร์แบบโต้ตอบ, ข้อมูลประจําตัวไคลเอ็นต์, ตามใบรับรอง และการรับรองความถูกต้องของโทเค็นการเข้าถึง
• รองรับการสืบค้นแบบเนทีฟของ Spark SQL: การดําเนินการโดยตรงของคําสั่ง Spark SQL ด้วยแบบสอบถามที่มีพารามิเตอร์
• รองรับประเภทข้อมูลที่ครอบคลุม: รองรับประเภทข้อมูล Spark SQL ทั้งหมดรวมถึงประเภทที่ซับซ้อน (ARRAY, MAP, STRUCT)
• Connection Pooling: การจัดการพูลการเชื่อมต่อในตัวเพื่อประสิทธิภาพที่ดีขึ้น
• การนําเซสชันกลับมาใช้ใหม่: การจัดการเซสชัน Spark ที่มีประสิทธิภาพเพื่อลดเวลาแฝงในการเริ่มต้น
• เซสชันที่มีความพร้อมกันสูง: เลือกใช้ความจุ Fabric Livy ร่วมกับ REPL แยกต่างหากสําหรับเซสชัน HC ที่เช่าพร้อมกัน
• Async Prefetch: การโหลดข้อมูลพื้นหลังเพื่อประสิทธิภาพที่ดีขึ้นด้วยชุดผลลัพธ์ขนาดใหญ่
• เชื่อมต่อใหม่อัตโนมัติ: การกู้คืนเซสชันแบบคลาสสิกหลังจากการเชื่อมต่อล้มเหลว;ความล้มเหลวของ HC จะถูกแสดงให้เห็นสําหรับการลองใหม่ที่ควบคุมโดยแอปพลิเคชัน

ข้อกำหนดเบื้องต้น

ก่อนใช้ไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering โปรดตรวจสอบให้แน่ใจว่าคุณมี:

• รันไทม์ .NET: .NET 8.0 หรือใหม่กว่า
• Fabric Access: การเข้าถึงพื้นที่ทํางาน Fabric ด้วยความสามารถด้านวิศวกรรมข้อมูล
• ข้อมูลประจําตัว Azure Entra ID: ข้อมูลประจําตัวที่เหมาะสมสําหรับการรับรองความถูกต้อง
• รหัสพื้นที่ทํางานและเลคเฮาส์: ตัวระบุ GUID สําหรับพื้นที่ทํางาน Fabric และเลคเฮาส์ของคุณ
• Azure CLI (ไม่บังคับ): จําเป็นสําหรับวิธีการรับรองความถูกต้องของ Azure CLI

ดาวน์โหลด รวม อ้างอิง และตรวจสอบ

ดาวน์โหลดแพ็คเกจ NuGet

• ดาวน์โหลดไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering (zip)
• ดาวน์โหลดไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering (tar)

อ้างอิงแพ็คเกจ NuGet ในโครงการของคุณ

รวมแพ็คเกจ NuGet ที่ดาวน์โหลดมาในโครงการของคุณและเพิ่มการอ้างอิงของแพ็คเกจไปยังไฟล์โครงการของคุณ:

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

ตรวจสอบการติดตั้ง

หลังจากรวมและอ้างอิงแล้ว ให้ตรวจสอบว่าแพ็คเกจพร้อมใช้งานในโครงการของคุณ:

using Microsoft.Spark.Livy.AdoNet;

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

ตัวอย่างการเริ่มต้นอย่างรวดเร็ว

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

รูปแบบสตริงการเชื่อมต่อ

รูปแบบพื้นฐาน

โปรแกรมควบคุม Microsoft ADO.NET ใช้รูปแบบสตริงการเชื่อมต่อ ADO.NET มาตรฐาน:

Parameter1=Value1;Parameter2=Value2;...

พารามิเตอร์ที่ต้องการ

พารามิเตอร์เพิ่มเติม

การตั้งค่าการเชื่อมต่อ

การตั้งค่าพูลการเชื่อมต่อ

การตั้งค่าการทํางานพร้อมกันสูง

การตั้งค่าการบันทึก

นามแฝงข้ามไดรเวอร์: โปรแกรมควบคุมยอมรับชื่อคุณสมบัติ JDBC และ ODBC นอกเหนือจากชื่อ ADO.NET ดั้งเดิม (เช่น WorkspaceId แมปไปยัง แมปไปยัง FabricWorkspaceIDแม LakehouseId ปไปยัง FabricLakehouseID) ชื่อพร็อพเพอร์ตี้ทั้งหมดไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

ตัวอย่างสตริงการเชื่อมต่อ

การเชื่อมต่อพื้นฐาน (การรับรองความถูกต้อง Azure CLI)

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

การเชื่อมต่อการทํางานพร้อมกันสูง

การเชื่อมต่อ Microsoft Fabric สามารถใช้งานพร้อมกันได้สูง. ตั้งค่า HcEnabled=true; API การเชื่อมต่อและคําสั่งมาตรฐานของ ADO.NET ยังคงไม่เปลี่ยนแปลง ใช้โฮสต์ Fabric API ที่ไม่มีเวอร์ชันสําหรับ Server; ไดรเวอร์จะใช้ FabricVersion=v1 และ LivyApiVersion=2023-12-01 โดยค่าเริ่มต้นเมื่อสร้าง HC endpoint

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

สําหรับคําแนะนําการตั้งค่าอย่างละเอียด โปรดดูที่ส่วนโหมดHigh-Concurrency (HC)

ด้วยตัวเลือกการรวมการเชื่อมต่อ

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

ด้วยการเชื่อมต่อใหม่และการบันทึกอัตโนมัติ

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

การพิสูจน์ตัวตน

โปรแกรมควบคุม Microsoft ADO.NET สนับสนุนวิธีการรับรองความถูกต้องหลายวิธีผ่าน Microsoft Entra ID (เดิมคือ Azure Active Directory) การรับรองความถูกต้องถูกกําหนดค่าโดยใช้ AuthFlow พารามิเตอร์ในสตริงการเชื่อมต่อ

วิธีการรับรองความถูกต้อง

การรับรองความถูกต้องของ Azure CLI

ดีที่สุดสําหรับ: การพัฒนาและการทดสอบ

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

ข้อกําหนดเบื้องต้น:

• ติดตั้ง Azure CLI: az --version
• เข้าสู่ระบบ: az login

การรับรองความถูกต้องของเบราว์เซอร์แบบโต้ตอบ

ดีที่สุดสําหรับ: แอปพลิเคชันที่ต้องเผชิญหน้ากับผู้ใช้

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

ลักษณะการทํางาน:

• เปิดหน้าต่างเบราว์เซอร์สําหรับการตรวจสอบผู้ใช้
• ข้อมูลประจําตัวจะถูกแคชสําหรับการเชื่อมต่อที่ตามมา

การรับรองความถูกต้องของข้อมูลประจําตัวไคลเอ็นต์ (บริการหลัก)

ดีที่สุดสําหรับ: บริการอัตโนมัติและงานเบื้องหลัง

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

พารามิเตอร์ที่จําเป็น:

• AuthTenantID: รหัสผู้เช่า Azure
• AuthClientID: รหัสแอปพลิเคชัน (ไคลเอ็นต์) จาก Microsoft Entra ID
• AuthClientSecret: ข้อมูลลับของไคลเอ็นต์จาก Microsoft Entra ID

การรับรองความถูกต้องตามใบรับรอง

ดีที่สุดสําหรับ: แอปพลิเคชันระดับองค์กรที่ต้องการการรับรองความถูกต้องตามใบรับรอง

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

พารามิเตอร์ที่จําเป็น:

• AuthTenantID: รหัสผู้เช่า Azure
• AuthClientID: รหัสแอปพลิเคชัน (ไคลเอ็นต์)
• AuthCertificatePath: เส้นทางไปยังไฟล์ใบรับรอง PFX/PKCS12
• AuthCertificatePassword: รหัสผ่านใบรับรอง

การรับรองความถูกต้องของโทเค็นการเข้าถึง

ดีที่สุดสําหรับ: สถานการณ์การรับรองความถูกต้องแบบกําหนดเอง

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

ตัวอย่างการใช้

การเชื่อมต่อและแบบสอบถามพื้นฐาน

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

คิวรีแบบกําหนดพารามิเตอร์

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 สําหรับค่าเดียว

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

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

ExecuteNonQuery สําหรับการดําเนินการ 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.");

การทํางานกับชุดผลลัพธ์ขนาดใหญ่

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

การค้นพบสคีมา

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

การใช้ 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();

การใช้ 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...

โหมดการทํางานพร้อมกันสูง (HC)

โหมด High-concurrency (HC) ช่วยให้แอปพลิเคชัน .NET สามารถรันงาน Spark SQL พร้อมกันได้โดยไม่ต้องจัดเตรียมเซสชัน Spark แบบคลาสสิกแยกสําหรับแต่ละการเชื่อมต่อ ADO.NET Fabric สามารถวางการเชื่อมต่อที่เข้ากันได้ในเซสชัน Livy ที่จัดการโดยเซิร์ฟเวอร์เดียวกัน พร้อมทั้งให้แต่ละการเชื่อมต่อมี Read-Eval-Print Loop (REPL) แยกสําหรับการดําเนินการคําสั่ง

โมเดลนี้ช่วยลดเวลาการเริ่มต้นเชื่อมต่อ หลีกเลี่ยงการจัดสรรเซสชัน Spark ซ้ํา ๆ และใช้ความจุของ Fabric Spark ได้อย่างมีประสิทธิภาพมากขึ้น แอปพลิเคชันของคุณยังคงใช้ API มาตรฐาน ADO.NET รวมถึง DbConnection, DbCommand, DbDataReader, OpenAsync, และClose

โหมด HC คือโหมดเลือกเข้าร่วม ถ้าคุณไม่เปิดใช้งาน ไดรเวอร์จะใช้เส้นทางเซสชัน Livy แบบคลาสสิก

เลือกได้ระหว่างโหมด HC และโหมดคลาสสิก

ใช้โหมด HC เมื่อ:

• บริการ ASP.NET จัดการคําขอที่เปิดการเชื่อมต่อและรัน Spark SQL พร้อมกัน
• บริการเวิร์กเกอร์ งานที่ตั้งเวลาไว้ หรือสายข้อมูลแบบขนานจะสร้างการเชื่อมต่อ ADO.NET เป็นชุด ๆ
• การเชื่อมต่อหลายจุดจะมุ่งเป้าไปที่พื้นที่ทํางาน Fabric และบ้านพักริมทะเลสาบเดียวกัน และใช้การตั้งค่า Spark ที่เข้ากันได้
• การลดเวลาการเริ่มต้นเชื่อมต่อและการจัดเตรียมเซสชัน Spark ซ้ํา ๆ เป็นสิ่งสําคัญ
• งานของคุณสามารถใช้ความจุ Spark ที่แชร์และจัดการโดยเซิร์ฟเวอร์ ในขณะที่แยกการดําเนินการคําสั่งไว้ด้วย REPL

ใช้โหมดคลาสสิกเมื่อ:

• แอปพลิเคชันของคุณใช้การเชื่อมต่อที่มีอายุการใช้งานยาวนานเพียงหนึ่งหรือไม่กี่การเชื่อมต่อเท่านั้น
• แต่ละการเชื่อมต่อต้องการเซสชัน Spark เฉพาะสําหรับภาระงานที่เข้มงวดหรือการแยกทรัพยากร
• การเชื่อมต่อต้องการการตั้งค่า Spark ที่แตกต่างกันอย่างมากซึ่งไม่ควรใช้เซสชันพื้นฐานร่วมกัน
• จุดสิ้นสุด Fabric Livy สําหรับพื้นที่ทํางานเป้าหมายและ lakehouse ไม่รองรับโหมด HC

วิธีการทํางานของการเชื่อมต่อ HC

เมื่อแอปพลิเคชันของคุณเรียกใช้ Open หรือ OpenAsync ไม่มีการเชื่อมต่อแบบพูลที่เข้ากันได้ ไดรเวอร์:

1. ขอเซสชัน HC จาก Fabric
2. รอให้เซสชันพร้อม จนถึงเวลาหมดอายุการเก็บข้อมูลที่กําหนดไว้
3. เชื่อมต่อการเชื่อมต่อ ADO.NET กับเซสชัน HC และ REPL ที่กําหนดไว้
4. ส่งคําสั่ง คําค้นหา คําขอยกเลิก และการทําความสะอาดผ่านจุดสิ้นสุดของ HC

เซสชัน HC ที่เช่าแยกพร้อมกันจะใช้ REPL แยกกัน คําสั่งบนการเชื่อมต่อหนึ่งจะแชร์เซสชัน HC และ REPL ของการเชื่อมต่อนั้น

การรวมฝั่งไคลเอนต์เปิดใช้งานโดยค่าเริ่มต้น การปิดหรือกําจัดการเชื่อมต่อที่มีสิทธิ์โดยปกติจะคืนเซสชัน HC ทางกายภาพและ REPL ไปยังพูลโปรเซส-โลคอลเพื่อใช้ซ้ํา;ไม่จําเป็นต้องปล่อยงานจากระยะไกลเสมอไป เมื่อปิดการใช้พูลข้อมูล การปิดการเชื่อมต่อทางกายภาพจะดําเนินการทําความสะอาด HC ใช้ using คําสั่งต่อไปเพื่อให้การเชื่อมต่อเชิงตรรกะกลับมาอย่างรวดเร็ว

เปิดใช้งานโหมด HC

โหมด HC คือโหมดเลือกเข้าร่วม หากคุณละเว้น hcEnabled หรือตั้งค่าเป็น false ไดรเวอร์จะใช้เส้นทางเซสชัน Livy แบบคลาสสิก

ตั้งค่าคุณสมบัติ hcEnabled เป็น true เพื่อรับเซสชัน HC:

hcEnabled=true;

กําหนดค่าการจัดเซสชัน

HcSessionTag ให้คําแนะนําฝั่งเซิร์ฟเวอร์สําหรับการบรรจุเซสชัน HC ที่เข้ากันได้ลงในเซสชัน Livy พื้นฐาน แท็กที่ตรงกันไม่ได้รับประกันว่าจะอยู่ในเซสชันเดียวกัน

หากคุณละเว้นแท็กหรือให้ค่าว่างเปล่าหรือมีเฉพาะช่องว่าง ไดรเวอร์จะไม่ส่งแท็กนั้นในคําขอ acquire การละเว้นแท็กไม่ได้ปิดโหมด HC หรือการแพ็คฝั่งบริการ ตั้งค่าแท็กเฉพาะเมื่อควรพิจารณาอินสแตนซ์แอปพลิเคชันหรือเวิร์กโหลดที่เกี่ยวข้องสําหรับความจุที่ใช้ร่วมกัน ใช้ป้ายกํากับปฏิบัติการที่เสถียรและไม่ไวต่อข้อมูล เช่น reporting-service หรือnightly-etl อย่าใส่ความลับ โทเค็นการเข้าถึง ข้อมูลส่วนบุคคล รหัสลูกค้า หรือข้อความค้นหา

การกําหนดค่า Spark ยังส่งผลต่อความเข้ากันได้ของเซสชันด้วย ใช้เพื่อ HcConfOverrides กําหนดการตั้งค่า Spark ที่อนุญาตสําหรับการสร้างเซสชัน HC:

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

สําหรับการแทนที่หลายครั้ง ให้ระบุมูลค่าทั้งหมดHcConfOverrides เครื่องหมายเซมิโคลอนที่ไม่มีเครื่องหมายคําพูดเริ่มต้นคุณสมบัติสตริงเชื่อมต่อภายนอกอีกตัวหนึ่ง;มันไม่ขยาย HcConfOverrides. ตัวแยกวิเคราะห์รับค่าที่มีเครื่องหมายอัญประกาศเดี่ยวหรือสองเครื่องหมาย รักษาเครื่องหมายเซมิโคลอนและเครื่องหมายเท่ากับภายในค่าที่อัญประกาศ และถอดรหัสเครื่องหมายอัญประกาศคู่ (''""หรือ ) พื้นที่ว่างรอบชื่อคุณสมบัติและที่ขอบนอกของค่าที่ไม่ได้ใส่เครื่องหมายอัญประกาศจะถูกละเว้น ช่องว่างภายในค่าที่ไม่ได้ใส่เครื่องหมายคําพูดและช่องว่างทั้งหมดภายในค่าที่ใส่เครื่องหมายคําพูดจะถูกเก็บรักษาไว้ ค่าว่างจะมีผลเหนือค่าเริ่มต้นของสภาพแวดล้อม และคุณสมบัติที่ซ้ํากันตัวสุดท้ายจะเป็นผู้ชนะ

คุณยังสามารถปล่อยให้ LivyConnectionStringBuilder จัดการการเสนอราคาได้:

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;

ตัวอย่างเหล่านี้ต้องใช้ไดรเวอร์ Microsoft ADO.NET เวอร์ชัน 2.0.1 หรือใหม่กว่า เพิ่มรหัสพื้นที่ทํางานและบ้านพักริมทะเลสาบของคุณก่อนเปิดการเชื่อมต่อ การแทนที่ทั้งสองจะถูกส่งในคําขอสร้างเซสชันของ HC เป็นรายการแยกกันconf แต่ละการแทนที่ต้องใช้กุญแจที่แยกตัวพิมพ์เล็ก-ใหญ่-เล็กดังนี้:

• 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

เครื่องหมายคําพูดที่ผิดรูปจะถูกปฏิเสธโดยไม่รวมเนื้อหาสตริงการเชื่อมต่อในข้อผิดพลาดการแยกวิเคราะห์

ใช้แท็กและค่าการกําหนดค่าที่สอดคล้องกันข้ามการเชื่อมต่อที่ตั้งใจให้แบ่งปันความจุ Fabric จะกําหนดว่าคําขอสามารถใช้เซสชันที่มีอยู่แล้วหรือจําเป็นต้องมีเซสชันอื่นหรือไม่

กําหนดค่าเวลาการได้มา

ใช้การตั้งค่าต่อไปนี้เพื่อควบคุมระยะเวลาที่ไดรเวอร์รอเซสชัน HC:

สําหรับงานส่วนใหญ่ ให้เก็บค่าตั้งต้นไว้ เพิ่มเวลาการหาข้อมูลเฉพาะเมื่อการเริ่มต้นความจุใช้เวลานานเกินห้านาทีเป็นประจํา

ใช้โหมด HC กับการจัดพูลการเชื่อมต่อ

โหมด HC และ ADO.NET การเชื่อมต่อพูลจะครอบคลุมชั้นต่าง ๆ ดังนี้:

• โหมด HC จัดการความจุ Fabric Spark และเซสชัน Livy ที่ใช้ร่วมกันบนเซิร์ฟเวอร์
• ADO.NET connection pooling จะใช้ทรัพยากรการเชื่อมต่อที่จัดการโดยไดรเวอร์ในแอปพลิเคชันลูกข่ายซ้ํา

คุณสามารถเปิดใช้งานทั้งสองฟีเจอร์ได้ Connection pooling ช่วยลดการตั้งค่าการเชื่อมต่อฝั่งไคลเอนต์ซ้ํา ๆ ขณะที่โหมด HC ลดการจัดสรรเซสชัน Spark ฝั่งเซิร์ฟเวอร์ซ้ํา ปรับขนาดพูลการเชื่อมต่อให้เหมาะสมกับความพร้อมกันที่คาดหวังของแอปพลิเคชัน แทนที่จะใช้พูลขนาดใหญ่เพื่อสร้างงานขนานที่ไม่จําเป็น

ในโหมด AutoReconnect=true HC จะไม่เล่นซ้ําคําสั่งที่ล้มเหลวอย่างโปร่งใสหลังจากเกิดข้อผิดพลาดเซสชันที่หยุดนิ่ง แอปพลิเคชันจะได้รับข้อยกเว้นและต้องตัดสินใจว่าการทดลองดําเนินการใหม่นั้นปลอดภัยหรือไม่

ปิดโหมด HC

หากต้องการใช้โหมด classic สําหรับการเชื่อมต่อใหม่ ให้ลบHcEnabledออกจาก สายอักขระการเชื่อมต่อ หรือตั้งค่าเป็น false:

HcEnabled=false

การเปลี่ยนแปลงนี้จะส่งผลต่อการเชื่อมต่อใหม่และไม่ล้างเซสชัน HC ที่รวมกันที่มีอยู่ ปิดหรือกําจัดการเชื่อมต่อเชิงตรรกะตามปกติ;เซสชันทางกายภาพที่มีสิทธิ์สามารถอยู่ในกลุ่มลูกค้าจนกว่าจะเลิกใช้งาน

ข้อจํากัดของ ADO.NET

• ธุรกรรมไม่รองรับ
• คําสั่งรองรับเฉพาะโหมดคําสั่งข้อความเท่านั้น โหมดคําสั่งแบบ stored-procedure และ table-direct ไม่รองรับ
• Prepare ไม่ทําอะไรเลย
• คําสั่งต้องมีคําสั่งหนึ่งคําสั่ง;ข้อความคําสั่งหลายคําสั่งจะถูกปฏิเสธ
• ใช้การเชื่อมต่อที่แยกกันและเปิดพร้อมกันสําหรับงานที่ทํางานพร้อมกัน คําสั่งบนการเชื่อมต่อเดียวกันจะแชร์เซสชันและ REPL

การแมปชนิดข้อมูล

ไดรเวอร์แมปชนิดข้อมูล Spark SQL กับชนิด .NET:

การทํางานกับประเภทที่ซับซ้อน

เส้นทางผลลัพธ์ของ HC ไม่สามารถทําการซีเรียลค่า native nested Array, MAP หรือ STRUCT เป็น JSON ได้อย่างน่าเชื่อถือ Project ค่าที่ซับซ้อนเป็นสตริง JSON ใน Spark SQL ก่อนการ deserialize :

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

แก้ไข ปัญหา

ส่วนนี้ให้คําแนะนําในการแก้ไขปัญหาทั่วไปที่คุณอาจพบเมื่อใช้งานไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering

ปัญหาทั่วไป

ส่วนต่อไปนี้จะอธิบายปัญหาทั่วไปและวิธีแก้ไข:

การเชื่อมต่อล้มเหลว

ปัญหา: ไม่สามารถเชื่อมต่อกับ Fabric ได้

โซลูชัน:

1. ตรวจสอบ FabricWorkspaceID และเป็น FabricLakehouseID GUID ที่ถูกต้อง
2. ตรวจสอบการรับรองความถูกต้อง Azure CLI: az account show
3. ตรวจสอบให้แน่ใจว่าคุณมีสิทธิ์พื้นที่ทํางาน Fabric ที่เหมาะสม
4. ตรวจสอบการเชื่อมต่อเครือข่ายเพื่อ api.fabric.microsoft.com

ข้อผิดพลาดในการรับรองความถูกต้อง

ปัญหา: การรับรองความถูกต้องล้มเหลวด้วย Azure CLI

โซลูชัน:

• เรียกใช้ az login เพื่อรีเฟรชข้อมูลประจําตัว
• ตรวจสอบผู้เช่าที่ถูกต้อง: az account set --subscription <subscription-id>
• ตรวจสอบความถูกต้องของโทเค็น: az account get-access-token --resource https://api.fabric.microsoft.com

หมดเวลาคิวรี

ปัญหา: การสืบค้นหมดเวลาบนตารางขนาดใหญ่

โซลูชัน:

• เพิ่มระยะเวลาหมดอายุของใบแจ้งยอด: LivyStatementTimeoutSeconds=1200.
• ใช้ LIMIT ส่วนคําสั่งเพื่อจํากัดขนาดผลลัพธ์ระหว่างการพัฒนา
• ตรวจสอบให้แน่ใจว่าคลัสเตอร์ Spark มีทรัพยากรเพียงพอ

หมดเวลาการเชื่อมต่อหรือการรับข้อมูล HC

ปัญหา: การเชื่อมต่อหมดเวลาขณะรอการเชื่อมต่อแบบพูลหรือเซสชัน HC

โซลูชัน:

• สําหรับการรอในกลุ่มไคลเอนต์และการสร้างการเชื่อมต่อ HTTP ให้ตรวจสอบ HttpConnectionTimeoutInSeconds.
• สําหรับการเก็บ HC ให้เพิ่มในช่วง hcAcquireTimeoutSeconds 120 ถึง 3,600 วินาทีที่รองรับ
• ตรวจสอบความพร้อมใช้งานของความจุ Fabric
• ตรวจสอบว่าพื้นที่ทํางานยังไม่ถึงขีดจํากัดเซสชัน

เปิดใช้งานการบันทึก

เมื่อแก้ไขปัญหา การบันทึกอย่างละเอียดจะช่วยให้คุณระบุสาเหตุที่แท้จริงได้ กําหนดค่าการบันทึกผ่าน สายอักขระการเชื่อมต่อ:

วิธีเปิดใช้งานการบันทึกโดยละเอียดผ่านสตริงการเชื่อมต่อ:

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

ถ้าคุณไม่ได้ตั้งค่าLogFilePathการตั้งค่าการบันทึกแบบทั่วโลก ไดรเวอร์จะเขียนบันทึกไว้ใต้ %LOCALAPPDATA%\FabricSparkAdoNet\Logs Windows

ระดับบันทึก:

• Trace: ฟุ่มเฟือยที่สุด รวมถึงการเรียก API ทั้งหมด
• Debug: ข้อมูลการดีบักโดยละเอียด
• Information: ข้อมูลทั่วไป (ค่าเริ่มต้น)
• Warning: คําเตือนเท่านั้น
• Error: ข้อผิดพลาดเท่านั้น

เนื้อหาที่เกี่ยวข้อง

• รันไทม์ Apache Spark ใน Fabric
• รันไทม์ของผ้า 1.3
• Livy API สําหรับวิศวกรรมข้อมูลคืออะไร
• ไดรเวอร์ Microsoft JDBC สําหรับ Fabric Data Engineering
• ไดรเวอร์ Microsoft ODBC สําหรับ Fabric Data Engineering