安裝適用於 Python 的 Databricks Connect

注意

本文涵蓋 Databricks Runtime 13.3 LTS 和更新版本適用的 Databricks Connect。

本文說明如何安裝適用於 Python 的 Databricks Connect。 請參閱 什麼是 Databricks Connect？。 如需本文的 Scala 版本，請參閱 安裝適用於 Scala 的 Databricks Connect。

需求

若要安裝適用於 Python 的 Databricks Connect，必須符合下列需求：

• 如果您要連線到 無伺服器計算，您的工作區必須符合 無伺服器計算的需求。

• 如果您要連線到 叢集，您的目標叢集必須符合 叢集組態 需求，其中包括 Databricks 運行時間版本需求。

• 您的開發計算機上必須安裝 Python 3，而安裝在開發電腦上的 Python 次要版本必須符合下表中的版本需求。

  Databricks Connect 版本	計算類型	相容的 Python 版本
  15.3	Cluster	3.11
  15.2	Cluster	3.11
  15.1	Cluster	3.11
  15.1	無伺服器	3.10
  13.3 LTS 至 14.3 LTS	Cluster	3.10

• 如果您想要使用 PySpark UDF，您的開發電腦安裝的次要 Python 版本必須符合叢集或無伺服器計算上安裝之 Databricks Runtime 隨附的 Python 次要版本。 若要尋找叢集的次要 Python 版本，請參閱 適用於叢集或無伺服器計算之 Databricks Runtime 版本資訊的系統環境 一節。 請參閱 Databricks Runtime 版本資訊版本資訊，以及相容性 和 無伺服器計算版本資訊。

啟用 Python 虛擬環境

Databricks 強烈建議您已針對與 Databricks Connect 搭配使用的每個 Python 版本啟用 Python 虛擬環境 。 Python 虛擬環境可協助您確定您使用的是正確的 Python 版本和 Databricks Connect。 如需這些工具以及如何啟用這些工具的詳細資訊，請參閱 venv 或 詩歌。

安裝 Databricks Connect 用戶端

本節說明如何使用 venv 或 Poetry 安裝 Databricks Connect 用戶端。

注意

如果您已安裝適用於Visual Studio Code的 Databricks 擴充功能，就不需要遵循這些設定指示，因為適用於Visual Studio Code 的 Databricks 延伸模組已經內建支援 Databricks Connect for Databricks Runtime 13.3 LTS 和更新版本。 針對 Visual Studio Code 的 Databricks 延伸模組使用 Databricks Connect，跳至 偵錯程式代碼。

使用 venv 安裝 Databricks Connect 用戶端

1. 啟用虛擬環境后，執行 uninstall 命令，以卸載已安裝 PySpark。 這是必要的， databricks-connect 因為套件與 PySpark 衝突。 如需詳細資訊，請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark，請執行 show 命令。

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. 在虛擬環境仍啟用之後，請執行 install 命令來安裝 Databricks Connect 用戶端。 --upgrade使用 選項，將任何現有的用戶端安裝升級至指定的版本。

   pip3 install --upgrade "databricks-connect==14.3.*"  # Or X.Y.* to match your cluster version.
   

   注意

   Databricks 建議您附加 「dot-asterisk」 表示法來指定 databricks-connect==X.Y.* ，而不是 databricks-connect=X.Y，以確保已安裝最新的套件。 雖然這不是必要條件，但它有助於確定您可以使用該叢集的最新支援功能。

直接跳到設定 連線屬性。

使用詩歌安裝 Databricks Connect 用戶端

1. 啟用虛擬環境后，執行 remove 命令，以卸載已安裝 PySpark。 這是必要的， databricks-connect 因為套件與 PySpark 衝突。 如需詳細資訊，請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark，請執行 show 命令。

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. 在虛擬環境仍啟用之後，請執行 add 命令來安裝 Databricks Connect 用戶端。

   poetry add databricks-connect@~14.3  # Or X.Y to match your cluster version.
   

   注意

   Databricks 建議您使用「波狀符號」表示法來指定 databricks-connect@~14.3 ，而不是 databricks-connect==14.3，以確保已安裝最新的套件。 雖然這不是必要條件，但它有助於確定您可以使用該叢集的最新支援功能。

設定連線屬性

在本節中，您會設定屬性來建立 Databricks Connect 與 Azure Databricks 叢集 或 無伺服器計算之間的連線，其中包括下列內容：

• Azure Databricks 工作區實例名稱。 這是 您 ompute 的伺服器主機名 值。 請參閱 取得 Azure Databricks 計算資源的連線詳細數據。
• 您想要使用之 Databricks 驗證類型所需的任何其他屬性。

注意

