針對適用於 Visual Studio Code 的 Databricks 擴充功能使用 Databricks 連線 對程式代碼進行偵錯

本文說明如何使用適用於 Visual Studio Code 的 Databricks 擴充功能中的 Databricks 連線 整合來偵錯程式代碼。 請參閱 什麼是適用於Visual StudioCode的 Databricks延伸模組？。

此資訊假設您已經安裝並設定 Visual Studio Code 的 Databricks 擴充功能。 請參閱 安裝適用於Visual Studio Code的 Databricks 擴充功能。

注意

此功能為 實驗性。

Databricks 連線 Visual Studio Code Databricks 擴充功能內的整合僅支援 Databricks 用戶端統一驗證標準的一部分。 如需詳細資訊，請參閱 VS Code Databricks 延伸模組的驗證設定。

適用於 Visual Studio Code 的 Databricks 延伸模組包含 Databricks 連線。 您可以從適用於 Visual Studio Code 的 Databricks 擴充功能內使用 Databricks 連線，執行個別 Python （.py） 檔案和 Python Jupyter 筆記本的逐步偵錯 。.ipynb。 適用於 Visual Studio Code 的 Databricks 延伸模組包含 Databricks 連線 for Databricks Runtime 13.0 和更新版本。 不支援舊版 Databricks 連線。

需求

您必須先符合 Databricks 連線 需求，才能從 Visual Studio Code 的 Databricks 擴充功能內使用 Databricks 連線。 這些需求包括使用 Unity 目錄啟用的工作區、執行 Databricks Runtime 13.0 或更新版本的叢集，以及具有單一使用者或共用的叢集存取模式，以及安裝其主要和次要版本的 Python，以及符合叢集上所安裝 Python 的本機版本。

步驟 1：建立 Python 虛擬環境

為您的 Python 程式代碼專案建立並啟用 Python 虛擬環境 。 Python 虛擬環境有助於確保您的程式代碼專案使用相容的 Python 和 Python 套件版本（在此案例中為 Databricks 連線 套件）。 本文中的指示和範例會針對 Python 虛擬環境使用 venv 或 Poetry 。 Databricks 尚未使用其他類型的 Python 虛擬環境完整測試 Databricks 連線 套件，例如 Conda。

使用 建立 Python 虛擬環境 venv

1. 從 Visual Studio Code 終端機 （View > Terminal） 設定為 Python 程式代碼專案的根目錄，指示 venv 使用 Python 進行虛擬環境，然後在 Python 程式代碼專案根目錄內名為 .venv 的隱藏目錄中建立虛擬環境的支援檔案，方法是執行下列命令：

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

   上述命令使用 Python 3.10，其符合 Databricks Runtime 13.0 所使用的 Python 主要和次要版本。 請務必使用符合您叢集所安裝 Python 版本的主要和次要 Python 版本。

2. 如果 Visual Studio Code 顯示「我們注意到已建立新的環境」訊息。 您要為工作區資料夾選取它，“按兩下 [是]。

3. 使用 venv 來啟用虛擬環境。 請參閱 venv 檔，以取得正確的命令，以根據您的作業系統和終端機類型使用。 例如，在執行的macOS zsh上：

   source ./.venv/bin/activate
   

   當虛擬環境的名稱 （例如， ） 顯示在終端機提示前的括弧中時， .venv您將知道您的虛擬環境已啟動。

   若要隨時停用虛擬環境，請執行 命令 deactivate。

   當虛擬環境的名稱不再顯示在終端機提示之前，您將知道虛擬環境的名稱已停用。

直接跳到 步驟 2：更新 Python 程式代碼以建立偵錯內容。

使用詩歌建立 Python 虛擬環境

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

2. 從 Visual Studio Code 終端機 （View > Terminal） 設定為現有 Python 程式代碼專案的根目錄，執行下列命令來指示 poetry 初始化您的 Python 程式代碼專案：

   poetry init
   

