Microsoft ADO.NET-ajuri Microsoft Fabric Data Engineeringille

ADO.NET on laajasti käytössä oleva datan käyttöteknologia .NET-ekosysteemissä, joka mahdollistaa sovellusten yhteyden tietokantojen ja big data -alustojen datan kanssa työskentelyyn.

Microsoft ADO.NET Driver for Fabric Data Engineering mahdollistaa Spark-työkuormien yhdistämisen, kyselyn ja hallinnan Fabric-järjestelmässä tavallisten ADO.NET-mallien luotettavuudella ja yksinkertaisuudella. Fabric:n Livy-rajapintojen pohjalta rakennettu ajuri tarjoaa turvallisen ja joustavan Spark SQL -yhteyden .NET-sovelluksiin tuttujen DbConnection, DbCommand, ja DbDataReader abstraktioiden avulla.

Tärkeimmät ominaisuudet

• ADO.NET API:t: Tutut DbConnection, DbCommand, DbDataReader, DbParameter, ja DbProviderFactory abstraktiot Spark SQL -yhteyksille
• Microsoft Entra ID -tunnistautuminen: Useita todennusprosesseja, mukaan lukien Azure CLI, interaktiivinen selain, asiakastunnukset, varmennepohjainen ja pääsytunnusen tunnistautuminen
• Spark SQL Native Query Support: Spark SQL -lauseiden suora suoritus parametrisoiduilla kyselyillä
• Kattava tietotyyppituki: Tuki kaikille Spark SQL -tietotyypeille, mukaan lukien monimutkaiset tyypit (TAULUKKO, KARTTA, RAKENNE)
• Connection pooling: Sisäänrakennettu yhteyspoolin hallinta suorituskyvyn parantamiseksi
• Session uudelleenkäyttö: Tehokas Spark-istuntojen hallinta käynnistysviiveen vähentämiseksi
• Korkean samanaikaisuuden istunnot: Valita jaettu Fabric Livy -kapasiteetti erillisillä REPL-tiloilla samanaikaisesti vuokratuille HC-istunnoille
• Asynkroninen esilataus: Taustalla lataava datan lataus parantaa suorituskykyä suurilla tulosjoukoilla
• Automaattinen uudelleenyhdistäminen: Klassisen istunnon palautus yhteyden epäonnistumisen jälkeen; HC-virheet havaitaan sovelluksen ohjaaman uudelleenkokeilun yhteydessä

Edellytykset

Ennen kuin käytät Microsoft ADO.NET Driver for Fabric Data Engineeringia, varmista, että sinulla on:

• .NET Runtime: .NET 8.0 tai uudempi
• Fabric Access: Pääsy Fabric-työtilaan, jossa on data-insinöörin kyvykkyydet
• Azure Entra ID -tunnus Credentials: Sopivat tunnistetiedot autentikointiin
• Workspace- ja Lakehouse-tunnisteet: GUID-tunnisteet Fabric-työtilallesi ja järvenrakennukselle
• Azure CLI (valinnainen): Vaaditaan Azure CLI -todennusmenetelmälle

Lataa, sisällytä, viittaa ja varmista

Lataa NuGet-paketti

• Lataa Microsoft ADO.NET Driver for Fabric Data Engineering (zip)
• Lataa Microsoft ADO.NET Driver for Fabric Data Engineering (tar)

Viittaa NuGet-pakettiin projektissasi

Sisällytä ladattu NuGet-paketti projektiisi ja lisää paketin viite projektitiedostoosi:

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

Asennuksen tarkistaminen

Sisällytyksen ja viitteen jälkeen varmista, että paketti on saatavilla projektissasi:

using Microsoft.Spark.Livy.AdoNet;

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

Nopea aloitusesimerkki

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

Yhteysmerkkijonomuoto

Perusformaatti

Microsoft ADO.NET Driver käyttää tavallista ADO.NET-yhteysmerkkijonomuotoa:

Parameter1=Value1;Parameter2=Value2;...

Pakolliset parametrit

Valinnaiset parametrit

Yhteysasetukset

Yhteysaltaan asetukset

Korkeat samanaikaisuusasetukset

Lokiasetukset

