Microsoft ODBC 驅動程式用於 Microsoft Fabric 資料工程

ODBC（開放資料庫連接性）是一項廣泛採用的標準，使客戶端應用程式能夠連接並操作來自資料庫及大數據平台的資料。

Microsoft ODBC Driver for Fabric Data Engineering 讓你能以 ODBC 標準的可靠性與簡便性，在 Fabric 中連接、查詢並管理 Spark 工作負載。 該驅動程式建立在 Fabric 的 Livy API 之上，為你的 C/C++、.NET、Python 及其他 ODBC 相容應用程式和商業智慧工具提供安全且靈活的 Spark SQL 連接。

關鍵功能

• 符合 ODBC 3.x 規範：完整實作 ODBC 3.x 規範
• Microsoft Entra ID 認證：多重認證流程，包括Azure CLI、互動式、用戶端憑證、憑證式及存取權杖認證
• Spark SQL 查詢支援：直接執行 Spark SQL 語句
• 完整的資料型態支援：支援所有 Spark SQL 資料型態，包括複雜型別（ARRAY、MAP、STRUCT）
• 會話重用：內建會話管理以提升效能
• 高並行模式：選擇使用共用且預熱的伺服器端 Livy 工作階段，以降低連線啟動延遲及 Spark 叢集擴張
• 大型資料表支援：針對可配置頁面大小的大型結果集優化處理
• 非同步預取：背景資料載入以提升效能
• 代理支援：企業環境的 HTTP 代理設定
• 多結構湖屋支援：連接湖屋內的特定結構
• OneLake 整合：透過統一的 ODBC 介面存取儲存在 OneLake 中的湖屋資料，包括跨多個結構的表格，無需單獨的儲存配置
• Environment 項目支援：在工作執行時附加Fabric環境項目，以將工作區函式庫、Spark屬性和變數套用到每個會話中
• Custom Spark configuration：直接將 Spark 設定屬性傳送至 連接字串 以調整會話行為

先決條件

在使用 Microsoft Fabric Data Engineering 的 Microsoft ODBC 驅動程式前，請確保您具備：

• 作業系統：Windows 10/11 或 Windows Server 2016+
• Fabric 存取權：存取 Fabric 工作區
• Microsoft Entra ID 憑證：適合的憑證用於認證
• 工作區與湖屋 ID：用於 Fabric 工作區與湖屋的 GUID 識別碼
• Azure CLI （可選）：需要用於 Azure CLI 認證方法

下載與安裝 MSI

• 下載 Microsoft Fabric Data Engineering 的 Microsoft ODBC 驅動程式（zip）

1. 下載 Microsoft ODBC 驅動程式用於 Microsoft Fabric Data Engineering 的 MSI 套件
2. 按兩下 MicrosoftFabricODBCDriver-2.0.msi。
3. 請依照安裝精靈操作並接受授權協議
4. 選擇安裝目錄（預設： C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\）
5. 完成安裝

靜默安裝

# Silent installation
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /l*v install.log

確認安裝

安裝後，請確認驅動程式已註冊：

1. 執行 odbcad32.exe （ODBC 資料來源管理員）
2. 前往 驅動程式 標籤頁
3. 請確認「Microsoft ODBC 驅動程式用於 Microsoft Fabric 資料工程」是否已列出。

快速入門範例

此範例示範如何連接 Fabric 並使用 Microsoft ODBC 驅動程式執行查詢，用於 Microsoft Fabric 資料工程。 執行此程式碼前，請確保你已完成前置條件並安裝驅動程式。

C/C++ 範例

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

int main() {
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);
    SQLSetEnvAttr(
        environment,
        SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3,
        0);
    SQLAllocHandle(SQL_HANDLE_DBC, environment, &connection);

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

    SQLRETURN result = SQLDriverConnectA(
        connection,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);
        result = SQLExecDirectA(
            statement,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

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

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

        SQLFreeHandle(SQL_HANDLE_STMT, statement);
        SQLDisconnect(connection);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, connection);
    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Python 範例

import pyodbc

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

# Connect and execute query
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()

.NET 範例

using System.Data.Odbc;

// Connection string with required parameters
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));
}

連接字串格式

基本連接字串

Microsoft Fabric Data Engineering 的 Microsoft ODBC 驅動程式使用以下連接字串格式：

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

連接串組成部分

範例連接字串

基本連線（Azure CLI 認證）

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=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）模式 章節。

