次の方法で共有


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

Important

この機能は プレビュー段階です

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

Microsoft ODBC Driver for Fabric Data Engineering を使用すると、ODBC 標準の信頼性とシンプルさを備えた Microsoft Fabric の Spark ワークロードを接続、クエリ、管理できます。 Microsoft Fabric の Livy API 上に構築されたドライバーは、.NET、Python、およびその他の ODBC 互換のアプリケーションや BI ツールに対して、セキュリティで保護された柔軟な Spark SQL 接続を提供します。

主要な機能

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

オープン ソースの Apache Spark では、データベースとスキーマが同義で使用されます。 たとえば、Fabric Notebook で SHOW SCHEMAS または SHOW DATABASES を実行すると、Lakehouse 内のすべてのスキーマの一覧という同じ結果が返されます。

[前提条件]

Microsoft ODBC Driver for Microsoft Fabric Data Engineering を使用する前に、次のことを確認してください。

  • オペレーティング システム: Windows 10/11 または Windows Server 2016 以降
  • Microsoft Fabric Access: Microsoft Fabric ワークスペースへのアクセス
  • Azure Entra ID 資格情報: 認証に適した資格情報
  • ワークスペース ID とレイクハウス ID: Fabric ワークスペースとレイクハウスの GUID 識別子
  • Azure CLI (省略可能): Azure CLI 認証方法に必要

ダウンロードと MSI のインストール

Microsoft ODBC Driver for Microsoft Fabric Data Engineering バージョン 1.0.0 はパブリック プレビュー段階であり、このダウンロード センターリンクからダウンロードできます。

  1. Microsoft ODBC Driver for Microsoft Fabric Data Engineering MSI パッケージをダウンロードする
  2. ダブルクリック MicrosoftFabricODBCDriver-1.0.msi
  3. インストール ウィザードに従い、使用許諾契約書に同意します
  4. インストール ディレクトリの選択 (既定値: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
  5. インストールを完了する

サイレント インストール

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

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

インストールを検証する

インストール後、ドライバーが登録されていることを確認します。

  1. odbcad32.exeの実行 (ODBC データ ソース 管理者)
  2. [ ドライバー ] タブに移動します
  3. "Microsoft ODBC Driver for Microsoft Fabric Data Engineering" が一覧表示されていることを確認する

クイックスタートの例

この例では、Microsoft Fabric に接続し、Microsoft ODBC Driver for Microsoft Fabric Data Engineering を使用してクエリを実行する方法を示します。 このコードを実行する前に、前提条件が満たされ、ドライバーがインストールされていることを確認してください。

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 ODBC Driver for Microsoft Fabric Data Engineering では、次の接続文字列形式が使用されます。

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

接続文字列コンポーネント

コンポーネント Description
ドライバー ODBC ドライバー識別子 {Microsoft ODBC Driver for Microsoft Fabric Data Engineering}
WorkspaceId Microsoft Fabric ワークスペース識別子 (GUID) xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
LakehouseId Microsoft Fabric Lakehouse 識別子 (GUID) xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
AuthFlow 認証方法 AZURE_CLIINTERACTIVECLIENT_CREDENTIALCLIENT_CERTIFICATEACCESS_TOKEN

接続文字列の例

基本接続 (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

認証

Microsoft ODBC Driver for Microsoft Fabric Data Engineering では、Microsoft Entra ID (旧称 Azure Active Directory) を使用した複数の認証方法がサポートされています。 認証は、接続文字列の AuthFlow パラメーターを使用して構成されます。

認証方法

AuthFlow 値 Description
AZURE_CLI Azure CLI 資格情報を使用した開発
INTERACTIVE 対話型ブラウザー ベースの認証
CLIENT_CREDENTIAL クライアント シークレットを含むサービス プリンシパル
CLIENT_CERTIFICATE 証明書付きサービス プリンシパル
ACCESS_TOKEN 事前に取得されたベアラー アクセス トークン

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)

必要条件:

  • 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 テナント ID
  • ClientId: Microsoft Entra ID からのアプリケーション (クライアント) ID
  • ClientSecret: Microsoft Entra ID からのクライアント シークレット

ベスト プラクティス

  • シークレットを安全に格納する (Azure Key Vault、環境変数)
  • 可能な場合はマネージド ID を使用する
  • シークレットを定期的にローテーションする

証明書ベースの認証

最適な対象: 証明書ベースの認証を必要とするエンタープライズ アプリケーション

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 テナント 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};"
)

構成パラメータ

必須のパラメーター

これらのパラメーターは、すべての接続文字列に存在する必要があります。

パラメーター タイプ Description
WorkspaceId UUID(ユニバーサリー・ユニーク・アイデンティファイア) Microsoft Fabric ワークスペース識別子 4bbf89a8-...
LakehouseId UUID(ユニバーサリー・ユニーク・アイデンティファイア) Microsoft Fabric Lakehouse 識別子 d8faa650-...
AuthFlow 認証フローの種類 AZURE_CLI