Ristiinkuljettajien aliakset: Ajuri hyväksyy JDBC- ja ODBC-ominaisuusnimet natiivien ADO.NET-nimien lisäksi (esim. WorkspaceId kartat , FabricWorkspaceIDLakehouseId kartat ).FabricLakehouseID Kaikkien kiinteistöjen nimet ovat kirjainkoon riippumattomia.

Esimerkkejä yhteysmerkkijonoista

Perusyhteys (Azure CLI authentication)

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

Korkea rinnakkaisyhteys

Korkea samanaikaisuus on saatavilla Microsoft Fabric -yhteyksille. Aseta HcEnabled=true; standardit ADO.NET-yhteys- ja komentorajapinnat pysyvät ennallaan. Käytä versioittamatonta Fabric API -isäntää Server; ajuri käyttää FabricVersion=v1 ja LivyApiVersion=2023-12-01 oletuksena rakentaessaan HC-päätepistettä.

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

Täydelliset konfigurointiohjeet löydät High-Concurrency (HC) Mode -osiosta.

Yhteyspoolausvaihtoehdoilla

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

Automaattisella uudelleenyhdistämisellä ja lokituksella

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

Todentaminen

Microsoft ADO.NET Driver tukee useita todennusmenetelmiä Microsoft Entra ID:n (entinen Azure Active Directory) kautta. Tunnistautuminen konfiguroidaan yhteysmerkkijonon AuthFlow parametrin avulla.

Todennusmenetelmät

Azure CLI -todennus

Paras: Kehitykseen ja testaukseen

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

Edellytykset:

• Azure CLI asennettu: az --version
• Kirjautunut sisään: az login

Interaktiivinen selaimen tunnistautuminen

Parhaiten: Käyttäjäkohtaisille sovelluksille

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

Toiminta:

• Avaa selaimen ikkunan käyttäjän tunnistautumista varten
• Tunnistetiedot tallennetaan välimuistiin seuraavia yhteyksiä varten

Asiakastunnisteiden (Service Principal) todennus

Paras: Automatisoidut palvelut ja taustatyöt

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

Vaaditut parametrit:

• AuthTenantID: Azure vuokralaisen tunnus
• AuthClientID: Application (client) ID Microsoft Entra ID:stä
• AuthClientSecret: Asiakassalaisuus Microsoft Entra ID:stä

Varmennepohjainen todentaminen

Paras: Yrityssovelluksiin, jotka vaativat varmennepohjaista todennusta

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

Vaaditut parametrit:

• AuthTenantID: Azure vuokralaisen tunnus
• AuthClientID: Sovelluksen (asiakas) tunnus
• AuthCertificatePath: Polku PFX/PKCS12-varmennetiedostoon
• AuthCertificatePassword: Varmenteen salasana

Pääsytunnuksen tunnistautuminen

Parhaiten: Mukautetut todennusskenaariot

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

Käyttöesimerkkejä

Perusyhteys ja kysely

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

Parametrisoidut kyselyt

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 yksittäisille arvoille

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

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

ExecuteNonQuery DML-operaatioille

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

Työskentely suurten tulosjoukkojen kanssa

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

Skeeman löytö

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

LivyConnectionStringBuilderin käyttö

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

DbProviderFactoryn käyttö

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

Korkean samanaikaisuuden (HC) tila

Korkean rinnakkaisuuden (HC) tila auttaa .NET-sovelluksia suorittamaan samanaikaisia Spark SQL -työkuormia ilman, että jokaiselle ADO.NET-yhteydelle tarvitaan erillistä klassista Spark-istuntoa. Fabric voivat sijoittaa yhteensopivat yhteydet samaan palvelimen hallinnoimaan Livy-istuntoon samalla kun jokaiselle yhteydelle on eristetty Read-Eval-Print Loop (REPL) lauseen suoritusta varten.

Tämä malli voi lyhentää yhteyden käynnistysaikaa, välttää toistuvan Spark-istunnon provisionoinnin ja käyttää Fabric Spark -kapasiteettia tehokkaammin. Sovelluksesi käyttää edelleen standardeja ADO.NET-rajapintoja, mukaan lukien DbConnection, DbCommand, DbDataReader, OpenAsync, ja Close.