• 適用於 Python 0.19.0 和更新版本之 Databricks SDK 支援 OAuth 使用者對電腦 （U2M） 驗證 。 您可能需要將程式代碼專案的已安裝 Databricks SDK 版本更新為 0.19.0 或更新版本，才能使用 OAuth U2M 驗證。 請參閱 開始使用適用於 Python 的 Databricks SDK。

  針對 OAuth U2M 驗證，您必須先使用 Databricks CLI 進行驗證，才能執行 Python 程式代碼。 請參閱教學課程。

• 適用於 Python 0.18.0 和更新版本之 Databricks SDK 支援 OAuth 機器對機器 （M2M） 驗證 OAuth 機器對機器 （M2M） 驗證。 您可能需要將程式代碼專案的已安裝 Databricks SDK for Python 版本更新為 0.18.0 或更新版本，才能使用 OAuth M2M 驗證。 請參閱 開始使用適用於 Python 的 Databricks SDK。

• 適用於 Python 的 Databricks SDK 尚未實 作 Azure 受控識別驗證。

設定叢集的連線

若要設定叢集的連線，您需要叢集的標識符。 您可以從 URL 取得叢集識別碼。 請參閱 叢集 URL 和標識碼。

您可以使用下列其中一種方式來設定叢集的連線。 Databricks Connect 會依下列順序搜尋組態屬性，並使用它找到的第一個組態。 如需進階組態資訊，請參閱 適用於 Python 的 Databricks Connect 進階使用方式。

1. DatabricksSession 類別的 remote（） 方法。
2. Databricks 組態配置檔
3. DATABRICKS_CONFIG_PROFILE環境變數
4. 每個組態屬性的環境變數
5. 名為 DEFAULT 的 Databricks 組態配置檔

類別 DatabricksSession 的 remote() 方法

針對此選項，僅適用於 Azure Databricks 個人存取令牌驗證 、指定工作區實例名稱、Azure Databricks 個人存取令牌，以及叢集的標識符。

您可以透過數種方式初始化 DatabricksSession 類別，如下所示：

• 在中DatabricksSession.builder.remote()設定host、 token和 cluster_id 欄位。
• 使用 Databricks SDK 的 Config 類別。
• 指定 Databricks 組態配置檔以及 cluster_id 欄位。
• 在 中DatabricksSession.builder.remote()設定 Spark Connect 連接字串。

Databricks 建議透過環境變數或組態檔設定屬性，而不是在您的程式代碼中指定這些連接屬性，如本節所述。 下列程式代碼範例假設您提供建議 retrieve_* 函式的一些實作，以從使用者或從某些其他組態存放區取得必要的屬性，例如 Azure KeyVault。

下列每個方法的程式代碼如下：

# Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

Databricks 組態配置檔

針對此選項，請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔，以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

每個驗證類型的必要組態設定檔欄位如下所示：

• 針對 Azure Databricks 個人存取權杖驗證： host 和 token。
• 針對 OAuth 電腦對電腦 （M2M） 驗證 （其中支援）： host、 client_id和 client_secret。
• 針對 OAuth 使用者對電腦 （U2M） 驗證 （其中支援）： host。
• 針對Microsoft Entra ID（先前稱為 Azure Active Directory）服務主體驗證：host、azure_tenant_id、、 azure_client_idazure_client_secret和 可能azure_workspace_resource_id。
• 針對 Azure CLI 驗證： host。
• 針對 Azure 受控識別驗證 （支援的位置）： host、 azure_use_msi、 azure_client_id、 和 可能 azure_workspace_resource_id。

然後透過 Config 類別設定此組態配置檔的名稱。

您可以透過幾種方式來指定 cluster_id ，如下所示：

• 在 cluster_id 組態配置檔中包含 字段，然後只指定組態配置檔的名稱。
• 指定組態配置檔名稱以及 cluster_id 欄位。

如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID 環境變數，則不需要指定 cluster_id。

下列每個方法的程式代碼如下：

# Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

DATABRICKS_CONFIG_PROFILE環境變數

針對此選項，請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔，以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID 環境變數，則不需要指定 cluster_id。

每個驗證類型的必要組態設定檔欄位如下所示：

• 針對 Azure Databricks 個人存取權杖驗證： host 和 token。
• 針對 OAuth 電腦對電腦 （M2M） 驗證 （其中支援）： host、 client_id和 client_secret。
• 針對 OAuth 使用者對電腦 （U2M） 驗證 （其中支援）： host。
• 針對Microsoft Entra ID（先前稱為 Azure Active Directory）服務主體驗證：host、azure_tenant_id、、 azure_client_idazure_client_secret和 可能azure_workspace_resource_id。
• 針對 Azure CLI 驗證： host。
• 針對 Azure 受控識別驗證 （支援的位置）： host、 azure_use_msi、 azure_client_id、 和 可能 azure_workspace_resource_id。

