ไดรเวอร์ Microsoft ODBC สําหรับ Microsoft Fabric Data Engineering บน Linux

ODBC (Open Database Connectivity) เป็นมาตรฐานที่นํามาใช้อย่างแพร่หลาย ซึ่งช่วยให้แอปพลิเคชันไคลเอ็นต์สามารถเชื่อมต่อและทํางานกับข้อมูลจากฐานข้อมูลและแพลตฟอร์มข้อมูลขนาดใหญ่ได้

Microsoft ODBC Driver for Fabric Data Engineering ช่วยให้คุณเชื่อมต่อ สืบค้น และจัดการงาน Spark ใน Fabric ด้วยความน่าเชื่อถือและความเรียบง่ายของมาตรฐาน ODBC ไดรเวอร์นี้สร้างขึ้นบน Fabric Livy APIs ซึ่งให้การเชื่อมต่อ Spark SQL ที่ปลอดภัยและยืดหยุ่นกับแอปพลิเคชัน C/C++, .NET, Python และแอปพลิเคชันที่รองรับ ODBC อื่น ๆ บน Linux

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

• เป็นไปตามมาตรฐาน ODBC 3.x: การใช้งานเต็มรูปแบบของข้อกําหนด ODBC 3.x
• การตรวจสอบสิทธิ์ Microsoft Entra ID: มีหลายขั้นตอนการตรวจสอบสิทธิ์ รวมถึง Azure CLI, ข้อมูลรับรองลูกค้า, การรับรองแบบใบรับรอง และการตรวจสอบสิทธิ์โทเค็นการเข้าถึง
• รองรับการสืบค้น Spark SQL: รันคําสั่ง Spark SQL โดยตรง
• รองรับชนิดข้อมูลอย่างครบถ้วน: รองรับชนิดข้อมูล SQL ของ Spark ทุกประเภท รวมถึงชนิดข้อมูลที่ซับซ้อน (ARRAY, MAP, และ STRUCT)
• การนําเซสชันกลับมาใช้ใหม่: มีการจัดการเซสชันในตัวเพื่อเพิ่มประสิทธิภาพ
• โหมดการทํางานพร้อมกันสูง: เลือกเข้าร่วมเซสชัน Livy ฝั่งเซิร์ฟเวอร์ที่แชร์และอบอุ่น เพื่อลดความหน่วงเวลาการเริ่มต้นเชื่อมต่อและการกระจายตัวของคลัสเตอร์ Spark
• รองรับตารางขนาดใหญ่: การจัดการที่เหมาะสมสําหรับชุดผลลัพธ์ขนาดใหญ่พร้อมขนาดหน้าที่ปรับแต่งได้
• Prefetch แบบไม่ซิงค์: โหลดข้อมูลเบื้องหลังเพื่อเพิ่มประสิทธิภาพ
• รองรับพร็อกซี: การกําหนดค่าพร็อกซี HTTP สําหรับสภาพแวดล้อมองค์กร
• รองรับบ้านพักริมทะเลสาบแบบหลายสคีมา: เชื่อมต่อกับสคีมาเฉพาะภายในบ้านพักริมทะเลสาบ

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

ก่อนที่คุณจะใช้ไดรเวอร์ Microsoft ODBC สําหรับ Microsoft Fabric Data Engineering บน Linux โปรดตรวจสอบให้แน่ใจว่าคุณมีข้อกําหนดเบื้องต้นดังต่อไปนี้:

• ระบบปฏิบัติการ: Ubuntu 22.04 หรือใหม่กว่า, Debian 11 หรือใหม่กว่า หรือ Red Hat Enterprise Linux (RHEL) 8 หรือใหม่กว่าบน x86-64
• unixODBC: โปรแกรมจัดการไดรเวอร์ ODBC สําหรับ Linux ติดตั้งunixodbcแพ็กเกจและunixodbc-dev
• libcurl: การพึ่งพา libcurl4 รันไทม์ HTTP เช่น แพ็กเกจที่เทียบเท่าสําหรับดิสทริบิวชันของคุณ
• OpenSSL: การพึ่งพา TLS และการเข้ารหัสในขณะรันไทม์ เช่น openssl แพ็กเกจและ หรือ libssl3 แพ็กเกจที่เทียบเท่า
• การเข้าถึง Fabric: การเข้าถึงพื้นที่ทํางาน Fabric
• ข้อมูลรับรอง Microsoft Entra IDV: ข้อมูลรับรองที่เหมาะสมสําหรับการตรวจสอบสิทธิ์
• รหัสพื้นที่ทํางานและบ้านพักริมทะเลสาบ: ตัวระบุ GUID สําหรับพื้นที่ทํางาน Fabric และบ้านพักริมทะเลสาบของคุณ
• Azure CLI (ไม่บังคับ): จําเป็นเมื่อใช้การตรวจสอบสิทธิ์ Azure CLI