HC-tila on vapaaehtoinen. Jos et ota sitä käyttöön, ajuri käyttää klassista Livyn istuntopolkua.

Valitse HC:n ja klassisen tilan välillä

Käytä HC-tilaa, kun:

• ASP.NET-palvelu käsittelee samanaikaisia pyyntöjä, jotka avaavat yhteydet ja ajavat Spark SQL:ää.
• Työntekijäpalvelu, aikataulutettu työ tai rinnakkainen dataputki luo ADO.NET-yhteyksien purskeita.
• Useat yhteydet kohdistuvat samaan Fabric-työtilaan ja järvenrakennukseen ja käyttävät yhteensopivia Spark-konfiguraatioita.
• Yhteyden käynnistysajan ja toistuvan Spark-istunnon provisionoinnin lyhentäminen on tärkeää.
• Työkuormasi voi käyttää jaettua, palvelimen hallinnoimaa Spark-kapasiteettia samalla kun lauseen suoritus pysyy erillään REPL:llä.

Käytä klassista tilaa, kun:

• Sovelluksesi käyttää vain yhtä tai muutamaa pitkäaikaista yhteyttä.
• Jokainen yhteys vaatii omistetun Spark-istunnon tiukkaa työkuormaa tai resurssien eristämistä varten.
• Yhteydet vaativat merkittävästi erilaisia Spark-konfiguraatioita, jotka eivät saisi jakaa taustalla olevaa istuntoa.
• Fabric Livy -päätepiste kohdetyötilalle ja järvitalolle ei tue HC-tilaa.

Miten HC-yhteydet toimivat

Kun sovelluksesi kutsuu Open tai OpenAsync ei ole yhteensopivaa pooliyhteyttä, ajuri:

1. Pyytää HC-istuntoa Fabric:lta.
2. Odottaa, että istunto on valmis, aina määritettyyn hankintaaikarajaan asti.
3. Yhdistää ADO.NET-yhteyden määritettyyn HC-istuntoon ja REPL:ään.
4. Ohjaa komentoja, kyselyitä, peruutuspyyntöjä ja siivousoperaatioita HC-päätepisteiden kautta.

Erilliset samanaikaisesti vuokratut HC-istunnot käyttävät erillisiä REPL-tiloja. Yhden yhteyden komennot jakavat kyseisen yhteyden HC-istunnon ja REPL:n.

Asiakaspuolen poolaus on oletuksena käytössä. Kelvollisen yhteyden sulkeminen tai poistaminen palauttaa yleensä sen fyysisen HC-istunnon ja REPL:n prosessipaikalliseen pooliin uudelleenkäyttöä varten; se ei välttämättä vapauta tehtävää etänä. Kun poolaus on pois päältä, fyysisen yhteyden sulkeminen suorittaa HC-puhdistuksen. Jatka lauseiden käyttöä using , jotta loogiset yhteydet palautuvat nopeasti.

Ota HC-tila käyttöön

HC-tila on vapaaehtoinen. Jos jätät hcEnabled sen pois tai asetat vääräksi, ajuri käyttää klassista Livyn sessiopolkua.

Aseta ominaisuus hcEnabled tosiksi saadaksesi HC-istunnon:

hcEnabled=true;

Istuntojen pakkaamisen konfigurointi

HcSessionTag tarjoaa palvelinpuolen vihjeen yhteensopivien HC-istuntojen pakkaamiseen taustalla olevaan Livy-istuntoon. Yhteensopiva tunniste ei takaa sijoitusta samaan taustalla olevaan sessioon.

Jos jätät tagin pois tai annat tyhjän tai pelkästään tyhjän tilan arvon, ajuri ei lähetä sitä hankintapyynnössä. Tagin poisjättäminen ei poista käytöstä HC-tilaa tai palvelupuolen pakkaamista. Aseta eksplisiittinen tunniste, milloin toisiinsa liittyvät sovellusinstanssit tai työkuormat tulisi ottaa huomioon jaetun kapasiteetin osalta. Käytä vakaata, ei-herkkää toimintamerkkiä, kuten reporting-service tai nightly-etl. Älä sisällytä salaisuuksia, pääsytunnukkeja, henkilötietoja, asiakastunnisteita tai kyselytekstiä.

