Microsoft ODBC-ajuri Microsoft Fabric Data Engineeringille Linuxilla

ODBC (Open Database Connectivity) on laajasti hyväksytty standardi, joka mahdollistaa asiakassovellusten yhteyden tietokantojen ja big data -alustojen datan käsittelyn ja sen kanssa.

Microsoft ODBC Driver for Fabric Data Engineering mahdollistaa Spark-työkuormien yhdistämisen, kyselyn ja hallinnan Fabric-järjestelmässä ODBC-standardin luotettavuudella ja yksinkertaisuudella. Fabric:n Livy-rajapintojen pohjalta rakennettu ajuri tarjoaa turvallisen ja joustavan Spark SQL -yhteyden C/C++-, .NET-, Python- ja muihin ODBC-yhteensopiviin Linux-sovelluksiin.

Tärkeimmät ominaisuudet

• ODBC 3.x -yhteensopivuus: ODBC 3.x -määrittelyn täysi toteutus.
• Microsoft Entra ID -tunnistautuminen: Useita todennusprosesseja, mukaan lukien Azure CLI, asiakastunnukset, varmennepohjainen ja pääsytunnusen tunnistautuminen.
• Spark SQL -kyselytuki: Spark SQL -lauseiden suora suoritus.
• Kattava tietotyyppituki: Tuki kaikille Spark SQL -tietotyypeille, mukaan lukien monimutkaiset tyypit (ARRAY, MAP, ja STRUCT).
• Istunnon uudelleenkäyttö: Sisäänrakennettu istunnonhallinta suorituskyvyn parantamiseksi.
• Korkean samanaikaisuuden tila: Valitse jaettuja, lämpimiä palvelinpuolen Livy-istuntoja yhteyden käynnistysviiveen ja Spark-klusterin leviämisen vähentämiseksi.
• Suuren taulun tuki: Optimoitu käsittely suurille tulosjoukoille, joissa sivukoot ovat konfiguroitavia.
• Asynkroninen esilataus: Taustalla lataava data suorituskyvyn parantamiseksi.
• Välityspalvelintuki: HTTP-välityspalvelimen konfiguraatio yritysympäristöihin.
• Moniskeemainen järvitalotuki: Yhdistä tiettyyn skeemaan järvimajassa.

Edellytykset

Ennen kuin käytät Microsoft ODBC Driveria Microsoft Fabric Data Engineeringille Linuxissa, varmista, että sinulla on seuraavat edellytykset:

• Käyttöjärjestelmä: Ubuntu 22.04 tai uudempi, Debian 11 tai uudempi, tai Red Hat Enterprise Linux (RHEL) 8 tai uudempi x86-64.
• unixODBC: Linuxin ODBC-ajurien hallintaohjelma. Asenna unixodbc ja-paketit unixodbc-dev .
• libcurl: HTTP-ajonaikainen riippuvuus, kuten libcurl4 tai vastaava paketti jakelullesi.
• OpenSSL: TLS- ja kryptografian ajonaikainen riippuvuus, kuten openssl vastaavat libssl3 paketit.
• Fabric access: Pääsy Fabric-työtilaan.
• Microsoft Entra ID -tunnukset: Sopivat tunnistetiedot todennukseen.
• Työtilan ja järvenrakennuksen tunnukset: GUID-tunnisteet Fabric-työtilallesi ja järventalolle.
• Azure CLI (valinnainen): Vaaditaan, kun käytät Azure CLI -tunnistautumista.

Lataa ja asenna Linuxille

• Lataa Microsoft ODBC Driver for Microsoft Fabric Data Engineering on Linux (tar)

Ajurin asentamiseen:

1. Poimi ms-sparksql-odbc-linux-2.0.0.tar.

2. Avaa terminaali puretusta hakemistosta.

3. Asenna Debian-paketti:

   sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb
   

Paketti asentaa seuraavat tiedostot:

Asenna RPM-paketti

RHEL:llä, Fedoralla tai CentOS:lla asenna RPM-paketti puretusta ajuriarkistosta:

sudo dnf install ./microsoft-fabric-odbc-driver-*.x86_64.rpm