3. 詩歌顯示數個提示，讓你完成。 這些提示都不是 Visual Studio Code 的 Databricks 擴充功能或 Databricks 連線 特定的提示。 如需這些提示的相關信息，請參閱 init。

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

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

   poetry install
   

6. 指示 Visual Studio Code 使用此 Python 專案虛擬環境中隨附的 Python 解釋器，如下所示：

   1. 從專案的根目錄執行下列命令，以尋找此 Python 專案虛擬環境中 Python 解釋器的完整路徑：

      poetry env info
      

   2. 複製欄位輸出中顯示的 Virtualenv > Executable 完整路徑，例如包含 pypoetry/virtualenvs的完整路徑。

   3. 在指令選擇區 （檢視 > 命令選擇區），輸入 命令 >Python: Select Interpreter。

   4. 輸入您剛才複製之 Python 解釋器的完整路徑。

7. Visual Studio Code 終端機仍設定為 Python 程式代碼專案的根目錄，指示 poetry 啟動虛擬環境並輸入殼層。 若要這樣做，請執行下列命令：

   poetry shell
   

   您將知道您的虛擬環境已啟動，而且當虛擬環境的名稱顯示在終端機提示前的括弧中時，會輸入殼層。

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

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

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

步驟 2：更新 Python 程式代碼以建立偵錯內容

若要在 Databricks 連線 與叢集之間建立偵錯內容，您的 Python 程式代碼必須藉由呼叫 DatabricksSession.builder.getOrCreate()來初始化 DatabricksSession 類別。

請注意，當您初始化 DatabricksSession 類別時，您不需要指定如工作區實例名稱、存取令牌或叢集標識碼和埠號碼等設定。 Databricks 連線 本文稍早透過適用於Visual Studio Code 的 Databricks 延伸模組所提供的組態詳細數據取得這項資訊。

如需初始化 DatabricksSession 類別的其他資訊，請參閱 Databricks 連線 程式代碼範例。

重要

如果您使用適用於 Visual Studio Code 的 Databricks 延伸模組將驗證類型設定為個人存取令牌，則此延伸模組會設定相關的SPARK_REMOTE環境變數，並偵錯內容設定以供 Databricks 連線 使用。 這些偵錯內容設定包括相關的工作區實例名稱、個人存取令牌和叢集標識碼。

在 Databricks 連線 中，您可以使用 DatabricksSession 或 SparkSession 類別以及SPARK_REMOTE個人存取令牌驗證，以快速且輕鬆地以程式設計方式建立偵錯內容。 針對其他支援的 Azure Databricks 驗證類型，您只能 DatabricksSession 使用 類別來建立偵錯內容。

如需詳細資訊，請參閱 Databricks 連線 檔中的設定用戶端。

步驟 3：啟用 Databricks 連線

開啟延伸模組並 針對您的程式碼項目設定 [工作區] 區段，請執行下列動作：

1. 在 Visual Studio Code 狀態列中，按兩下已停用的紅色 Databricks 連線 按鈕。

2. 如果擴充功能中尚未設定 [叢集] 區段，則會出現下列訊息：「請附加叢集以使用 Databricks 連線」。 按兩下 [附加叢集]，然後選取符合 Databricks 連線 需求的叢集。

3. 如果已設定 [叢集] 區段，但叢集與 Databricks 連線 不相容，請按兩下 [紅色 Databricks 連線 停用] 按鈕，按兩下 [附加叢集]，然後選取相容的叢集。

4. 如果尚未安裝 Databricks 連線 套件（及其相依性），則會出現下列訊息：「若要進行互動式偵錯和自動完成，您需要 Databricks 連線。 您想要在環境中 <environment-name>安裝它。」 按一下 [安裝]。

5. 在 Visual Studio Code 狀態列中，[已啟用 Databricks 連線] 按鈕隨即出現。

   如果紅色的 Databricks 連線 停用按鈕仍然出現，請按兩下它，並完成螢幕上的指示，以取得已啟用 Databricks 連線 按鈕。