Kipinäkonfiguraatio vaikuttaa myös istuntojen yhteensopivuuteen. Käytä HcConfOverrides sallittujen Spark-asetusten tarjoamiseen HC-istunnon luomiseen:

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

Useista ohituksista ilmoita koko HcConfOverrides arvo. Lainausmerkitön puolipiste aloittaa toisen ulkoisen yhteysmerkkijonon ominaisuuden; se ei laajenna HcConfOverrides. Jäsentäjä hyväksyy yksi- tai kaksinkertaiset lainausarvot, säilyttää puolipisteet ja yhtäsuuruusmerkit lainausarvojen sisällä, ja purkaa kaksinkertaiset vastaavat lainausmerkit ('' tai ""). Tyhjä tila ominaisuuksien nimien ympärillä ja lainaamattomien arvojen ulkoreunoilla jätetään huomiotta. Tyhjä tila lainauksettomien arvojen sisällä ja kaikki tyhjä tila lainattujen arvojen sisällä säilyy. Tyhjät arvot ohittavat ympäristön oletukset, ja viimeinen kaksoisominaisuus voittaa.

Voit myös antaa LivyConnectionStringBuilder lainauksen hoitaa:

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;

Nämä esimerkit vaativat Microsoft ADO.NET Driver version 2.0.1 tai uudemman. Lisää työtilasi ja järvimajan tunnisteet ennen yhteyden avaamista. Molemmat ohitukset lähetetään HC:n luomisistuntopyynnössä erillisinä conf merkintöinä. Jokaisen ohituksen on käytettävä yhtä näistä kirjainkoon herkistä näppäimistä:

• 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

Väärin muotoillut lainausmerkit hylätään ilman, että yhteysjonon sisältö sisällytetään jäsennysvirheeseen.

Käytä yhtenäisiä tageja ja konfiguraatioarvoja yhteyksien välillä, joiden kapasiteetti on tarkoitettu jakamaan. Fabric määrittää, voiko pyyntö käyttää olemassa olevaa istuntoa vai vaatiiko se toisen istunnon.

Määritä hankinta-ajoitus

Käytä seuraavia asetuksia ohjataksesi, kuinka kauan kuljettaja odottaa HC-istuntoa:

Useimmissa työkuormissa säilytä oletusarvot. Lisää hankintaaikaa vain, kun kapasiteetin käynnistys kestää säännöllisesti yli viisi minuuttia.

Käytä HC-tilaa yhteyspoolauksessa

HC-tila ja ADO.NET-yhteyspoolaus osoittavat eri kerroksia:

• HC-tila hallinnoi jaettua Fabric Spark -kapasiteettia ja Livy-istuntoja palvelimella.
• ADO.NET-yhteyspoolaus käyttää ajurien hallinnoimia yhteysresursseja asiakassovelluksessa.

Voit ottaa molemmat ominaisuudet käyttöön. Yhteyspoolaus vähentää toistuvaa asiakaspuolen yhteyden muodostusta, kun taas HC-tila vähentää toistuvaa palvelinpuolen Spark-istuntojen provisiointia. Kokoa yhteyspooli sovelluksen odotetun rinnakkaiskäytön mukaan sen sijaan, että käyttäisit suurta poolia tarpeettoman rinnakkaistyön luomiseen.

HC-tilassa AutoReconnect=true se ei läpinäkyvästi toista epäonnistunutta komentoa vanhentuneen istuntovirheen jälkeen. Sovellus saa poikkeuksen ja sen on päätettävä, onko operaation uudelleenyrittäminen turvallista.

Poista HC-tila käytöstä

Käyttääksesi klassista tilaa uusille yhteyksille, poista HcEnabled yhteysmerkkijono tai aseta se :false

HcEnabled=false

Muutos vaikuttaa uusiin yhteyksiin eikä poista olemassa olevia HC-istuntoja. Sulje tai hävitä loogiset yhteydet normaalisti; kelpoiset fyysiset istunnot voivat pysyä asiakaspoolissa, kunnes ne jäävät eläkkeelle.

ADO.NET-rajoitukset