Authentication

Microsoft Fabric Data Engineering 的 Microsoft ODBC 驅動程式支援透過 Microsoft Entra ID（前稱 Azure Active Directory）進行多種認證方法。 認證是透過 AuthFlow 連接字串中的參數來設定的。

驗證方法

你可以用大寫的蛇形、帕斯卡爾大小寫或數字形式來指定認證值。 驅動程式也接受短別名，如 Browser、 Interactive、 FileCLICertificateToken。 驅動程式在比較數值時會忽略底線。

Azure CLI 驗證

最佳用途：開發與互動應用

# Python Example
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)

Prerequisites:

• Azure CLI 安裝： az --version
• 登入： az login

互動式瀏覽器驗證

最佳應用：面向使用者的應用程式

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

行為：

• 開啟瀏覽器視窗以進行使用者驗證
• 憑證會被快取以供後續連線使用

用戶端憑證（服務主體）認證

最佳用途：自動化服務與背景工作

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： Azure tenant ID
• ClientId：來自 Microsoft Entra ID 的應用程式（用戶端）ID
• ClientSecret：Microsoft Entra ID 的用戶端密碼

最佳作法

• 安全儲存秘密（Azure Key Vault， environment variables）
• 盡可能使用受管理身份
• 要定期輪換密鑰

憑證式驗證

最佳應用：需要憑證式認證的企業應用

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=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

所需參數：

• TenantId： Azure tenant ID
• ClientId： 應用程式（用戶端）ID
• CertificatePath： 前往 PFX/PKCS12 憑證檔案的路徑
• CertificatePassword： 證書密碼

存取令牌驗證

最佳用途：自訂認證場景

# Acquire token through custom mechanism
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};"
)

檔案權杖驗證

在容器化環境及自動化管線中使用檔案令牌認證，當另一個程序寫入驅動程式已知的令牌檔時：

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

驅動程式在 Windows 和 Linux 上解析令牌檔案的位置。

跨驅動程式屬性別名

ODBC 驅動程式除了接受原生 ODBC 名稱外，還接受選定的 ADO.NET 和 JDBC 屬性名稱。 這種支援能減少在 Fabric 驅動程式間切換時的連線串變更。

驅動程式在建立連線時會解析 17 個跨驅動程式別名。

組態參數

必要參數

這些參數必須存在於每個連接字串中：

選擇性參數

連線設定

效能設定

記錄設定

代理伺服器設定

高並行（HC）設定

利用這些參數啟用並設定高並行（HC）模式。 HC 模式需主動啟用。 如果你沒有設定 LivyMode 或 UseHighConcurrency，驅動程式會使用經典的單會話路徑。 有關指引與範例，請參見 高並發（HC）模式。

模式優先順序與驗證

• 當你同時設定這兩個參數時，LivyMode 的優先順序高於 UseHighConcurrency
• 參數值不區分大小寫。
• UseHighConcurrency 接受 true、 1、 yes或 on 以啟用 HC 模式。 它接受 false、0、no 或 off 以停用 HC 模式。
• 若為其他非空值，SQLDriverConnect 會回傳錯誤。 僅 SQLConnect DSN 會記錄驗證失敗，並使用經典路徑。

相容性設定

驅動程式接受 TenantPrincipal 和 PoolMax，以及它們對應的環境變數後備值，以便與較早期的 HC 組態相容。 驅動程式會解析並驗證這些值，但它們不會影響 HC 會話匹配或執行時池容量。 不要依賴它們來實現租戶隔離或連線限制。

環境變數備援

當對應的 DSN 或連接字串參數未設定時，驅動程式才會使用以下環境變數：

對於 FABRIC_ODBC_USE_HC，僅限環境的啟用會將 true、1 或 yes 識別為有效值（不區分大小寫）。 其他值會使 HC 維持停用狀態。 on與off別名僅適用於 DSN 與 connection-string 值。

環境設定

你可以將 Fabric 環境項目附加到驅動程式啟動的 Spark 會話中。 所選環境的函式庫、Spark 屬性和變數會在建立會話時自動套用。

帶有環境項目的範例連接字串：

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

自訂 Spark 配置

你可以直接在 連接字串 中傳遞 Spark 設定屬性。 任何以 為 spark. 前綴的參數會在建立時自動套用到 Spark 會話，讓你能覆蓋工作區或執行時的預設值。

火花配置範例：