ดาวน์โหลดและติดตั้งบน Linux

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

วิธีติดตั้งไดรเวอร์:

1. สกัด ms-sparksql-odbc-linux-2.0.0.tar.

2. เปิดเทอร์มินัลในไดเรกทอรีที่แตกออกมา

3. ติดตั้งแพ็กเกจ Debian:

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

แพ็กเกจนี้จะติดตั้งไฟล์ดังต่อไปนี้:

ติดตั้งแพ็กเกจ RPM

บน RHEL, Fedora หรือ CentOS ให้ติดตั้งแพ็กเกจ RPM จากคลังไดรเวอร์ที่แยกออกมา:

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

หรือใช้ rpm:

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

ตรวจสอบว่ารอบเครื่องยนต์ได้ลงทะเบียนไดรเวอร์แล้ว:

odbcinst -q -d | grep "Microsoft"

หากต้องการถอนการติดตั้งแพ็กเกจ RPM ให้รัน:

sudo dnf remove microsoft-fabric-odbc-driver

ติดตั้งทาร์บอล

สําหรับดิสทริบิวชันที่ไม่มีการรองรับแพ็กเกจ Debian หรือ RPM หรือสําหรับตําแหน่งติดตั้งที่กําหนดเอง ให้แตกแพ็กเกจและ .tar.gz รันสคริปต์ติดตั้ง:

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

สคริปต์ติดตั้งรองรับตัวเลือกเหล่านี้:

เพื่อยืนยันการติดตั้ง tarball เริ่มต้น ให้รัน:

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

หากต้องการถอนการติดตั้ง ให้รัน sudo ./install.sh --uninstall จากไดเรกทอรีแพ็กเกจที่แตกออกมา

ลงทะเบียนคนขับด้วยตนเอง

แพ็กเกจจะลงทะเบียนไดรเวอร์กับ unixODBC โดยอัตโนมัติ หากต้องการลงทะเบียนไดรเวอร์ด้วยตนเอง ให้รัน:

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

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

ตรวจสอบว่าไดรเวอร์ถูกลงทะเบียนและติดตั้งไลบรารีแล้ว:

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

คําสั่งควร odbcinst แสดงรายการ [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

ถอนการติดตั้งไดรเวอร์

หากต้องการถอนการติดตั้งไดรเวอร์ ให้รันคําสั่งต่อไปนี้:

sudo dpkg -r microsoft-fabric-odbc-driver

คําสั่งนี้จะลบไฟล์ไดรเวอร์และยกเลิกการลงทะเบียนไดรเวอร์จาก unixODBC

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

ตัวอย่างต่อไปนี้เชื่อมต่อกับ Fabric และรันคําสั่ง Spark SQL query ทําข้อกําหนดเบื้องต้นให้ครบและติดตั้งไดรเวอร์ก่อนที่คุณจะรันตัวอย่าง

ตัวอย่าง Python

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

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

สร้างและรันตัวอย่าง:

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

ตัวอย่าง .NET

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

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

สตริงการเชื่อมต่อพื้นฐาน

ใช้รูปแบบ สายอักขระการเชื่อมต่อ ดังนี้:

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

ส่วนประกอบสตริงการเชื่อมต่อ

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

การเชื่อมต่อพื้นฐาน

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

การเชื่อมต่อกับตัวเลือกประสิทธิภาพ

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

การเชื่อมโยงกับการบันทึกข้อมูล

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

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

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

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

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

Microsoft ODBC Driver for Microsoft Fabric Data Engineering รองรับวิธีการตรวจสอบสิทธิ์หลายแบบผ่าน Microsoft Entra ID กําหนดค่าการตรวจสอบสิทธิ์โดยใช้พารามิเตอร์ใน AuthFlow สายอักขระการเชื่อมต่อ หรือ DSN

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

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

ใช้การตรวจสอบสิทธิ์ Azure CLI สําหรับการพัฒนาและแอปพลิเคชันแบบโต้ตอบ

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)

