Microsoft ODBC-ajuri Microsoft Fabric Data Engineeringille Linuxissa (Preview)

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

Microsoft ODBC Driver for Microsoft Fabric Data Engineering versio 1.0.0 on saatavilla julkisessa esikatselussa.

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

Ajurin asentamiseen:

1. Poimi ms-sparksql-odbc-linux-1.0.0.zip.

2. Avaa terminaali puretusta hakemistosta.

3. Asenna Debian-paketti:

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

Paketti asentaa seuraavat tiedostot:

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

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

Määritysparametrit

Pakolliset parametrit

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

Valinnaiset parametrit

Yhteysasetukset

Esitysasetukset

Lokiasetukset

Välityspalvelimen asetukset

DSN-konfiguraatio

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

Luo DSN

Kopioi asennettu mallipohja:

cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template ~/.odbc.ini

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 -v FabricDSN

Komento isql vaatii unixODBC-komentorivityökalut.

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 -v FabricDSN

Suorita yksi kysely:

echo "SELECT 1 AS test" | isql -v FabricDSN -b

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-1.0.0-Linux.deb.

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

• TRACE: Sisältää kaikki API-kutsut.
• DEBUG: Sisältää yksityiskohtaista virheenkorjaustietoa.
• 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