Vaihtoehtoisesti käytä rpm:

sudo rpm -i microsoft-fabric-odbc-driver-*.x86_64.rpm

Varmista, että RPM rekisteröi ajurin:

odbcinst -q -d | grep "Microsoft"

Poistaaksesi RPM-paketin, suorita:

sudo dnf remove microsoft-fabric-odbc-driver

Asenna tarballi

Jakeluissa, joissa ei ole Debian- tai RPM-pakettitukea, tai mukautetulle asennuspaikalle, purkaa paketti .tar.gz ja suorita sen asennusskripti:

tar -xzf microsoft-fabric-odbc-driver-2.0.0-linux-x86_64.tar.gz
cd microsoft-fabric-odbc-driver-2.0.0

# Install to /opt/microsoft/fabricodbc.
sudo ./install.sh

# Or install to a custom writable location.
./install.sh --prefix=$HOME/fabricodbc

Asennusskripti tukee näitä vaihtoehtoja:

Varmistaaksesi oletus-tarball-asennuksen, suorita:

odbcinst -q -d
ls -la /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so

Poistaaksesi sen, suorita sudo ./install.sh --uninstall puretusta pakettihakemistosta.

Rekisteröi ajuri manuaalisesti

Paketti rekisteröi ajurin automaattisesti unixODBC:llä. Rekisteröidäksesi ajurin manuaalisesti, suorita:

sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template

Tarkista asennus

Varmista, että ajuri on rekisteröity ja kirjasto asennettu:

odbcinst -q -d
ls -la /usr/lib/libmicrosoftfabricodbc.so

Käskyn odbcinst tulisi listata [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Poista ajuri

Poistaaksesi ajurin, suorita seuraava komento:

sudo dpkg -r microsoft-fabric-odbc-driver

Tämä komento poistaa ajuritiedostot ja poistaa ajurin rekisteröinnin unixODBC:stä.

Nopea aloitusesimerkki

Seuraavat esimerkit yhdistävät Fabric-tiedostoon ja suorittavat Spark SQL -kyselyn. Suorita vaaditut vaatimukset ja asenna ajuri ennen kuin suoritat esimerkin.

Python-esimerkki

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

conn = pyodbc.connect(connection_string, timeout=30)
cursor = conn.cursor()

cursor.execute("SELECT 'Hello from Fabric!' AS message")
row = cursor.fetchone()
print(row.message)

conn.close()

C/C++-esimerkki

#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV henv = SQL_NULL_HENV;
    SQLHDBC hdbc = SQL_NULL_HDBC;
    SQLHSTMT hstmt = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

    const char* connectionString =
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;";

    SQLRETURN result = SQLDriverConnect(
        hdbc,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        std::cout << "Connected successfully!" << std::endl;

        SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        result = SQLExecDirect(
            hstmt,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(hstmt) == SQL_SUCCESS) {
                SQLGetData(
                    hstmt,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
        SQLDisconnect(hdbc);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return 0;
}

Rakenna ja suorita esimerkki:

g++ -o fabric_test fabric_test.cpp -lodbc -std=c++17
./fabric_test

.NET-esimerkki

using System.Data.Odbc;

string connectionString =
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand(
    "SELECT 'Hello from Fabric!' AS message",
    connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Yhteysmerkkijonomuoto

Perusyhteysjono

Käytä seuraavaa yhteysmerkkijono -muotoa:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};<parameter1>=<value1>;<parameter2>=<value2>;...

Yhteysmerkkijonon komponentit

Esimerkkejä yhteysmerkkijonoista

Perusyhteys

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI

Yhteys suorituskykyvaihtoehtoihin

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;ReuseSession=true;LargeTableSupport=true;PageSizeBytes=18874368

Yhteys lokitukseen

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=/tmp/odbc_driver.log

Yhteys korkean samanaikaisuuden tilaan

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Täydelliset konfiguraatioohjeet löytyvät kohdasta Korkean samanaikaisuuden (HC) tila.

Todennus

Microsoft ODBC Driver for Microsoft Fabric Data Engineering tukee useita todennusmenetelmiä Microsoft Entra ID:n kautta. Määritä todennus käyttämällä AuthFlow parametria yhteysmerkkijono:ssä tai DSN:ssä.

Todennusmenetelmät

Azure CLI -todennus

Käytä Azure CLI -todennuksia kehitykseen ja interaktiivisiin sovelluksiin.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Ennen kuin yhdistät, varmista, että Azure CLI on asennettu ja kirjaudu sisään:

az --version
az login

Jos haluat asentaa Azure CLI:n Debianiin tai Ubuntuun käyttämällä pakettihallintaa:

sudo apt-get update
sudo apt-get install -y azure-cli

Asiakastunnisteiden todennus

Käytä asiakastunnisteiden tunnistautumista automatisoituihin palveluihin ja taustatehtäviin.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CREDENTIAL;"
    f"TenantId={tenant_id};"
    f"ClientId={client_id};"
    f"ClientSecret={client_secret};"
)

Anna seuraavat parametrit:

• TenantId: Microsoft Entra -vuokralaisen ID.
• ClientId: Sovelluksen (asiakas) tunnus.
• ClientSecret: Asiakassalaisuus.

Tallenna salaisuudet turvalliseen salavarastoon tai ympäristömuuttujiin. Älä tallenna salaisuuksia selväkielisiin yhteysjonoihin tai INI-tiedostoihin.

Varmennepohjainen todentaminen

Käytä varmennepohjaista tunnistautumista yrityssovelluksissa, jotka vaativat varmennetunnon tunnisteet.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CERTIFICATE;"
    "TenantId=<tenant-id>;"
    "ClientId=<client-id>;"
    "CertificatePath=/path/to/cert.pfx;"
    "CertificatePassword=<password>;"
)

Anna seuraavat parametrit:

• TenantId: Microsoft Entra -vuokralaisen ID.
• ClientId: Sovelluksen (asiakas) tunnus.
• CertificatePath: Polku PFX- tai PKCS12-varmennetiedostoon.
• CertificatePassword: Sertifikaatin salasana.

Pääsytunnuksen tunnistautuminen

Käytä käyttöoikeustunnisteen tunnistautumista, kun sovelluksesi hankkii tokenin toisen mekanismin kautta.

access_token = acquire_token_from_custom_source()

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=ACCESS_TOKEN;"
    f"AccessToken={access_token};"
)