ก่อนเชื่อมต่อ ให้ตรวจสอบว่า Azure CLI ถูกติดตั้งแล้วและลงชื่อเข้าใช้:

az --version
az login

ในการติดตั้ง Azure CLI บน Debian หรือ Ubuntu ให้ใช้ตัวจัดการแพ็กเกจ:

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

การตรวจสอบสิทธิ์ข้อมูลรับรองลูกค้า

ใช้การตรวจสอบสิทธิ์ลูกค้าสําหรับบริการอัตโนมัติและงานเบื้องหลัง

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

ระบุพารามิเตอร์ดังต่อไปนี้:

• TenantId: รหัสผู้เช่า Microsoft Entra
• ClientId: รหัสแอปพลิเคชัน (ไคลเอนต์)
• ClientSecret: ความลับของลูกค้า

เก็บความลับไว้ในที่เก็บข้อมูลลับที่ปลอดภัยหรือตัวแปรสภาพแวดล้อม อย่าเก็บความลับไว้ในสตริงการเชื่อมต่อแบบข้อความธรรมดาหรือไฟล์ INI

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

ใช้การตรวจสอบสิทธิ์แบบใช้ใบรับรองสําหรับแอปพลิเคชันองค์กรที่ต้องการข้อมูลรับรองใบรับรอง

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

ระบุพารามิเตอร์ดังต่อไปนี้:

• TenantId: รหัสผู้เช่า Microsoft Entra
• ClientId: รหัสแอปพลิเคชัน (ไคลเอนต์)
• CertificatePath: เส้นทางไปยังไฟล์ใบรับรอง PFX หรือ PKCS12
• CertificatePassword: รหัสผ่านใบรับรอง

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

ใช้การตรวจสอบสิทธิ์โทเค็นการเข้าถึงเมื่อแอปพลิเคชันของคุณได้รับโทเค็นผ่านกลไกอื่น

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

การตรวจสอบสิทธิ์โทเค็นไฟล์

ใช้การตรวจสอบสิทธิ์โทเค็นไฟล์ในสภาพแวดล้อมแบบคอนเทนเนอร์และ pipeline อัตโนมัติที่กระบวนการอื่นเขียนโทเค็นแบร์เลอร์ลงในไฟล์โทเค็นที่รู้จักดีของไดรเวอร์:

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

สําหรับนามแฝงคุณสมบัติข้ามไดรเวอร์ที่รองรับ ดูที่ นามแฝงคุณสมบัติข้ามไดรเวอร์

พารามิเตอร์การกําหนดค่า

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

รวมพารามิเตอร์เหล่านี้ในทุก สายอักขระการเชื่อมต่อ:

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

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

การตั้งค่าประสิทธิภาพ

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

การตั้งค่าพร็อกซี

การตั้งค่าความพร้อมกันสูง (HC)

ใช้พารามิเตอร์เหล่านี้เพื่อเปิดและกําหนดค่าโหมด high-concurrency (HC) โหมด HC คือโหมดเลือกเข้าร่วม หากคุณไม่ได้ตั้งค่า LivyMode หรือ UseHighConcurrency, ไดรเวอร์จะใช้เส้นทางเซสชันเดียวแบบคลาสสิก สําหรับคําแนะนําและตัวอย่าง ดูที่ โหมด High-concurrency (HC)

ลําดับความสําคัญของโหมดและการตรวจสอบความถูกต้อง

• LivyMode จะมีความสําคัญมากกว่า UseHighConcurrency เมื่อคุณตั้งค่าพารามิเตอร์ทั้งสอง
• ค่าพารามิเตอร์ไม่แยกตัวพิมพ์ใหญ่-เล็ก
• UseHighConcurrency รับ true, 1, yes, หรือ on เพื่อเปิดใช้งานโหมด HC มันยอมรับ false, 0, no, หรือ off เพื่อปิดใช้งานโหมด HC
• สําหรับค่าที่ไม่ว่างอื่น ๆ จะ SQLDriverConnect คืนค่าข้อผิดพลาด DSN เท่านั้น SQLConnect จะบันทึกความล้มเหลวในการตรวจสอบและใช้เส้นทางคลาสสิก

