將 Python 和 pyodbc 連線至 Azure Databricks

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

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

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

需求

• 執行下列其中一項的本機開發電腦：
  • macOS
  • 窗戶
  • 支援 .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 倉儲。

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

步驟 2：測試您的設定

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

1. 建立名為 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)
   

2. 若要加速執行程式代碼，。

3. 使用 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 個人存取令牌。 建立個人存取權杖，請參閱 為工作區使用者建立個人存取權杖。

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

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

原因：在執行查詢返回名稱過長的欄位或錯誤訊息過長時，pyodbc 4.0.31 版或以下版本可能會出現這類徵兆的問題。 較新版本 pyodbc已修正此問題。

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

一般疑難排解

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