Tiedostotunnuksen tunnistautuminen

Käytä tiedostotoken-tunnistautumista konttipohjaisissa ympäristöissä ja automatisoiduissa putkissa, joissa toinen prosessi kirjoittaa kantajatokenin kuljettajan tunnettuun token-tiedostoon:

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

Tuetuista ristiinajurien omaisuusaliaksista katso Ristiinkuljettajien ominaisuusalias.

Määritysparametrit

Pakolliset parametrit

Sisällytä nämä parametrit jokaiseen yhteysmerkkijonoiin:

Valinnaiset parametrit

Yhteysasetukset

Esitysasetukset

Lokiasetukset

Välityspalvelimen asetukset

Korkean samanaikaisuuden (HC) asetukset

Käytä näitä parametreja ottaaksesi käyttöön ja konfiguroidaksesi korkean samanaikaisuuden (HC) tilan. HC-tila on vapaaehtoinen. Jos et aseta LivyMode tai UseHighConcurrency, ajuri käyttää klassista yhden session polkua. Ohjeita ja esimerkkejä varten katso Korkean samanaikaisuuden (HC) tila.

Moodien etusijaisuus ja validointi

• LivyMode Se menee etusijalle, UseHighConcurrency kun asetat molemmat parametrit.
• Parametriarvot eivät ole kirjainkoon herkkiä.
• UseHighConcurrency hyväksyy true, 1, yes, tai on HC-tilan aktivoimiseksi. Se hyväksyy false, 0, no, tai off HC-tilan poistamiseksi käytöstä.
• Muiden ei-tyhjien arvojen kohdalla palauttaa SQLDriverConnect virheen. DSN-only SQLConnect kirjaa validointivirheen ja käyttää klassista polkua.

