搭配 Azure Databricks 使用 SQLAlchemy

Azure Databricks 為 Azure Databricks 提供 SQLAlchemy方言 (SQLAlchemy 用來與各種類型的資料庫 API 實作和資料庫通訊的系統)。 SQLAlchemy 是 Python SQL 工具組和物件關聯對應器 (ORM)。 SQLAlchemy 提供一套知名的企業級持續性模式，專為高效且高效能的資料庫存取而設計，並改編成簡單的 Pythonic 網域語言。 請參閱功能和理念。

必須安裝 Azure Databricks 的 SQLAlchemy 方言，才能搭配 Azure Databricks 使用 SQLAlchemy 功能。 本文涵蓋 Azure Databricks 1.0 版和 2.0 版的 SQLAlchemy 方言，該方言將以適用於 Python 4.0.0 版或更新版本的 Databricks SQL Connector 為基礎。

需求

• 執行 Python >=3.8 和 <=3.11 的開發機器。
• Databricks 建議您使用 Python 虛擬環境，例如 Python 隨附的 venv 所提供的環境。 虛擬環境可協助您確保同時使用正確的 Python 版本和適用於 Python 的 Databricks SQL 連接器。 設定和使用虛擬環境不屬於本文的討論範圍。 如需詳細資訊，請參閱建立虛擬環境。
• 現有的叢集或 SQL 倉儲。

開始

• 為 SQLAlchemy v1 安裝 databricks-sqlalchemy 使用 pip install databricks-sqlalchemy~=1.0，或為 SQLAlchemy v2 使用 pip install databricks-sqlalchemy。 如需版本資訊，請參閱 databricks-sqlalchemy 版本歷史。

• 針對想要使用的叢集或 SQL 倉儲，收集下列資訊：

  叢集

  • 叢集的伺服器主機名稱。 您可以從叢集的 [] 索引標籤中的 [> 值取得此值。
  • 叢集的 HTTP 路徑。 您可以從叢集的 ] 索引卷標中，取得 > 的值。

  SQL 資料庫倉儲

  • SQL 倉儲的伺服器主機名稱。 您可以從 SQL 倉儲的 [連線 詳細數據] 索引卷標中的 [伺服器主機名] 值取得此值。
  • SQL 倉儲的 HTTP 路徑。 您可以從 SQL 倉儲的 [連線 詳細資料] 索引卷標中的 [HTTP 路徑] 值取得此值。

驗證

Azure Databricks 的 SQLAlchemy 方言使用 Databricks SQL 連接器（Python）來連接，並將 connect_args 中的值傳遞給連接器。 它支援以下認證類型：

• 個人存取權杖認證
• OAuth 使用者與機器對應 (U2M) 驗證
• OAuth 計算機對電腦 （M2M） 驗證

個人存取權杖認證

若要建立 Azure Databricks 個人存取權杖，請遵循為 工作區使用者建立個人存取權杖中的步驟。

若要驗證 SQLAlchemy 方言，請使用下列程式碼片段。 此代碼段假設您已設定下列環境變數：

• DATABRICKS_TOKEN，設定為 Azure Databricks 個人存取令牌。
• DATABRICKS_SERVER_HOSTNAME已設為叢集或 SQL 倉儲的 伺服器主機名稱 值。
• DATABRICKS_HTTP_PATH，設為叢集或 SQL 倉儲的 HTTP 路徑 值。
• DATABRICKS_CATALOG，設定為 Unity 目錄中的目標目錄。
• DATABRICKS_SCHEMA，設定為 Unity 目錄中的目標架構（也稱為資料庫）。

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

import os
from sqlalchemy import create_engine

access_token    = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://token:{access_token}@{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}"
)

# ...

您可以使用上述 engine 變數，透過 Azure Databricks 計算資源連線到指定的目錄和架構。

OAuth 使用者對電腦 （U2M） 驗證

OAuth U2M 認證使用即時人類登入與同意來驗證目標 Azure Databricks 使用者帳號。 如需瞭解各雲端上支援的 Databricks SQL Connector for Python 版本，請參見 OAuth 使用者對機器（U2M）驗證。

要用 OAuth U2M 驗證 SQLAlchemy 方言，請使用以下程式碼片段。 此程式碼片段假設你已設定 DATABRICKS_SERVER_HOSTNAME、DATABRICKS_HTTP_PATH、DATABRICKS_CATALOG 和 DATABRICKS_SCHEMA 環境變數，如 個人存取憑證認證所述。

import os
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"auth_type": "databricks-oauth"}
)

# ...

OAuth 計算機對電腦 （M2M） 驗證

OAuth M2M authentication 以 Azure Databricks service principal 身份認證。 你也必須安裝 Databricks SDK for Python（例如執行 pip install databricks-sdk）。 如需瞭解各雲端上支援此功能的 Databricks SQL Connector for Python 和 SDK 版本，請參見 OAuth 機器對機器（M2M）認證。

要使用 OAuth M2M 認證，請執行以下步驟：

1. 在 Azure Databricks 工作區中建立 Azure Databricks 服務主體，並為該服務主體建立 OAuth 祕密。 請參見 使用 OAuth 授權服務主體存取至 Azure Databricks。
2. 讓那個服務主體名稱存取你的叢集或 SQL 倉儲。 請參閱 計算許可權 或 管理 SQL 倉儲。

要用 OAuth M2M 驗證 SQLAlchemy 方言，請使用以下程式碼片段。 除了 DATABRICKS_SERVER_HOSTNAME、DATABRICKS_HTTP_PATH、DATABRICKS_CATALOG 和 DATABRICKS_SCHEMA 環境變數外，此程式碼片段假設你已設定以下環境變數：

• DATABRICKS_CLIENT_ID，設定為服務主體的 UUID 或 應用程式識別碼 值。
• DATABRICKS_CLIENT_SECRET，設定服務主體的 OAuth 憑證為 Secret 值。

import os
from databricks.sdk.core import Config, oauth_service_principal
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"credentials_provider": credential_provider}
)

# ...

SQLAlchemy v1

如需連線範例，請參閱此 example.py

SQLAlchemy v2

如需連線範例，請參閱下一節和 GitHub 中的 sqlalchemy_example.py 檔案。

DBAPI 參考

• gitHub 存放庫 databricks-sqlalchemy v1
• SQLAlchemy v1 README.md
• databricks-sqlalchemy v2 GitHub 儲存庫
• SQLAlchemy v2 README.md

其他資源

• SQLAlchemy 1 整合教學課程
• SQLAlchemy 2 整合教學課程