การตั้งค่าความเข้ากันได้

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

ตัวแปรสภาพแวดล้อมสํารอง

ไดรเวอร์จะใช้ตัวแปรสภาพแวดล้อมต่อไปนี้เฉพาะเมื่อไม่ได้ตั้งค่าพารามิเตอร์ DSN หรือการเชื่อมต่อที่เกี่ยวข้อง:

สําหรับ FABRIC_ODBC_USE_HC, การเปิดใช้งานเฉพาะสภาพแวดล้อมจะ trueรับรู้ , 1, หรือ yes (ไม่สนใจตัวพิมพ์ใหญ่-เล็ก) ค่าอื่น ๆ จะปิดโหมด HC onนามแฝง และ off จะใช้ได้เฉพาะกับค่า DSN และ connection-string เท่านั้น

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

โหมด High-concurrency (HC) ช่วยให้การเชื่อมต่อ ODBC ไปยังพื้นที่ทํางานเดียวกันและ lakehouse เชื่อมต่อกับเซสชัน Livy Spark ฝั่งเซิร์ฟเวอร์ที่แชร์และอบอุ่น แทนที่จะต้องจัดคลัสเตอร์แยกสําหรับแต่ละการเชื่อมต่อ ใช้สําหรับงาน เช่น แดชบอร์ด BI, เคอร์เนลโน้ตบุ๊ก และ ETL fan-out ที่เปิดการเชื่อมต่อระยะสั้นจํานวนมากและสามารถแชร์ความจุ Spark ที่จัดการโดยเซิร์ฟเวอร์ได้

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

เลือกโหมดการเชื่อมต่อ

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

• ภาระงานของคุณจะเปิดการเชื่อมต่อ ODBC ที่มีอายุสั้นหลายรายการ เช่น แดชบอร์ด BI, เคอร์เนลโน้ตบุ๊ก หรือการออก ETL
• การเชื่อมต่อจะมุ่งเป้าไปที่พื้นที่ทํางานเดียวกันและบ้านริมทะเลสาบเดียวกัน และสามารถแชร์เซสชัน Spark ที่จัดการโดยเซิร์ฟเวอร์ได้
• การลดความหน่วงเวลาการเริ่มต้นแบบเย็นต่อการเชื่อมต่อเป็นสิ่งสําคัญ

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

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

เปิดใช้งานโหมดการทํางานพร้อมกันสูง

เพิ่มพารามิเตอร์โหมด high-concurrency ลงใน DSN หรือ สายอักขระการเชื่อมต่อ

แนะนํา: ชุด LivyMode

ใช้เพื่อ LivyMode เลือกโหมดการรับเซสชันอย่างชัดเจน:

LivyMode=HighConcurrency

ค่าที่รองรับคือ Classic, HighConcurrencyและAuto ค่าต่าง ๆ ไม่สนใจตัวพิมพ์ใหญ่-เล็ก Auto ขณะนี้เลือกโหมดคลาสสิก

ทางเลือก: Set UseHighConcurrency

ใช้การตั้งค่าบูลีนเพื่อความเข้ากันได้กับการกําหนดค่าที่มีอยู่:

UseHighConcurrency=true

เพื่อเปิดใช้งานโหมดการทํางานพร้อมกันสูง ให้ใช้ true, 1, yes, หรือ on. หากต้องการปิดใช้งาน ให้ใช้ false, 0, , noหรือ off. ค่าต่าง ๆ ไม่สนใจตัวพิมพ์ใหญ่-เล็ก SQLDriverConnectปฏิเสธค่าที่ไม่ว่างอื่น ๆ ด้วย SQLSTATE HY024 ใช้เพียง DSN SQLConnect บันทึกความล้มเหลวในการตรวจสอบและใช้โหมดคลาสสิก

คุณยังสามารถเปิดใช้งานโหมดการทํางานพร้อมกันสูงสําหรับเชลล์ปัจจุบันโดยใช้ตัวแปรสภาพแวดล้อม:

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

พารามิเตอร์ที่จําเป็นในโหมด HC

การเปิดใช้งาน HC ต้องใช้ตัวระบุที่ถูกต้องดังต่อไปนี้:

รวม SessionTag เพราะมีผลต่อการจับคู่ฝั่งเซิร์ฟเวอร์สําหรับเซสชันที่ร้อน

การจับคู่เซสชัน

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

• คุณค่าSessionTag
• การกําหนดค่าประกายไฟที่มีประสิทธิภาพ รวมถึงconf.*การตั้งค่าและEnvironmentId

บริการ Fabric Livy จะประเมินค่าเหล่านี้และตัดสินใจว่าจะเชื่อมต่อกับเซสชันอุ่นหรือสร้างเซสชันใหม่ เพื่อปรับปรุงการนําเซสชันกลับมาใช้ใหม่ ให้ใช้ค่าที่สอดคล้องกันระหว่างการเชื่อมต่อที่มีวัตถุประสงค์เพื่อแบ่งปันความจุ Spark ที่จัดการโดยเซิร์ฟเวอร์

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

การเชื่อมต่อ HC ขั้นต่ํากับการตรวจสอบสิทธิ์ Azure CLI:

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

การเชื่อมต่อ HC พร้อมเวลาหมดที่ปรับจูน:

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 กับสภาพแวดล้อมและการตั้งค่า Spark จะยกเลิก:

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 กับ 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 ใน Linux DSN

แทนที่จะซ้ําการตั้งค่า HC ในแต่ละ สายอักขระการเชื่อมต่อ ให้เก็บไว้~/.odbc.iniสําหรับ DSN เฉพาะผู้ใช้หรือ /etc/odbc.ini DSN ทั่วทั้งระบบ