Yhteensopivuusasetukset

Ajuri hyväksyy TenantPrincipal ja PoolMax, mukaan lukien ympäristön muuttuvat varasuunnitelmat, yhteensopivuuden vuoksi aiempien HC-konfiguraatioiden kanssa. Ajuri jäsentää ja validoi nämä arvot, mutta ne eivät vaikuta HC-istuntojen sovitukseen tai ajonaikaiseen poolin kapasiteettiin. Älä luota niihin vuokralaisten eristyksessä tai yhteysrajoituksissa.

Ympäristömuuttujien varasuunnitelmat

Ajuri käyttää seuraavia ympäristömuuttujia vain, kun vastaavaa DSN- tai connection-string-parametria ei ole asetettu:

Kun FABRIC_ODBC_USE_HC, pelkkä ympäristön mahdollistaminen tunnistaa true, 1, tai yes (sijainherkkyys). Muut arvot jättävät HC-tilan pois päältä. Ja-aliakset onoff koskevat vain DSN- ja yhteysmerkkijonojen arvoja.

Korkean samanaikaisuuden (HC) tila

High-concurrency (HC) -tila mahdollistaa ODBC-yhteyksien liittämisen samaan työtilaan ja lakehouseen yhteisiin, lämpimiin palvelinpuolen Livy Spark -sessioihin sen sijaan, että jokaiselle yhteydelle olisi oma klusteri. Käytä sitä työkuormiin, kuten BI-hallintapaneelit, notebook-ytimet ja ETL-hajautus, jotka avaavat monia lyhytikäisiä yhteyksiä ja voivat jakaa palvelimen hallinnoiman Spark-kapasiteetin.

HC-tila on vapaaehtoinen. Jos et määritä HC-asetusta, ajuri käyttää klassista yhden istunnon polkua.

Yhteystilan valitseminen

Käytä HC-tilaa, kun:

• Työkuormasi avaa monia lyhytikäisiä ODBC-yhteyksiä, kuten BI-hallintapaneelit, notebook-ytimet tai ETL-hajautuksen.
• Yhteydet kohdistuvat samaan työtilaan ja järvimajaan ja voivat jakaa palvelimen hallinnoiman Spark-istunnon.
• Jokaisen yhteyden kylmäkäynnistyksen viiveen vähentäminen on tärkeää.

Käytä klassista tilaa, kun:

• Jokainen yhteys vaatii erillisen Spark-istunnon erilaisten Spark-asetusten tai tiukan resurssieristyksen vuoksi.
• Fabric Livy -päätepiste kohdetyötilalle ja järvitalolle ei tue HC-tilaa.

Ota käyttöön korkean samanaikaisuuden tila

Lisää DSN:ään tai yhteysmerkkijonoiin korkean samanaikaisuuden tilan parametri.

Suositeltava: Setti LivyMode

Käytä LivyMode valitaksesi istunnon hankintatilan eksplisiittisesti:

LivyMode=HighConcurrency

Tuettuja arvoja ovat Classic, HighConcurrencyja Auto. Arvot eivät ole kirjainkoon herkkiä. Auto tällä hetkellä valitsee klassisen tilan.

Vaihtoehto: Aseta UseHighConcurrency

Käytä Boolean-asetusta yhteensopivuuden varmistamiseksi olemassa olevien kokoonpanojen kanssa:

UseHighConcurrency=true

Korkean samanaikaisuuden tilan aktivoimiseksi käytä true, 1, yes, tai on. Poistaaksesi sen käytöstä, käytä false, 0, no, tai off. Arvot eivät ole kirjainkoon herkkiä. SQLDriverConnect hylkää muut ei-tyhjät arvot SQLSTATE HY024:llä . Pelkkä SQLConnect DSN-kirjaa validointivirheen ja käyttää klassista tilaa.

Voit myös ottaa käyttöön korkean samanaikaisuuden tilan nykyiselle kuorelle käyttämällä ympäristömuuttujia:

export FABRIC_ODBC_USE_HC=true
export FABRIC_ODBC_WORKSPACE_ID=<workspace-id>
export FABRIC_ODBC_LAKEHOUSE_ID=<lakehouse-id>
export FABRIC_ODBC_SESSION_TAG=bi-dashboard

Vaaditut parametrit HC-tilassa

HC-aktivointi vaatii seuraavat kelvolliset tunnisteet:

Sisällytä SessionTag , koska se vaikuttaa palvelinpuolen matchaukseen lämpimissä sessioissa.

Istuntojen yhdistäminen

HC-tila ei takaa, että jokainen yhteys käyttää olemassa olevaa istuntoa uudelleen. Jokaisesta istuntokeruuspyynnöstä kuljettaja lähettää:

• Arvo SessionTag .
• Tehokas Spark-konfiguraatio, mukaan lukien conf.* asetukset ja EnvironmentId.

Fabric Livy -palvelu arvioi nämä arvot ja päättää, liitetäänkö yhteys lämpimään istuntoon vai luodako uusi istunto. Istunnon uudelleenkäytön parantamiseksi käytä yhtenäisiä arvoja yhteyksien välillä, joiden on tarkoitus jakaa palvelimen hallinnoima Spark-kapasiteetti.

Esimerkkejä yhteysmerkkijonoista

Minimaalinen HC-yhteys Azure CLI -autentikointiin:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

HC-yhteys viritetyillä aikakatkaisuilla:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

HC-yhteys ympäristöön ja Spark-konfiguraatio ohittaa:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python, jossa pyodbc:

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

HC-tilan konfigurointi Linux DSN:ssä

Sen sijaan, että toistaisit HC-asetukset jokaisessa yhteysmerkkijono, tallenna ~/.odbc.ini ne käyttäjäkohtaiseen DSN:ään tai /etc/odbc.ini koko järjestelmän DSN:ään.

[FabricHCDSN]
Description               = Microsoft Fabric Data Engineering with HC mode
Driver                    = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId               = <workspace-id>
LakehouseId               = <lakehouse-id>
AuthFlow                  = AZURE_CLI
LivyMode                  = HighConcurrency
SessionTag                = bi-dashboard
AcquireTimeoutSeconds     = 300
HeartbeatTimeoutInSecond  = 600

Kun olet tallentanut DSN:n, varmista se ja testaa yhteys.

odbcinst -q -s
isql -k -v "DSN=FabricHCDSN;"

Kun yhteysmerkkijono ei määritä arvoa, ajuri lukee seuraavat asetukset DSN:stä:

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

Ajuri lukee myös pelkästään TenantPrincipal yhteensopivuuden ja PoolMax asetukset. Käytä HC-asetustaulukon parametrien nimiä.

Poista HC-tila käytöstä

Voit poistaa uudet HC-istunnon hankinnat käytöstä ilman, että joudut ottamaan ajurin uudelleen käyttöön. Käytä menetelmää, joka vastaa HC-tilan käyttöönottoa:

Yhteysmerkkijonon ja DSN-asetukset ovat etusijalla ympäristömuuttujan varasuunnitelmaan nähden. Nämä muutokset koskevat vain uusia yhteyksiä. Nykyiset HC-istunnot jatkuvat, kunnes ne julkaistaan.

Ymmärrä HC:n ajonaikainen käyttäytyminen

