安裝適用於 Python 的 Databricks 連線

注意

本文涵蓋 Databricks 連線 Databricks Runtime 13.0 和更新版本。

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

需求

• 您的目標 Azure Databricks 工作區和叢集必須符合 Databricks 連線 叢集設定的需求。

• 您必須在開發計算機上安裝 Python 3，且用戶端 Python 安裝的次要版本必須與 Azure Databricks 叢集的次要 Python 版本相同。 若要尋找叢集的次要 Python 版本，請參閱叢集 Databricks Runtime 版本資訊中的「系統環境」一節。 請參閱 Databricks Runtime 版本資訊版本和相容性。

  注意

  如果您想要使用 PySpark UDF，請務必讓開發機器安裝的 Python 次要版本符合叢集上安裝 Databricks Runtime 隨附的 Python 次要版本。

• Databricks 連線 主要和次要套件版本應符合您的 Databricks Runtime 版本。 Databricks 建議您一律使用與 Databricks Runtime 版本相符的最新 Databricks 連線 套件。 例如，當您使用 Databricks Runtime 14.0 叢集時，也應該使用 14.0 套件的版本 databricks-connect 。

  注意

  如需可用的 Databricks 連線 版本和維護更新清單，請參閱 Databricks 連線 版本資訊。

  使用與 Databricks 執行時間版本相符的最新 Databricks 連線 套件並非必要專案。 針對 Databricks Runtime 13.3 LTS 和更新版本，您可以在 Databricks 連線 套件版本或更新版本的 Databricks 運行時間上使用 Databricks 連線 套件。 不過，如果您想要使用更新版本的 Databricks Runtime 中可用的功能，則必須據以升級 Databricks 連線 套件。

• Databricks 強烈建議您已針對與 Databricks 連線 搭配使用的每個 Python 版本啟用 Python 虛擬環境。 Python 虛擬環境可協助您確定您同時使用正確的 Python 和 Databricks 版本 連線。 這有助於減少或縮短解決相關的技術問題。 請參閱下列各節中的如何啟用或詩歌的 venv Python 虛擬環境。 如需這些工具的詳細資訊，請參閱 venv 或 詩歌。

使用 venv 啟用 Python 虛擬環境

如果您在開發計算機上使用 venv ，且叢集正在執行 Python 3.10，則必須使用該版本建立 venv 環境。 下列範例命令會產生腳本來啟動 venv 具有 Python 3.10 的環境，然後此命令會將這些腳本放在目前工作目錄中名為 .venv 的隱藏資料夾中：

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

若要使用這些腳本來啟用此 venv 環境，請參閱 venvs 的運作方式。

直接跳到 設定用戶端。

使用詩歌啟用 Python 虛擬環境

1. 安裝詩歌，如果您尚未這麼做。

2. 如果您在開發計算機上使用詩歌，且您的叢集正在執行 Python 3.10，則必須使用該版本建立詩歌虛擬環境。 從現有 Python 程式代碼專案的根目錄中，執行下列命令，指示 poetry 初始化 Poetry 的 Python 程式代碼專案：

   poetry init
   

3. 詩歌顯示數個提示，讓你完成。 這些提示都不是 Databricks 連線 特有的提示。 如需這些提示的相關信息，請參閱 init。

4. 完成提示之後，Poetry 會將檔案 pyproject.toml 新增至 Python 專案。 如需檔案的相關信息 pyproject.toml ，請參閱 pyproject.toml 檔案。

5. 從 Python 程式代碼專案的根目錄，指示 poetry 讀取 pyproject.toml 檔案、解析相依性並加以安裝、建立 poetry.lock 檔案以鎖定相依性，最後建立虛擬環境。 若要這樣做，請執行下列命令：

   poetry install
   

6. 從 Python 程式代碼專案的根目錄，指示 poetry 啟動虛擬環境並輸入殼層。 若要這樣做，請執行下列命令：

   poetry shell
   

您會知道您的虛擬環境已啟動，而且當虛擬環境的名稱顯示在終端機提示之前方括弧時，會輸入殼層，例如 (my-project-py3.10)。

若要停用虛擬環境並隨時結束殼層，請執行 命令 exit。

當虛擬環境的名稱不再顯示在終端機提示前的括弧中時，您將知道已結束殼層。

如需建立和管理詩歌虛擬環境的詳細資訊，請參閱 管理環境。

設定 用戶端

提示

如果您已安裝適用於 Visual Studio Code 的 Databricks 擴充功能，就不需要遵循這些設定指示。

適用於 Visual Studio Code 的 Databricks 延伸模組已經內建支援 Databricks 連線 for Databricks Runtime 13.0 和更新版本。 使用 Databricks 連線 Visual Studio Code 的 Databricks 擴充功能，直接跳到偵錯程序代碼。

在您符合 Databricks 連線 的需求之後，請完成下列步驟來設定 Databricks 連線 用戶端。

步驟 1：安裝 Databricks 連線 用戶端

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

使用 venv 安裝 Databricks 連線 用戶端

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

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

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

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

   注意

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