6. 啟用 Databricks 連線 按鈕之後，您現在已準備好使用 Databricks 連線。

注意

您不需要設定延伸模組的 [同步目的地] 區段，程式代碼專案才能使用 Databricks 連線。

如果您使用詩歌，您可以執行下列命令，將 和 pyproject.tomlpoetry.lock 檔案與已安裝的 Databricks 連線 套件（及其相依性）同步處理。 請務必將 取代13.3.2為 Databricks 連線 套件的版本，該套件符合適用於您專案的 Databricks 擴充功能所安裝的套件。

poetry add databricks-connect==13.3.2

步驟 4：執行或偵錯 Python 程式代碼

為程式代碼專案啟用 Databricks 連線 之後，請執行或偵錯 Python 檔案或筆記本，如下所示。

若要執行或偵錯 Python （.py） 檔案：

1. 在您的程式代碼專案中，開啟您要執行或偵錯的 Python 檔案。

2. 在 Python 檔案中設定任何偵錯斷點。

3. 在檔案編輯器的標題欄中，按兩下播放 （執行或偵錯] 圖示旁的下拉式箭號。 然後在下拉式清單中，選取 [偵錯 Python 檔案]。 此選項支援逐步偵錯、斷點、監看表達式、呼叫堆疊和類似功能。 此選項使用 Databricks 連線 在本機執行 Python 程式代碼、在遠端工作區中的叢集上執行 PySpark 程式代碼，以及將遠端回應傳送回 Visual Studio Code 以進行本機偵錯。

   注意

   不支援偵錯的其他選項包括：

   • 執行 Python 檔案以使用 Databricks 連線 來執行檔案或筆記本，但不需要偵錯支援。 此選項會將檔案傳送至遠端工作區、在工作區中的遠端叢集上執行檔案的 Python 和 PySpark 程式代碼，並將遠端回應傳送至 Visual Studio Code 終端機。
   • 上傳並執行 Databricks 上的檔案以將檔案傳送至遠端工作區、在工作區中的遠端叢集上執行檔案的 Python 和 PySpark 程式代碼，並將遠端回應傳送至 Visual Studio Code 終端機。 此選項不會使用 Databricks 連線。
   • 在 Databricks 上以工作流程身分執行檔案以將檔案傳送至遠端工作區、在與自動化 Azure Databricks 作業相關聯的叢集上執行檔案的 Python 和 PySpark 程式代碼，並將結果傳送至 Visual Studio Code 中的編輯器。 此選項不會使用 Databricks 連線。

   

   [ 在互動式視窗中 執行目前檔案] 選項，如果有的話，會嘗試在本機以特殊的 Visual Studio Code 互動式編輯器執行檔案。 Databricks 不建議使用此選項。

若要執行或偵錯 Python Jupyter Notebook （.ipynb）：

1. 在您的程式代碼專案中，開啟您要執行或偵錯的 Python Jupyter Notebook。 請確定 Python 檔案是 Jupyter 筆記本格式，且擴展名為 .ipynb。

   提示

   您可以從命令選擇區內執行 >[建立：新增 Jupyter Notebook] 命令，以建立新的 Python Jupyter Notebook。

2. 單擊 [執行所有單元格] 以執行所有單元格而不偵錯、執行單元格以執行個別的對應單元格而不進行偵錯，或 [依行執行] 以執行具有有限偵錯的個別單元格行列，並在 Jupyter 面板中顯示變數值（檢視>開啟檢視 > Jupyter）。

   如需個別儲存格內的完整偵錯，請設定斷點，然後單擊儲存格 [執行] 按鈕旁選單中的 [偵錯儲存格]。

   按兩下上述任何選項之後，系統可能會提示您安裝遺漏的 Python Jupyter Notebook 套件相依性。 按一下以安裝。

   如需詳細資訊，請參閱 VS Code 中的 Jupyter Notebook。