• Validointi:SQLDriverConnect hylkää virheelliset HC Boolean- ja positiiviset kokonaislukuarvot SQLSTATE HY024:llä. Se hylkää virheellisen LivyMode ja virheellisen tai ylisuuren WorkspaceId, LakehouseId, ja IdempotencyKey arvot SQLSTATE-tilassa HY000. Ylisuurikokoinen yhteensopivuusarvo TenantPrincipal palauttaa HY000myös . Pelkästään SQLConnectDSN-tilassa ajuri kirjaa tavalliset HC-validointivirheet ja käyttää klassista tilaa. Ylisuuret turvallisuusherkät arvot epäonnistuvat silti yhteydessä.
• Arkaluonteiset tiedot: Kuljettaja sulkee pois tai IdempotencyKey puhdistaa ja muut arkaluontoiset kentät HC-lokeista ja diagnostiikkatuotoksista.
• Peruutus: Tiliotteen peruutus on yhteistyöhalua. Palvelintyö, joka on käynnissä, päättyy siististi sen sijaan, että lopetettaisiin välittömästi.
• Katkaisijat: HC- ja klassikkotilat käyttävät erillisiä katkaisijoita. Yhden tilan loppuun käyttäminen ei vaikuta toiseen.
• Alkuperäinen tietokanta: HC-yhteydet eivät suorita parametrin alkuperäistä USE lausetta Database . Suorita USE <database> yhdistämisen jälkeen tai käytä täysin päteviä taulukkonimiä.
• Diagnostiikka: Asetettu LogLevel=DEBUG kirjaamaan HC:n hankinta-, kysely-, julkaisu- ja virhekartoituspäätökset. Kohdennettua vianmääritystä varten aseta LIVY_HC_VERBOSE=1 lisätyt puhdistetut HC HTTP -diagnostiikat.

DSN-konfiguraatio

Linuxissa määritä tietolähteiden nimet (DSN) INI-tiedostoihin Windows-rekisterin sijaan.

Luo DSN

Jos ~/.odbc.ini sellainen on olemassa, lisää uusi DSN-osio korvaamatta olemassa olevaa tiedostoa. Kopioi asennettu mallipohja vain tiedoston luomisen yhteydessä:

if [ -e "$HOME/.odbc.ini" ]; then
    echo "Preserve ~/.odbc.ini and add the new DSN section manually."
else
    cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template "$HOME/.odbc.ini"
fi

Muokkaa ~/.odbc.ini Fabric-työtilan yksityiskohtia:

[FabricDSN]
Description    = Microsoft Fabric Data Engineering
Driver         = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId    = <workspace-id>
LakehouseId    = <lakehouse-id>
AuthFlow       = AZURE_CLI
LogLevel       = INFO
# LogFile      = /tmp/fabric_odbc.log
# LargeTableSupport = true
# ReuseSession = true

Varmista DSN

Listaa konfiguroidut DSN:t ja testaa sitten yhteys:

odbcinst -q -s
isql -k -v "DSN=FabricDSN;"

Komento isql vaatii unixODBC-komentorivityökalut. Vaihtoehto -k käyttää SQLDriverConnect, jonka avulla kuljettaja käsittelee DSN-yhteysattribuutteja.

Käytä DSN:ää sovelluksissa

conn = pyodbc.connect("DSN=FabricDSN")

using var connection = new OdbcConnection("DSN=FabricDSN");
await connection.OpenAsync();

SQLRETURN result = SQLConnect(
    hdbc,
    (SQLCHAR*)"FabricDSN",
    SQL_NTS,
    NULL,
    0,
    NULL,
    0);

Käyttöesimerkkejä

Testaa yhteyttä isql:llä

Aloita interaktiivinen SQL-istunto:

isql -k -v "DSN=FabricDSN;"

Suorita yksi kysely:

echo "SELECT 1 AS test" | isql -k -v "DSN=FabricDSN;" -b

Käytä -k Fabric DSN:ää, joten isql se yhdistyy läpi SQLDriverConnect eikä SQLConnect.

Työ suurilla tulosjoukoilla

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LargeTableSupport=true;"
    "PageSizeBytes=18874368;"
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT * FROM large_table")

row_count = 0
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break

    for row in rows:
        row_count += 1

    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

Tutustu skeemoihin ja taulukoihin

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SHOW TABLES")
for table in cursor.fetchall():
    print(table)

cursor.execute("DESCRIBE employees")
for column in cursor.fetchall():
    print(column)

cursor.execute("SHOW SCHEMAS")
for schema in cursor.fetchall():
    print(schema)

conn.close()

Tietotyyppien kartoittaminen

Ajuri kartoittaa Spark SQL -tietotyypit ODBC:n SQL-tyyppeihin:

Käyttöympäristön erot

Vianmääritys

Kuljettajaa ei löydy

Ongelma: Yhteys epäonnistuu .[IM002] Data source name not found and no default driver specified

Ratkaisut:

1. Varmista kuljettajan rekisteröinti ajamalla odbcinst -q -d.
2. Varmista, että sellainen /usr/lib/libmicrosoftfabricodbc.so on olemassa.
3. Rekisteröi ajuri ajamalla sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Asenna paketti uudelleen ajamalla sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Kuljettajaa ei löydetty tarball-asennuksen jälkeen

Ongelma: Ajuri on rekisteröity, mutta jaettua kirjastoa ei ole rekisteröidyllä polulla.

Ratkaisut:

1. Varmista, että sellainen /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so on olemassa.
2. Suorita uudelleen sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Jos käytit mukautettua etuliitettä, varmista, että rekisteröity ajurin polku käyttää samaa etuliitettä.

DSN:ää ei löydy

Ongelma: Yhteys epäonnistuu .[IM002] Data source name not found

Ratkaisut:

1. Varmista DSN-asetus ajamalla odbcinst -q -s.
2. Varmista, että ~/.odbc.ini se sisältää /etc/odbc.ini DSN-osion.
3. Varmista, että arvo Driver täsmälleen vastaa rekisteröityä kuljettajan nimeä.

Yhteyden epäonnistumiset

Ongelma: Ajuri ei pääse yhdistämään Fabric:iin.

Ratkaisut:

1. Varmista, että työtilan ID ja järvitalotunnus ovat kelvollisia GUID-kortteja.
2. Tarkista Azure CLI -autentikointi ajamalla az account show.
3. Varmista, että sinulla on tarvittavat Fabric-työtilaoikeudet.
4. Tarkista verkkoyhteys ja välityspalvelinasetukset.

Todennusvirheet

Ongelma: Azure CLI -todennus epäonnistuu.

Ratkaisut:

1. Juokse az login päivittääksesi tunnuksesi.
2. Aseta oikea tilaus ajamalla az account set --subscription <subscription-id>.
3. Tarkista token ajamalla az account get-access-token --resource https://api.fabric.microsoft.com.
4. Varmista, että tililläsi on vaaditut Fabric-työtilaoikeudet.

Jaetun kirjaston virheet

Ongelma: Kuljettaja raportoi error while loading shared libraries: libmicrosoftfabricodbc.so.

Ratkaisut:

1. Asenna paketti uudelleen ajamalla sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Varmista, että sellainen /usr/lib/libmicrosoftfabricodbc.so on olemassa.
3. Juokse sudo ldconfig päivitäksesi jaetun kirjaston välimuistin.

Kyselyn aikakatkaisut

Ongelma: Kyselyt aikakatkaistaan suurilla pöydillä.

Ratkaisut:

1. Lisää LargeTableSupport=true yhteysmerkkijono.
2. Säädä PageSizeBytes tuloksen kokoa.
3. Lisää EnableAsyncPrefetch=1 yhteysmerkkijono.
4. Käytä lauseketta LIMIT rajoittaaksesi tuloskokoa.

Lokituksen ottaminen käyttöön

Ota yksityiskohtainen lokiminen käyttöön DSN:ssä:

[FabricDSN]
LogLevel = DEBUG
LogFile  = /tmp/fabric_odbc_debug.log

Vaihtoehtoisesti lisää lokiparametrit yhteysmerkkijonoiin:

LogLevel=DEBUG;LogFile=/tmp/fabric_odbc_debug.log;

Ajuri tukee seuraavia lokitasoja:

• DEBUG: Sisältää yksityiskohtaista virheenkorjaustietoa ja on artikkelein ajurilokitaso.
• INFO: Sisältää yleistä tietoa ja on oletus.
• WARN: Sisältää vain varoitukset.
• ERROR: Sisältää vain virheitä.

Ota käyttöön unixODBC-jäljitys

Matalan tason ODBC-puheludiagnostiikassa lisää seuraava konfiguraatio :/etc/odbcinst.ini

[ODBC]
Trace     = yes
TraceFile = /tmp/odbc_trace.log

Poista jäljitys pois päältä, kun vianetsintä on valmis, jotta vältät tarpeettomia suorituskykyvaatimuksia.

Liittyvä sisältö

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