將 Python 和 pyodbc 連線至 Azure Databricks

發行項
08/29/2024

您可以透過 ODBC 從本機 Python 程式代碼連線到 Azure Databricks 叢集或 SQL 倉儲中的數據。若要這樣做，您可以使用開放原始碼 Python 程式代碼模組 pyodbc。

請遵循這些指示來安裝、設定及使用 pyodbc。

如需的詳細資訊 pyodbc，請參閱 pyodbc Wiki。

注意

Databricks 提供適用於 Python 的 Databricks SQL 連接器，作為的pyodbc替代方案。適用於 Python 的 Databricks SQL Connector 更容易設定及使用，而且具有比更強固的一組程式代碼建構 pyodbc。不過 pyodbc ，擷取超過 10 MB 的查詢結果時，效能可能更好。

這些指示已使用 Databricks ODBC 驅動程式 2.7.5、pyodbc 5.0.1 和 unixODBC 2.3.12 進行測試。

需求

執行下列其中一項的本機開發電腦：
- macOS
- Windows
- 支援 .rpm 或 .deb 檔案的 Unix 或 Linux 發行版
pip。
針對 Unix、Linux 或 macOS、 Homebrew。
Azure Databricks 叢集、Databricks SQL 倉儲或兩者。如需詳細資訊，請參閱計算組態參考和連線到 SQL 倉儲。

步驟 1：下載、安裝及設定軟體

在此步驟中，您會下載並安裝 Databricks ODBC 驅動程式、 unixodbc 套件和 pyodbc 模組。（模組 pyodbc 需要 unixodbc Unix、Linux 和 macOS 上的套件。您也會設定 ODBC 資料來源名稱（DSN）來向進行驗證，並連線到您的叢集或 SQL 倉儲。

下載並安裝 Databricks ODBC 驅動程式，併為您的作業系統設定 ODBC DSN 。
若為 Unix、Linux 和 macOS，請安裝 unixodbc 套件：從終端機使用 Homebrew 來執行命令 brew install unixodbc。如需詳細資訊，請參閱 Homebrew 網站上的 unixodbc 。
pyodbc安裝模組：從終端機或命令提示字元，使用 pip 來執行命令 pip install pyodbc。如需詳細資訊，請參閱 PyPI 網站上的 pyodbc 和 pyodbc Wiki 中的 Install 。

步驟 2：測試您的設定

在此步驟中，您會撰寫並執行 Python 程式代碼，以使用 Azure Databricks 叢集或 Databricks SQL 倉儲來查詢trips目錄nyctrips架構中的samples數據表，並顯示結果。

建立名為 pyodbc-demo.py 且具有下列內容的檔案。將取代 <dsn-name> 為您稍早建立的 ODBC DSN 名稱、儲存盤案，然後使用 Python 解釋器執行檔案。

import pyodbc

# Connect to the Databricks cluster by using the
# Data Source Name (DSN) that you created earlier.
conn = pyodbc.connect("DSN=<dsn-name>", autocommit=True)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute(f"SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

若要加速執行程式代碼，請啟動對應至 DSN 中設定的HTTPPath叢集。
使用 Python 解釋器執行 pyodbc-demo.py 檔案。數據表數據列的相關信息隨即顯示。

下一步

若要針對不同的叢集或 SQL 倉儲執行 Python 測試程式代碼，請建立不同的 DSN 並變更 <dsn-name> 為 DSN 的名稱。
若要使用不同的 SQL 查詢執行 Python 測試程式代碼，請變更 execute 命令字串。

使用無 DSN 連線

除了使用 DSN 名稱，您也可以內嵌指定連線設定。下列範例示範如何針對 Azure Databricks 個人存取令牌驗證使用無 DSN 連接字串。此範例假設您有下列環境變數：

設定 DATABRICKS_SERVER_HOSTNAME 為工作區實例名稱，例如 adb-1234567890123456.7.azuredatabricks.net。
設定 DATABRICKS_HTTP_PATH 為 工作區中目標叢集或 SQL 倉儲的 HTTP 路徑 值。若要取得 HTTP 路徑 值，請參閱取得 Azure Databricks 計算資源的連線詳細數據。
設定 DATABRICKS_TOKEN 為目標使用者的 Azure Databricks 個人存取令牌。若要建立個人存取令牌，請參閱適用於工作區使用者的 Azure Databricks 個人存取令牌。

若要設定環境變數，請參閱您的作業系統文件。

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=3;" +
  "UID=token;" +
  f"PWD={os.getenv('DATABRICKS_TOKEN')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

下列範例使用 OAuth 使用者對電腦（U2M）或 OAuth 2.0 瀏覽器型驗證，而不是 Azure Databricks 個人存取令牌。此範例假設您已經設定上述 DATABRICKS_SERVER_HOSTNAME 和 DATABRICKS_HTTP_PATH 環境變數。

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=2;" +
  "PWD=1234567",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

下列範例使用 OAuth 計算機對電腦（M2M）或 OAuth 2.0 用戶端認證驗證。此範例假設您已經設定上述 DATABRICKS_SERVER_HOSTNAME 和 DATABRICKS_HTTP_PATH 環境變數，以及下列環境變數：

設定 ARM_CLIENT_ID 為服務主體 的應用程式（用戶端）識別碼 值。
設定 DATABRICKS_OAUTH_SECRET 為服務主體的 OAuth 秘密值。（Microsoft Databricks ODBC Driver 的 OAuth M2M 或 OAuth 2.0 用戶端認證驗證不支援 Entra ID 秘密。

如需詳細資訊，請參閱 OAuth 計算機對電腦（M2M）驗證。

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=1;" +
  f"Auth_Client_ID={os.getenv('ARM_CLIENT_ID')};" +
  f"Auth_Client_Secret={os.getenv('DATABRICKS_OAUTH_SECRET')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

疑難排解

本節解決搭配 Databricks 使用 pyodbc 時的常見問題。

Unicode 譯碼錯誤

問題：您收到類似下列的錯誤訊息：

<class 'pyodbc.Error'> returned a result with an error set
Traceback (most recent call last):
File "/Users/user/.pyenv/versions/3.7.5/lib/python3.7/encodings/utf_16_le.py", line 16, in decode
return codecs.utf_16_le_decode(input, errors, True)
UnicodeDecodeError: 'utf-16-le' codec can't decode bytes in position 2112-2113: illegal UTF-16 surrogate

原因：當執行傳回具有長名稱或長錯誤訊息之數據行的查詢時，4.0.31 版或以下版本可能會顯示這類徵兆的問題 pyodbc 。較新版本 pyodbc已修正此問題。

解決方案：將您的安裝 pyodbc 升級至 4.0.32 版或更新版本。

一般疑難排解

請參閱 GitHub 上的 mkleehammer/pyodbc 存放庫中的問題。

共用方式為