[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

หลังจากบันทึก DSN แล้ว ให้ตรวจสอบและทดสอบการเชื่อมต่อ

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

เมื่อ สายอักขระการเชื่อมต่อ ไม่ได้ระบุค่า ไดรเวอร์จะอ่านการตั้งค่าเหล่านี้จาก DSN:

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

ไดรเวอร์ยังอ่านเฉพาะ TenantPrincipal ความเข้ากันได้และ PoolMax การตั้งค่าต่าง ๆ ด้วย ใช้ชื่อพารามิเตอร์ในตารางการตั้งค่า HC

ปิดโหมด HC

คุณสามารถปิดการรับเซสชัน HC ใหม่ได้โดยไม่ต้องปรับใช้ไดรเวอร์ใหม่ ใช้วิธีการที่สอดคล้องกับวิธีที่คุณเปิดใช้งานโหมด HC:

การตั้งค่า connection-string และ DSN มีความสําคัญเหนือ fallback ของตัวแปรสภาพแวดล้อม การเปลี่ยนแปลงเหล่านี้มีผลเฉพาะกับการเชื่อมต่อใหม่เท่านั้น เซสชัน HC ที่มีอยู่จะดําเนินต่อไปจนกว่าจะปล่อยออกมา

เข้าใจพฤติกรรมรันไทม์ของ HC

• การตรวจสอบความถูกต้อง:SQLDriverConnectปฏิเสธค่าบูลีน HC และค่าจํานวนเต็มบวกที่ไม่ถูกต้องด้วย SQLSTATE HY024 มันปฏิเสธค่าที่ไม่ถูกต้องLivyModeและผิดปกติ หรือมีขนาดใหญ่WorkspaceIdLakehouseIdเกิน , และIdempotencyKeyค่าที่มี SQLSTATE HY000 ค่าความเข้ากันได้TenantPrincipalที่ใหญ่เกินก็จะคืนค่าHY000 สําหรับ DSN เท่านั้น SQLConnectไดรเวอร์จะบันทึกความล้มเหลวในการตรวจสอบ HC ปกติและใช้โหมดคลาสสิก ค่าที่มีความสําคัญต่อความปลอดภัยที่ใหญ่เกินก็ยังล้มเหลวในการเชื่อมต่อ
• ข้อมูลที่ละเอียดอ่อน: ไดรเวอร์จะยกเว้นหรือลบ IdempotencyKey ข้อมูลและฟิลด์ที่ละเอียดอ่อนอื่น ๆ ออกจากบันทึก HC และผลลัพธ์การวินิจฉัย
• การยกเลิก: การยกเลิกใบแจ้งยอดเป็นแบบร่วมมือ งานเซิร์ฟเวอร์ที่กําลังดําเนินอยู่จะจบลงอย่างราบรื่นแทนที่จะถูกยกเลิกทันที
• เบรกเกอร์วงจร: โหมด HC และ Classic ใช้เบรกเกอร์วงจรแยกกัน การใช้โหมดหนึ่งจนหมดจะไม่ส่งผลกระทบต่ออีกโหมดหนึ่ง
• ฐานข้อมูลเริ่มต้น: การเชื่อมต่อ HC จะไม่รันคําสั่งเริ่มต้น USE สําหรับ Database พารามิเตอร์ เรียกใช้ USE <database> หลังจากเชื่อมต่อหรือใช้ชื่อตารางที่มีคุณสมบัติครบถ้วน
• การวินิจฉัย: ตั้งค่า LogLevel=DEBUG ให้บันทึกการได้มาซึ่ง HC, การสํารวจ, การปล่อย และการตัดสินใจทําแผนที่ข้อผิดพลาด สําหรับการแก้ไขปัญหาเฉพาะจุด ให้ตั้งค่า LIVY_HC_VERBOSE=1 ให้รวมการวินิจฉัย HC HTTP ที่ถูกลบเพิ่มเติม

การกําหนดค่า DSN

บน Linux ให้กําหนดค่าชื่อแหล่งข้อมูล (DSNs) ในไฟล์ INI แทนรีจิสทรีของ Windows

สร้าง DSN

หากมี ~/.odbc.ini อยู่ ให้เพิ่มส่วน DSN ใหม่โดยไม่แทนที่ไฟล์เดิม คัดลอกเทมเพลตที่ติดตั้งไว้เฉพาะเมื่อคุณสร้างไฟล์เท่านั้น:

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

แก้ไข~/.odbc.iniด้วยรายละเอียดพื้นที่ทํางาน Fabric ของคุณ:

[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

ตรวจสอบ DSN

แสดงรายการ DSN ที่กําหนดค่าไว้ แล้วทดสอบการเชื่อมต่อ:

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

คําสั่งนี้ isql ต้องใช้เครื่องมือบรรทัดคําสั่ง unixODBC ตัวเลือกนี้ -k ใช้ SQLDriverConnect, ซึ่งช่วยให้ไดรเวอร์ประมวลผลคุณสมบัติการเชื่อมต่อ DSN

ใช้ DSN ในแอปพลิเคชัน

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

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

ทดสอบการเชื่อมต่อด้วย isql

เริ่มเซสชัน SQL แบบโต้ตอบ:

isql -k -v "DSN=FabricDSN;"

รันคําสั่งค้นหาเพียงครั้งเดียว:

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

ใช้-kสําหรับ Fabric DSN ดังนั้นisqlจะเชื่อมต่อผ่านแทนที่SQLDriverConnectจะเป็น SQLConnect.

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

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

ค้นพบสคีมาและตาราง

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

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

โปรแกรมควบคุมแมปชนิดข้อมูล Spark SQL กับชนิด ODBC SQL:

ความแตกต่างของแพลตฟอร์ม

การแก้ไขปัญหา

ไม่พบไดรเวอร์

ปัญหา: การเชื่อมต่อล้มเหลวเมื่อ [IM002] Data source name not found and no default driver specified.

โซลูชัน:

1. ตรวจสอบการลงทะเบียนผู้ขับขี่โดยรัน odbcinst -q -d.
2. ตรวจสอบว่ามีอยู่ /usr/lib/libmicrosoftfabricodbc.so จริง
3. ลงทะเบียนไดรเวอร์โดยรัน sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. ติดตั้งแพ็กเกจใหม่โดยรัน sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

ไม่พบไดรเวอร์หลังจากติดตั้ง tarball

ปัญหา: ไดรเวอร์ลงทะเบียนแล้ว แต่ไลบรารีที่ใช้ร่วมกันไม่ปรากฏในเส้นทางที่ลงทะเบียนไว้

โซลูชัน:

1. ตรวจสอบว่ามีอยู่ /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so จริง
2. รีรันsudo ./install.sh --prefix=/opt/microsoft/fabricodbc
3. หากคุณใช้คํานําหน้าแบบกําหนดเอง ให้ตรวจสอบว่าเส้นทางไดรเวอร์ที่ลงทะเบียนใช้คํานําหน้าเดียวกัน

ไม่พบ DSN

ปัญหา: การเชื่อมต่อล้มเหลวเมื่อ [IM002] Data source name not found.

โซลูชัน:

1. ตรวจสอบการกําหนดค่า DSN โดยรัน odbcinst -q -s.
2. ตรวจสอบว่า ~/.odbc.ini หรือ /etc/odbc.ini มีส่วน DSN อยู่
3. ตรวจสอบให้แน่ใจว่าค่าตรงกับ Driver ชื่อผู้ขับขี่ที่ลงทะเบียนไว้อย่างแม่นยํา

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

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

โซลูชัน:

1. ตรวจสอบว่า Workspace ID และ Lakehouse ID เป็น GUID ที่ถูกต้อง
2. ตรวจสอบการตรวจสอบสิทธิ์ Azure CLI โดยรัน az account show.
3. ตรวจสอบให้แน่ใจว่าคุณมีสิทธิ์ Fabric workspace ที่จําเป็น
4. ตรวจสอบการเชื่อมต่อเครือข่ายและการตั้งค่าพร็อกซี

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

ปัญหา: การตรวจสอบสิทธิ์ Azure CLI ล้มเหลว

โซลูชัน:

1. รีเฟ az login รชข้อมูลรับรองของคุณ
2. ตั้งค่าการสมัครสมาชิกที่ถูกต้องโดยการรัน az account set --subscription <subscription-id>.
3. ตรวจสอบโทเค็นโดยการรัน az account get-access-token --resource https://api.fabric.microsoft.com.
4. ตรวจสอบให้แน่ใจว่าบัญชีของคุณมีสิทธิ์ Fabric workspace ที่จําเป็น

ข้อผิดพลาดไลบรารีที่ใช้ร่วมกัน

ปัญหา: ไดรเวอร์รายงานerror while loading shared libraries: libmicrosoftfabricodbc.so .

โซลูชัน:

1. ติดตั้งแพ็กเกจใหม่โดยรัน sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. ตรวจสอบว่ามีอยู่ /usr/lib/libmicrosoftfabricodbc.so จริง
3. รัน sudo ldconfig เพื่อรีเฟรชแคชไลบรารีที่ใช้ร่วมกัน

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

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

โซลูชัน:

1. เพิ่มLargeTableSupport=trueเข้าไปใน สายอักขระการเชื่อมต่อ
2. ปรับ PageSizeBytes ขนาดผลลัพธ์
3. เพิ่มEnableAsyncPrefetch=1เข้าไปใน สายอักขระการเชื่อมต่อ
4. ใช้ LIMIT คําสั่งเพื่อจํากัดขนาดผลลัพธ์

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

เปิดใช้งานการบันทึกรายละเอียดใน DSN:

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

อีกทางเลือกหนึ่ง เพิ่มพารามิเตอร์การบันทึกลงใน สายอักขระการเชื่อมต่อ:

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

ไดรเวอร์รองรับระดับบันทึกดังต่อไปนี้:

• DEBUG: รวมข้อมูลการดีบักอย่างละเอียดและเป็นระดับบันทึกไดรเวอร์ที่ละเอียดที่สุด
• INFO: รวมข้อมูลทั่วไปและเป็นค่าเริ่มต้น
• WARN: รวมเฉพาะคําเตือนเท่านั้น
• ERROR: รวมเฉพาะข้อผิดพลาดเท่านั้น

เปิดใช้งานการติดตาม unixODBC

สําหรับการวินิจฉัยการเรียก ODBC ระดับต่ํา ให้เพิ่มการกําหนดค่าต่อไปนี้ใน /etc/odbcinst.ini:

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

ปิดการติดตามเมื่อคุณแก้ไขปัญหาเสร็จเพื่อหลีกเลี่ยงภาระงานที่ไม่จําเป็น

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

• โปรแกรมควบคุม Microsoft ODBC สําหรับวิศวกรรมข้อมูล Microsoft Fabric
• รันไทม์ Apache Spark ใน Fabric
• รันไทม์ของผ้า 1.3
• Livy API สําหรับวิศวกรรมข้อมูลคืออะไร
• โปรแกรมควบคุม Microsoft JDBC สําหรับวิศวกรรมข้อมูล Microsoft Fabric
• ยูนิกซ์ ODBC