直接跳到 步驟 2：設定連線屬性。

使用詩歌安裝 Databricks 連線 用戶端

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

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

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

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

   注意

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

步驟 2：設定連線屬性

在本節中，您會設定屬性來建立 Databricks 連線 與遠端 Azure Databricks 叢集之間的連線。 這些屬性包括用來向叢集驗證 Databricks 連線 的設定。

針對 Databricks 連線 Databricks Runtime 13.1 和更新版本，Databricks 連線 包含適用於 Python 的 Databricks SDK。 此 SDK 會實作 Databricks 用戶端統一驗證 標準、合並且一致的架構和驗證程序設計方法。 這種方法可讓使用 Azure Databricks 更集中且可預測的方式來設定和自動化驗證。 它可讓您設定 Azure Databricks 驗證一次，然後在多個 Azure Databricks 工具和 SDK 之間使用該設定，而不需要進一步的驗證組態變更。

注意

• 適用於 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 受控識別驗證。

• Databricks runtime 13.0 的 Databricks 連線 僅支援 Azure Databricks 個人存取令牌驗證以進行驗證。

1. 收集下列組態屬性。

   • Azure Databricks 工作區實例名稱。 這與叢集的伺服器 主機名 值相同;請參閱 取得 Azure Databricks 計算資源的連線詳細數據。
   • 叢集的標識碼。 您可以從 URL 取得叢集識別碼。 請參閱 叢集 URL 和標識碼。
   • 您想要使用之支援的 Databricks 驗證類型 所需的任何其他屬性。 本節會說明這些屬性。

2. 在您的程式代碼中設定連線。 Databricks 連線 依下列順序搜尋組態屬性，直到找到它們為止。 找到它們之後，它會停止搜尋其餘選項。 下表後面會出現每個選項的詳細資料：

   組態屬性選項	適用於
   1. 類別 DatabricksSession 的 remote() 方法	僅限 Azure Databricks 個人存取令牌驗證
   2.Azure Databricks 組態配置檔	所有 Azure Databricks 驗證類型
   3. SPARK_REMOTE 環境變數	僅限 Azure Databricks 個人存取令牌驗證
   4. DATABRICKS_CONFIG_PROFILE 環境變數	所有 Azure Databricks 驗證類型
   5. 每個組態屬性的環境變數	所有 Azure Databricks 驗證類型
   6.名為 的 Azure Databricks 組態配置檔 DEFAULT	所有 Azure Databricks 驗證類型

   1. 類別 DatabricksSession 的 remote() 方法

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

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

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

      Databricks 不建議您在程式碼中直接指定這些連接屬性。 相反地，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()
      
      # Set the Spark Connect connection string in DatabricksSession.builder.remote.
      from databricks.connect import DatabricksSession
      
      workspace_instance_name = retrieve_workspace_instance_name()
      token                   = retrieve_token()
      cluster_id              = retrieve_cluster_id()
      
      spark = DatabricksSession.builder.remote(
        f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
      ).getOrCreate()
      

   2. Azure 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_id、 azure_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()
      

   3. SPARK_REMOTE環境變數

      針對此選項，僅適用於 Azure Databricks 個人存取令牌驗證，請將環境變數設定SPARK_REMOTE為下列字串，並將佔位元取代為適當的值。

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>
      

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

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

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

   4. 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_id、 azure_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()
      

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

   5. 每個組態屬性的環境變數

      針對此選項，請設定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_ID、 ARM_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()
      

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

   6. 名為的 Azure 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_id、 azure_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()
      

3. 驗證您的環境和 Databricks 叢集的連線

   • 下列命令會確認您的環境、預設認證和叢集連線都已針對 Databricks 連線 正確設定。

     databricks-connect test
     

     此命令會挑選在環境上設定的預設認證（例如 DEFAULT 組態配置檔或透過環境變數）。

     當命令偵測到安裝程式中的任何不相容時，命令會失敗，並出現非零結束代碼和對應的錯誤訊息。

   • 此外，您也可以使用pyspark隨附於 Databricks 連線 for Python 的殼層。 執行下列命令以啟動殼層：

     pyspark
     

     Spark 殼層隨即出現，例如：

     Python 3.10 ...
     [Clang ...] on darwin
     Type "help", "copyright", "credits" or "license" for more information.
     Welcome to
           ____              __
          / __/__  ___ _____/ /__
         _\ \/ _ \/ _ `/ __/  '_/
        /__ / .__/\_,_/_/ /_/\_\   version 13.0
           /_/
     
     Using Python version 3.10 ...
     Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
     SparkSession available as 'spark'.
     >>>
     

     在提示字元中 >>> ，執行簡單的 PySpark 命令， 例如 spark.range(1,10).show()。 如果沒有錯誤，您已成功連線。

     如果您已成功連線，請停止 Spark 殼層、按 Ctrl + d 或 Ctrl + z，或執行 命令 quit() 或 exit()。

     如需二進位檔的詳細資訊databricks-connect，請參閱適用於 Python 的 Databricks 連線 進階使用方式