Microsoft ODBCドライバ Microsoft Fabric Data Engineering on Linux(プレビュー)

ODBC (Open Database Connectivity) は、クライアント アプリケーションがデータベースやビッグ データ プラットフォームのデータに接続して操作できるようにする、広く採用されている標準です。

Microsoft ODBCドライバー for Fabric Data Engineeringは、ODBC標準の信頼性とシンプルさでFabric上でSparkワークロードの接続、クエリ、管理を可能にします。 FabricのLivy APIを基に構築されたこのドライバーは、Linux上のC/C++、.NET、Python、その他のODBC互換アプリケーションに対して安全かつ柔軟なSpark SQL接続を提供します。

主要な機能

• ODBC 3.x準拠:ODBC 3.x仕様の完全実装。
• Microsoft Entra ID認証:Azure CLI、クライアント認証、証明書ベース、アクセストークン認証を含む複数の認証フロー。
• Spark SQLクエリサポート:Spark SQL文の直接実行。
• 包括的なデータ型サポート:複雑な型(ARRAY、 MAP、 STRUCTを含むすべてのSpark SQLデータ型をサポートしています)。
• セッション再利用:パフォーマンス向上のための組み込みセッション管理機能。
• 大規模テーブルサポート:設定可能なページサイズを持つ大規模な結果セットの最適化された処理。
• 非同期プリフェッチ:性能向上のためのバックグラウンドデータロード。
• プロキシサポート:エンタープライズ環境向けのHTTPプロキシ設定。
• マルチスキーマレイクハウスサポート:レイクハウス内の特定のスキーマに接続します。

前提条件

Linux上でMicrosoft ODBCドライバー(Microsoft Fabric Data Engineering用)を使用する前に、以下の前提条件を確認してください。

• オペレーティングシステム:Ubuntu 22.04以降、Debian 11以降、またはRed Hat Enterprise Linux(RHEL)8以降(x86-64)を搭載。
• unixODBC:Linux用のODBCドライバーマネージャーです。 unixodbcとunixodbc-devパッケージをインストールしてください。
• Fabricアクセス:Fabricワークスペースへのアクセス。
• Microsoft Entra IDの認証情報:認証に適切な認証情報。
• ワークスペースおよびレイクハウスID:FabricのワークスペースとレイクハウスのGUID識別子です。
• Azure CLI (optional):Azure CLI 認証を使用する際に必須。

Linuxでダウンロード・インストール

Microsoft ODBCドライバー for Microsoft Fabric Data Engineering バージョン1.0.0はパブリックプレビューで利用可能です。

• Linux版Microsoft Fabric Data Engineering用Microsoft ODBCドライバー(zip)をダウンロード

ドライバーをインストールするには:

1. ms-sparksql-odbc-linux-1.0.0.zipを抽出します。

2. 抽出したディレクトリで端末を開きます。

3. Debianパッケージをインストールする:

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

このパッケージは以下のファイルをインストールします:

手動でドライバーを登録してください

パッケージはドライバーを自動的に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クエリを実行します。 事前条件を満たし、ドライバーをインストールしてからサンプルを実行してください。

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

Authentication

Microsoft ODBCドライバー for Microsoft Fabric Data Engineeringは、Microsoft Entra IDを通じた複数の認証方法をサポートしています。 認証は、接続文字列またはDSNのAuthFlowパラメータを使って設定します。

認証方法

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

DebianまたはUbuntuにAzure CLIをインストールするには、パッケージマネージャーをご利用ください:

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 テナント ID です。
• ClientId: アプリケーション (クライアント) ID。
• 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 テナント ID です。
• ClientId: アプリケーション (クライアント) ID。
• 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};"
)

構成パラメータ

必須のパラメーター

すべての接続文字列に以下のパラメータを含めます:

省略可能なパラメーター

接続設定

パフォーマンス設定

ログ記録の設定

プロキシの設定

DSN の構成

Linuxでは、WindowsレジストリではなくINIファイルでデータソース名(DSN)を設定しましょう。

DSN を作成する

インストール済みのテンプレートをコピーしてください:

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

Fabricワークスペースの詳細で編集~/.odbc.ini:

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

isqlコマンドはunixODBCのコマンドラインツールを必要とします。

アプリケーションで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 -v FabricDSN

単一のクエリを実行します:

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

大規模な結果セットの作業

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 型にマップします。

プラットフォームの違い

Troubleshooting

運転手が見つからない

問題: [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-1.0.0-Linux.debを実行してパッケージを再インストールしてください。

DSN が見つかりません

問題: [IM002] Data source name not foundで接続が失敗します。

解決策:

1. DSNの設定は odbcinst -q -sを実行して確認してください。
2. ~/.odbc.iniまたはDSNのセクションが含まれているか/etc/odbc.ini確認してください。
3. Driverの価値が登録されたドライバー名と正確に一致していることを確認してください。

接続の失敗

問題:ドライバーがFabricに接続できません。

解決策:

1. ワークスペースIDとレイクハウスIDが有効なGUIDであることを確認しましょう。
2. 認証Azure CLIaz account showを実行してください。
3. 必要なFabricワークスペースの権限を持っていることを確認してください。
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ワークスペース権限を持っていることを確認してください。

共有ライブラリエラー

問題:運転手が error while loading shared libraries: libmicrosoftfabricodbc.soを報告しています。

解決策:

1. sudo dpkg -i microsoft-fabric-odbc-driver-1.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;

ドライバーは以下のログレベルをサポートしています:

• TRACE: すべてのAPIコールを含みます。
• DEBUG詳細なデバッグ情報を含む。
• INFO: 一般情報が含まれ、デフォルトです。
• WARN警告のみを含みます。
• ERROR: 誤りのみを含みます。

unixODBCトレーシングを有効にする

低レベルのODBCコール診断では、 /etc/odbcinst.iniに以下の構成を追加してください:

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

トラブルシューティングが終わったら、不要なパフォーマンス負荷を避けるためにトレーシングをオフにしてください。

関連するコンテンツ

• Microsoft ODBCドライバ for Microsoft Fabric Data Engineering
• Fabric の Apache Spark ランタイム
• ファブリック ランタイム 1.3
• データ エンジニアリング用 Livy API とは
• Microsoft JDBCドライバ for Microsoft Fabric Data Engineering
• ユニックスODBC