spark.sql.shuffle.partitions=200
spark.sql.adaptive.enabled=true
spark.sql.autoBroadcastJoinThreshold=10485760

範例連接字串，包含自訂的 Spark 屬性：

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;spark.sql.shuffle.partitions=200;spark.sql.adaptive.enabled=true

高並行（HC）模式

高並行（HC）模式允許同一工作空間與湖屋的 ODBC 連線連接到共享的暖伺服器端 Livy Spark 會話，而不必為每個連線配置獨立叢集。 適用於 BI 儀表板、筆記本核心程序和 ETL 扇出等工作負載；這些工作負載會開啟大量短生命週期的連線，並可共用由伺服器管理的 Spark 容量。

HC 模式需主動啟用。 如果你沒有設定 HC 設定，驅動程式會使用經典的單會話路徑。

選擇連線模式

以下情況下使用 HC 模式：

• 你的工作負載會開啟許多短暫的 ODBC 連線，例如 BI 儀表板、筆記本核心或 ETL 輸出。
• 連線針對相同的工作空間和湖庫，並可共用由伺服器管理的 Spark 會話。
• 降低每連線的冷啟動延遲非常重要。

當以下情況使用經典模式：

• 每個連線都需要一個隔離的 Spark 會話，因為 Spark 配置不同或資源嚴格隔離。
• 目標工作空間和湖屋的 Fabric Livy 端點不支援 HC 模式。

啟用高並行模式

在 DSN 或 連接字串 中加入一個高並行模式參數。

建議：設定 LivyMode

請明確選擇 LivyMode 會話擷取模式：

LivyMode=HighConcurrency

支援值為 Classic、 HighConcurrency、 Auto和 。 值不區分大小寫。 Auto 目前選擇經典模式。

替代方案：Set UseHighConcurrency

請使用布林設定來與現有配置相容：

UseHighConcurrency=true

要啟用高並行模式，請使用 true、 1、 yes或 on。 要停用它，請使用 false、 0、 no或 off。 值不區分大小寫。 SQLDriverConnect 會以 SQLSTATE HY024 拒絕其他非空值。 僅 SQLConnect DSN 會記錄驗證失敗並使用經典模式。

HC 模式下的必要參數

啟用 HC 需要以下有效識別碼：

加入 SessionTag，因為它會影響預熱工作階段的伺服器端比對。

會話匹配

HC 模式並不保證每個連線都會重複使用現有的會話。 對於每個會話擷取請求，驅動程式會發送：

• SessionTag 值。
• 有效的 Spark 配置，包括 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

具有環境與 Spark 設定覆寫的 HC：

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

在 DSN 中設定 HC 模式

你可以把 HC 設定存進 DSN，而不是在每個 連接字串 裡重複。 當 連接字串 未指定值時，驅動程式會從 DSN 讀取以下設定：

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

驅動程式也會讀取僅供相容性使用的 TenantPrincipal 和 PoolMax 設定。 若要儲存這些設定，請編輯 odbcad32.exe 中的 DSN，或使用 SQLWritePrivateProfileString。 請使用 HC設定表中的參數名稱。

關閉 HC 模式

你可以停用新的 HC 會話擷取，而不必重新部署驅動程式。 使用與你啟用 HC 模式相符的方法：

連線字串與 DSN 設定優先於環境變數的備援。 這些變更只影響新連線。 現有的 HC 課程會持續進行，直到釋出為止。

了解 HC 執行時的行為

• 驗證：SQLDriverConnect 拒絕無效的 HC 布林值及正整數值，使用 SQLSTATE HY024。 它會以 SQLSTATE HY000 拒絕無效的 LivyMode，以及無效或過大的 IdempotencyKey、WorkspaceId 和 LakehouseId 值。 過大的相容性值 TenantPrincipal 也會回傳 HY000。 對於僅限 DSN 的情況 SQLConnect，驅動程式會記錄一般 HC 驗證失敗，並使用傳統模式。 過大的安全性敏感值仍會導致連線失敗。
• 敏感資料： 驅動程式會從 HC 記錄和診斷輸出中排除或遮罩 IdempotencyKey 及其他敏感欄位。
• 取消： 陳述式取消是協作式的。 伺服器正在進行的工作會乾淨利落地結束，而非立即終止。
• 斷路器： HC 模式與經典模式使用不同的斷路器。 用盡其中一種模式不會影響另一種模式。
• 初始資料庫：HC 連線不會針對 USE 參數執行初始的 Database 陳述式。 連線後執行 USE <database>，或使用完全限定資料表名稱。
• 診斷：將 LogLevel=DEBUG 設定為記錄 HC 的取得、輪詢、釋放及錯誤對應決策。 若要進行針對性的疑難排解，請將 LIVY_HC_VERBOSE=1 設定為包含額外的、已去除敏感資訊的 HC HTTP 診斷資訊。