將 DATABRICKS_CONFIG_PROFILE 環境變數設定為此組態配置檔的名稱。 然後初始化 類別， DatabricksSession 如下所示：

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

每個組態屬性的環境變數

針對此選項，請設定DATABRICKS_CLUSTER_ID環境變數，以及您想要使用之 Databricks 驗證類型所需的任何其他環境變數。

每個驗證類型的必要環境變數如下：

• 針對 Azure Databricks 個人存取權杖驗證： DATABRICKS_HOST 和 DATABRICKS_TOKEN。
• 針對 OAuth 電腦對電腦 （M2M） 驗證 （其中支援）： DATABRICKS_HOST、 DATABRICKS_CLIENT_ID和 DATABRICKS_CLIENT_SECRET。
• 針對 OAuth 使用者對電腦 （U2M） 驗證 （其中支援）： DATABRICKS_HOST。
• 針對Microsoft Entra ID（先前稱為 Azure Active Directory）服務主體驗證：DATABRICKS_HOST、ARM_TENANT_ID、、 ARM_CLIENT_IDARM_CLIENT_SECRET和 可能DATABRICKS_AZURE_RESOURCE_ID。
• 針對 Azure CLI 驗證： DATABRICKS_HOST。
• 針對 Azure 受控識別驗證 （支援的位置）： DATABRICKS_HOST、 ARM_USE_MSI、 ARM_CLIENT_ID、 和 可能 DATABRICKS_AZURE_RESOURCE_ID。

然後初始化 類別， DatabricksSession 如下所示：

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

名為的 Databricks 組態配置檔 DEFAULT

針對此選項，請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔，以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID 環境變數，則不需要指定 cluster_id。

每個驗證類型的必要組態設定檔欄位如下所示：

• 針對 Azure Databricks 個人存取權杖驗證： host 和 token。
• 針對 OAuth 電腦對電腦 （M2M） 驗證 （其中支援）： host、 client_id和 client_secret。
• 針對 OAuth 使用者對電腦 （U2M） 驗證 （其中支援）： host。
• 針對Microsoft Entra ID（先前稱為 Azure Active Directory）服務主體驗證：host、azure_tenant_id、、 azure_client_idazure_client_secret和 可能azure_workspace_resource_id。
• 針對 Azure CLI 驗證： host。
• 針對 Azure 受控識別驗證 （支援的位置）： host、 azure_use_msi、 azure_client_id、 和 可能 azure_workspace_resource_id。

將此組態設定檔 DEFAULT命名為 。

然後初始化 類別， DatabricksSession 如下所示：

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

設定與無伺服器計算的連線

重要

這項功能處於公開預覽狀態。

Databricks Connect 支援連線到無伺服器計算。 若要使用這項功能，必須符合連線到無伺服器的需求。 請參閱 需求。

重要

這項功能有下列限制：

• 適用於 Python 的所有 Databricks Connect 限制
• 所有無伺服器計算限制
• 只有包含在無伺服器計算環境的 Python 相依性，才能用於 UDF。 請參閱 系統環境。 無法安裝其他相依性。
• 不支援具有自定義模組的UDF。

您可以透過下列其中一種方式設定與無伺服器計算的連線：

• 將本機環境變數 DATABRICKS_SERVERLESS_COMPUTE_ID 設定為 auto。 如果設定此環境變數，Databricks Connect 會 cluster_id忽略 。

• 在本機 Databricks 組態配置檔中，設定 serverless_compute_id = auto，然後從您的 Databricks Connect Python 程式代碼參考該配置檔。

  [DEFAULT]
  host = https://my-workspace.cloud.databricks.com/
  serverless_compute_id = auto
  token = dapi123...
  

• 或者，只要更新 Databricks Connect Python 程序代碼，如下所示：

  from databricks.connect import DatabricksSession
  
  spark = DatabricksSession.builder.serverless(True).getOrCreate()
  

  from databricks.connect import DatabricksSession
  
  spark = DatabricksSession.builder.remote(serverless=True).getOrCreate()
  

注意

無伺服器計算會話會在閑置 10 分鐘後逾時。 之後，必須在用戶端重新啟動 Python 程式，才能建立新的 Spark 工作階段，以連線到無伺服器計算。

驗證 Databricks 的連線

若要驗證您的環境、預設認證和計算連線已針對 Databricks Connect 正確設定，請執行 databricks-connect test 命令，此命令會在偵測到安裝程式中的任何不相容時，失敗並出現非零結束代碼和對應的錯誤訊息。

databricks-connect test

或者，您可以使用 pyspark 包含在 Databricks Connect for Python 中的殼層，並執行簡單的命令。 如需 PySpark 殼層的詳細資訊，請參閱 Pyspark 殼層。