省略可能なパラメーター

接続の設定

パラメーター タイプ 既定値 Description
データベース None 接続先の特定のデータベース
Scope https://api.fabric.microsoft.com/.default OAuth スコープ

パフォーマンス設定

パラメーター タイプ 既定値 Description
ReuseSession ブール値 true 既存の Spark セッションを再利用する
LargeTableSupport ブール値 false 大きな結果セットの最適化を有効にする
EnableAsyncPrefetch ブール値 false バックグラウンド データプリフェッチを有効にする
ページサイズ(バイト数) 整数 18874368 (18 MB) 結果の改ページ位置のページ サイズ (1 ~ 18 MB)

ログ記録の設定

パラメーター タイプ 既定値 Description
LogLevel INFO ログ レベル: TRACEDEBUGINFOWARNERROR
ログファイル odbc_driver.log ログ ファイルのパス (絶対または相対)

プロキシの設定

パラメーター タイプ 既定値 Description
UseProxy ブール値 false プロキシを有効にする
ProxyHost None プロキシホスト名
ProxyPort 整数 None プロキシ ポート
ProxyUsername None プロキシ認証のユーザー名
ProxyPassword None プロキシ認証パスワード

DSN の構成

システム DSN を作成する

  1. ODBC 管理者を開く

    %SystemRoot%\System32\odbcad32.exe
    
  2. 新しいシステム DSN の作成

    • [システム DSN] タブに移動する
    • [追加] の選択
    • [Microsoft ODBC Driver for Microsoft Fabric Data Engineering] を選択する
    • [完了] を選択する
  3. DSN 設定の構成

    • データ ソース名: 一意の名前を入力します (例: FabricODBC)
    • 説明: 省略可能な説明
    • ワークスペース ID: Fabric ワークスペース GUID
    • Lakehouse ID: あなたのFabricレイクハウスGUID
    • 認証: 認証方法を選択する
    • 必要に応じて追加の設定を構成する
  4. [接続テスト]

    • [テスト接続] を選択して設定を確認する
    • [OK] を選択して保存する

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

スキーマ検出

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

Spark SQL の種類 ODBC SQL 型 C/C++ 型 Python 型 .NET の種類
BOOLEAN SQL_BIT SQLCHAR ブール (bool) ブール (bool)
BYTE SQL_TINYINT SQLSCHAR 整数 (int) sbyte
短い SQL_SMALLINT SQLSMALLINT 整数 (int) short
INT SQL_INTEGER SQLINTEGER 整数 (int) 整数 (int)
LONG SQL_BIGINT SQLBIGINT 整数 (int) long
FLOAT SQL_REAL SQLREAL float float
DOUBLE SQL_DOUBLE SQLDOUBLE float ダブル
小数 SQL_DECIMAL Sqlchar* decimal.Decimal 10 進
STRING SQL_VARCHAR Sqlchar* str 文字列
VARCHAR(n) SQL_VARCHAR Sqlchar* str 文字列
CHAR(n) SQL_CHAR Sqlchar* str 文字列
BINARY SQL_BINARY Sqlchar* バイト byte[]
DATE SQL_TYPE_DATE SQL_DATE_STRUCT (SQLの日付構造) datetime.date DateTime
TIMESTAMP SQL_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT datetime.datetime DateTime
ARRAY SQL_VARCHAR Sqlchar* str (JSON) 文字列
MAP SQL_VARCHAR Sqlchar* str (JSON) 文字列
STRUCT SQL_VARCHAR Sqlchar* str (JSON) 文字列

BI ツールの統合

マイクロソフト 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 を使用するときに発生する可能性のある一般的な問題を解決するためのガイダンスを提供します。

一般的な問題

次のセクションでは、一般的な問題とその解決策について説明します。

接続の失敗

問題: Microsoft 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;

ログ レベル:

  • TRACE: 最も詳細で、すべての API 呼び出しが含まれます
  • DEBUG: デバッグ情報の詳細
  • INFO: 一般的な情報 (既定)
  • WARN: 警告のみ
  • ERROR: エラーのみ

ODBC トレース

低レベルの診断では、Windows ODBC トレースを有効にして、詳細な ODBC API 呼び出しとドライバーの動作をキャプチャできます。 最適なパフォーマンスを維持するために必要ない場合は、トレースをオフにすることを忘れないでください。

ODBC トレースを有効にするには:

  1. odbcad32.exeをオープンする
  2. [トレース] タブに移動する
  3. トレース ファイルのパスを設定する (例: C:\temp\odbctrace.log)
  4. [今すぐトレースを開始] を選択する
  5. 問題を再現する
  6. [トレースを今すぐ停止] を選択する