設定 DSN

建立系統DSN

1. 開放 ODBC 管理員

   %SystemRoot%\System32\odbcad32.exe
   

2. 建立新系統 DSN

   • 前往「系統DSN」分頁
   • 選擇 [新增]
   • 選擇「Microsoft ODBC 驅動程式用於 Microsoft Fabric 資料工程」
   • 選擇「完成」

3. 設定 DSN 設定

   • 資料來源名稱：輸入唯一名稱（例如， FabricODBC）
   • 描述：可選描述
   • 工作區 ID：您的 Fabric 工作空間 GUID
   • Lakehouse ID：您的 Fabric Lakehouse GUID
   • 認證：選擇認證方法
   • 環境 ID（可選）：在建立會話時輸入要附加至 Fabric 環境項目的 GUID。
   • Livy 模式 （選用）：設定為 HighConcurrency 啟用 HC 模式
   • 會話標籤 （可選）：輸入非敏感操作標籤以匹配 HC 會話
   • 根據需要設定更多設定

4. 測試連接

   • 選擇「測試連線」以驗證設定
   • 選擇「確定」以儲存

在應用中使用 DSN

# Python - Connect using DSN
conn = pyodbc.connect("DSN=FabricODBC")

// .NET - Connect using DSN
using var connection = new OdbcConnection("DSN=FabricODBC");
await connection.OpenAsync();

使用範例

基本連接與查詢

Python

import pyodbc

def main():
    connection_string = (
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;"
        "ReuseSession=true;"
    )
    
    conn = pyodbc.connect(connection_string, timeout=30)
    cursor = conn.cursor()
    
    print("Connected successfully!")
    
    # Show available tables
    print("\nAvailable tables:")
    cursor.execute("SHOW TABLES")
    for row in cursor.fetchall():
        print(f"  {row}")
    
    # Query data
    print("\nQuery results:")
    cursor.execute("SELECT * FROM employees LIMIT 10")
    
    # Print column names
    columns = [desc[0] for desc in cursor.description]
    print(f"Columns: {columns}")
    
    # Print rows
    for row in cursor.fetchall():
        print(row)
    
    conn.close()

if __name__ == "__main__":
    main()

.NET

using System.Data.Odbc;

class Program
{
    static async Task Main(string[] args)
    {
        string connectionString = 
            "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
            "WorkspaceId=<workspace-id>;" +
            "LakehouseId=<lakehouse-id>;" +
            "AuthFlow=AZURE_CLI;" +
            "ReuseSession=true;";

        using var connection = new OdbcConnection(connectionString);
        await connection.OpenAsync();
        
        Console.WriteLine("Connected successfully!");

        // Show available tables
        Console.WriteLine("\nAvailable tables:");
        using (var cmd = new OdbcCommand("SHOW TABLES", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine($"  {reader.GetString(0)}");
            }
        }

        // Query data
        Console.WriteLine("\nQuery results:");
        using (var cmd = new OdbcCommand("SELECT * FROM employees LIMIT 10", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            // Print column names
            var columns = new List<string>();
            for (int i = 0; i < reader.FieldCount; i++)
            {
                columns.Add(reader.GetName(i));
            }
            Console.WriteLine($"Columns: {string.Join(", ", columns)}");

            // Print rows
            while (await reader.ReadAsync())
            {
                var values = new object[reader.FieldCount];
                reader.GetValues(values);
                Console.WriteLine(string.Join("\t", values));
            }
        }
    }
}

處理大型結果集

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;"  # 18 MB pages
    "EnableAsyncPrefetch=1;"
)

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

# Execute large query
cursor.execute("SELECT * FROM large_table")

# Process in batches
row_count = 0
while True:
    rows = cursor.fetchmany(1000)  # Fetch 1000 rows at a time
    if not rows:
        break
    
    for row in rows:
        # Process row
        row_count += 1
        
    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

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

執行 DML 陳述式