• Transaktioita ei tueta.
• Komennot tukevat vain tekstikomentotilaa. Tallennettu proseduuri ja taulu-suorakomentotilat eivät ole tuettuja.
• Prepare ei tee mitään.
• Käskyn täytyy sisältää yksi lause; monilauseinen komentoteksti hylätään.
• Käytä erillisiä, samanaikaisesti avoimia yhteyksiä samanaikaisille työkuormille. Yhden yhteyden komennot jakavat istunnon ja REPL:n.

Tietotyyppien kartoittaminen

Ajuri kartoittaa Spark SQL -tietotyypit .NET-tyyppeihin:

Työskentely monimutkaisten tyyppien kanssa

HC-tulospolku ei luotettavasti serialisoi natiivisti sisäkkäisiä ARRAY-, MAP- tai STRUCT-arvoja JSON-muodossa. Project kompleksiarvot JSON-merkkijonoiksi Spark SQL:ssä ennen niiden deserialisointia:

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

Vianmääritys

Tämä osio antaa ohjeita yleisten ongelmien ratkaisemiseen, joita saatat kohdata käyttäessäsi Microsoft ADO.NET Driver for Fabric Data Engineeringiä.

Yleisiä ongelmia

Seuraavissa osioissa kuvataan yleisiä ongelmia ja niiden ratkaisuja:

Yhteyden epäonnistumiset

Ongelma: En saa yhteyttä Fabric-ohjelmaan

Ratkaisut:

1. Varmista FabricWorkspaceID ja FabricLakehouseID ovatko oikeat GUID-tiedostot
2. Tarkista Azure CLI -autentikointi: az account show
3. Varmista, että sinulla on asianmukaiset Fabric-työtilaoikeudet
4. Varmista verkkoyhteys api.fabric.microsoft.com

Todennusvirheet

Ongelma: Todennus epäonnistuu Azure CLI:llä

Ratkaisut:

• Juokse az login päivittääksesi tunnukset
• Varmista oikea vuokralainen: az account set --subscription <subscription-id>
• Tarkista tokenin pätevyys: az account get-access-token --resource https://api.fabric.microsoft.com

Kyselyn aikakatkaisut

Ongelma: Kyselyt aikakatkaistuvat suurilla tauluilla

Ratkaisut:

• Pidennä lauseen aikakatkaisu: LivyStatementTimeoutSeconds=1200.
• Käytä LIMIT lauseketta rajoittamaan tuloskokoa kehityksen aikana
• Varmista, että Spark-klusterilla on riittävät resurssit

Yhteys- tai HC-hankintaaikakatkaisu

Ongelma: Yhteys aikakatkaisee odottaessaan poolitettua yhteyttä tai HC-istuntoa

Ratkaisut:

• Asiakaspoolin odotusta ja HTTP-yhteyden perustamista varten tarkista HttpConnectionTimeoutInSeconds.
• HC-hankinnassa nostetaan hcAcquireTimeoutSeconds tuetun 120–3 600 sekunnin välissä.
• Tarkista kankaan kapasiteetin saatavuus
• Varmista, ettei työtila ole saavuttanut istuntorajoja

Lokituksen ottaminen käyttöön

Ongelmien vianetsinnässä yksityiskohtainen lokitus voi auttaa tunnistamaan juurisyyn. Määritä lokitus yhteysmerkkijono:n kautta:

Yksityiskohtaisen lokituksen mahdollistamiseksi yhteysmerkkijonon kautta:

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

Jos et aseta LogFilePath globaalia lokiasetusta, ajuri kirjoittaa lokit %LOCALAPPDATA%\FabricSparkAdoNet\Logs alle Windows.

Lokitasot:

• Trace: Monisanainen, sisältää kaikki API-kutsut
• Debug: Yksityiskohtaista virheenkorjaustietoa
• Information: Yleistä tietoa (oletus)
• Warning: Vain varoitukset
• Error: Vain virheet

Liittyvä sisältö

• Apache Spark -suoritusajat Fabricissa
• Kankaan käyttöaika 1.3
• Mikä on Livy API data-insinöörille
• Microsoft JDBC -ajuri Fabric Data Engineeringille
• Microsoft ODBC -ajuri Fabric Data Engineeringille