bool executeDml(SQLHDBC connection, const char* sql, const char* description) {
    SQLHSTMT statement = SQL_NULL_HSTMT;
    SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);

    std::cout << "Executing: " << description << std::endl;
    SQLRETURN result = SQLExecDirectA(
        statement,
        (SQLCHAR*)sql,
        SQL_NTS);

    bool succeeded = SQL_SUCCEEDED(result);
    if (succeeded) {
        SQLLEN rowCount;
        SQLRowCount(statement, &rowCount);
        std::cout << "Rows affected: " << rowCount << std::endl;
    }

    SQLFreeHandle(SQL_HANDLE_STMT, statement);
    return succeeded;
}

將 executeDml 與 INSERT、UPDATE 或 DELETE 陳述式一起使用。 報告的列數取決於結果是否包含驅動程式識別的更新次數。

模式探索

import pyodbc

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

# List all tables
print("Tables in current default schema / database:")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
for table in tables:
    print(f"  {table}")

# Describe table structure
print("\nTable structure for 'employees':")
cursor.execute("DESCRIBE employees")
for col in cursor.fetchall():
    print(f"  {col}")

# List schemas (for multi-schema Lakehouses)
print("\nAvailable schemas:")
cursor.execute("SHOW SCHEMAS")
for db in cursor.fetchall():
    print(f"  {db}")

conn.close()

數據類型映射

驅動程式將 Spark SQL 資料型態映射到 ODBC SQL 型別：

商業智慧工具整合

Microsoft Excel

1. 開啟 Excel -> 資料 -> 取得資料 -> 來自其他來源 -> 來自 ODBC
2. 選擇你已設定的 DSN（例如， FabricODBC）
3. 如有提示，請驗證
4. 瀏覽並選擇表格
5. 將資料載入 Excel 工作表

Power BI Desktop

1. 啟動 Power BI Desktop -> 取得資料 -> ODBC
2. 選擇你已設定的 DSN
3. 瀏覽資料目錄並選擇表格
4. 視需要轉換資料
5. 建立視覺效果

SQL Server Management Studio（連結伺服器）

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

故障排除

本節提供解決您在使用Microsoft ODBC Driver for Microsoft Fabric Data Engineering時可能遇到的常見問題的指引。

常見問題

以下章節說明常見問題及其解決方案：

連線失敗

問題：無法連接 Fabric

解決方案：

1. 確認工作區 ID 和 Lakehouse ID 是否為有效的 GUID
2. 檢查 Azure CLI 認證： az account show
3. 確保你擁有適當的 Fabric 工作區權限
4. 檢查網路連線和代理設定

驗證錯誤

問題：Azure CLI 認證失敗

解決方案：

• 執行 az login 以刷新憑證
• 確認租戶正確： az account set --subscription <subscription-id>
• 檢查令牌有效性： az account get-access-token --resource https://api.fabric.microsoft.com

查詢逾時

問題：查詢在大型資料表上超時

解決方案：

• 啟用 LargeTableSupport=true
• 調整 PageSizeBytes 到最佳區塊大小
• 啟用非同步預取： EnableAsyncPrefetch=1
• 使用 LIMIT 子句限制結果大小

啟用日誌記錄

在排除問題時，啟用詳細記錄功能能幫助你找出問題根源。 你可以透過連線字串啟用日誌。

若要啟用詳細記錄：

LogLevel=DEBUG;LogFile=C:\temp\odbc_driver_debug.log;

日誌等級：

• DEBUG：詳細除錯資訊及最詳細的驅動程式日誌層級
• INFO：一般資訊（預設）
• WARN：僅顯示警告
• ERROR：僅有錯誤

ODBC 追蹤

在低階診斷方面，你可以啟用 Windows 的 ODBC 追蹤，以捕捉詳細的 ODBC API 呼叫與驅動程式行為。 記得在不需要時關閉追蹤，以維持最佳效能。

啟用 ODBC 追蹤：

1. 開啟odbcad32.exe
2. 前往「描圖」分頁
3. 設定追蹤檔案路徑（例如， C:\temp\odbctrace.log）
4. 選擇「立即開始追蹤」
5. 重現問題
6. 選擇「立即停止追蹤」

相關內容

• Microsoft ODBC 用於 Linux 上的 Microsoft Fabric 資料工程驅動程式
• Fabric 中的 Apache Spark 執行階段
• Fabric 執行階段 1.3
• 什麼是 Livy API 用於資料工程
• Microsoft Fabric 數據工程的 Microsoft JDBC 驅動程式