搭配 Visual Studio Code 使用使用 dbx

重要

此文件已淘汰，且可能未更新。

Databricks 建議您使用 Databricks Asset Bundles，而不是 Databricks Labs 的 dbx。 請參閱什麼是 Databricks 資產套件組合？和從 dbx 遷移至套件組合。

若要搭配 Visual Studio Code 使用 Azure Databricks，請參閱適用於 Visual Studio Code 的 Databricks 擴充功能一文。

本文說明可在任何 Python 相容的 IDE 中使用以 Python 為基礎的程式碼範例。 具體來說，本文說明如何在Visual StudioCode中使用此程式碼範例，提供下列開發人員生產力功能：

• 程式碼完成
• 正在 Lint
• 測試
• 偵錯不需要對遠端 Azure Databricks 資源進行即時連線的程式碼物件。

本文使用 Databricks Labs 的 dbx 以及 Visual Studio Code，將程式碼範例提交至遠端 Azure Databricks 工作區。 dbx 指示 Azure Databricks 排程及協調工作流程，以在該工作區中的 Azure Databricks 作業叢集 上執行提交的程式碼。

您可以使用熱門的第三方 Git 提供者進行版本控制和持續整合，以及程式碼的持續傳遞或持續部署 (CI/CD)。 針對版本控制，這些 Git 提供者包含下列內容：

• GitHub
• Bitbucket
• GitLab
• Azure DevOps (不適用於 Azure 中國區域)
• AWS CodeCommit
• GitHub AE

針對 CI/CD，dbx 支援下列 CI/CD 平台：

• GitHub 動作
• Azure Pipelines
• GitLab CI/CD

為了示範版本控制和 CI/CD 的運作方式，本文說明如何使用 Visual Studio Code、dbx和此程式碼範例，以及 GitHub 和 GitHub Actions。

程式碼範例需求

若要使用此程式碼範例，您必須具有下列內容：

• Azure Databricks 帳戶中的 Azure Databricks 工作區。
• GitHub 帳戶。 建立 GitHub 帳戶 (如果您還沒有帳戶的話)。

此外，在您的本機開發電腦上您必須具有下列內容：

• Python 3.8 或更新版本。

  您應該使用符合目標叢集上安裝的 Python 版本。 若要取得安裝在現有叢集上的 Python 版本，您可以使用叢集的網路終端機來執行 python --version 命令。 針對您目標叢集的 Databricks Runtime 版本，請參閱 Databricks Runtime 版本資訊版本和相容性中的的「系統環境」一節。 在任何情況下，Python 的版本都必須是 3.8 或更新版本。

  若要取得本機電腦上目前參考的 Python 版本，請從本機終端機執行 python --version。 (視您在本機電腦上設定 Python 的方式而定，您可能需要執行 python3，而不是在整個文章中執行 python。) 另請參閱選取 Python 解譯器。

• pip。 pip 會自動與較新版本的 Python 一起安裝。 若要檢查是否已安裝 pip，請從本機終端機執行 pip --version。 (視您在本機電腦上設定 Python 或 pip 的方式而定，您可能需要執行 pip3，而不是在整個文章中執行 pip。)

• dbx 0.8.0 版或更新版本。 您透過可以執行 pip install dbx，從 Python 套件索引 (PyPI) 安裝 dbx 套件。

  注意

  您現在不需要安裝 dbx。 您稍後可以在程式碼範例安裝一節中加以安裝。

• 建立 Python 虛擬環境的方法，以確保您在 dbx 專案中使用正確的 Python 版本和套件相依性。 本文涵蓋 pipenv。

• 使用驗證進行設定的 Databricks CLI 0.18 版或更舊版本。

  注意

  您現在不需要安裝舊版 Databricks CLI (Databricks CLI 0.17 版)。 您稍後可以在程式碼範例安裝一節中加以安裝。 如果您想要稍後進行安裝，您必須記得在該時間設定驗證。

• Visual Studio Code \(英文\)。

• 適用於 Visual Studio Code 的 Python 擴充功能。

• Visual Studio Code GitHub 提取要求和問題擴充功能。

• Git。

關於程式碼範例

本文的 Python 程式碼範例可在 GitHub 的 databricks/ide-best-practices 存放庫中取得，執行下列動作：

1. 從 GitHub 中的 owid/covid-19-data 存放庫取得資料。
2. 篩選特定 ISO 國家/地區代碼的資料。
3. 從資料建立樞紐表。
4. 對資料執行資料清理。
5. 將程式碼邏輯模組化為可重複使用的函式。
6. 單元測試函式。
7. 提供 dbx 專案組態和設定，讓程式碼能夠將資料寫入遠端 Azure Databricks 工作區中的 Delta 資料表。

設定範例程式碼

在您備妥此程式碼範例的需求之後，請完成下列步驟以開始使用程式碼範例。

注意

這些步驟不包含針對 CI/CD 設定此程式碼範例。 您不需要設定 CI/CD 來執行此程式碼範例。 如果您想要稍後設定 CI/CD，請參閱 使用 GitHub Actions 執行。

步驟 1：建立 Python 虛擬環境

1. 從終端機建立空白資料夾，以包含此程式碼範例的虛擬環境。 這些指示會使用名為 ide-demo 的父資料夾。 您可以為此資料夾指定任何名稱。 如果您使用不同的名稱，請取代本文中的名稱。 建立資料夾之後，請切換至該資料夾，然後從該資料夾啟動 Visual Studio Code。 請務必在 code 命令後面包含點 (.)。

   針對 Linux 與 macOS：

   mkdir ide-demo
   cd ide-demo
   code .
   

   提示

   如果您收到錯誤 command not found: code，請參閱 Microsoft 網站上的從命令列啟動。

   若為 Windows：

   md ide-demo
   cd ide-demo
   code .
   

2. 在 Visual Studio 的選單列上，按一下 [檢視 > 終端機]。

3. 從資料夾 ide-demo 的根目錄中，使用下列選項執行 pipenv 命令，其中 <version> 是您已在本機安裝的目標 Python 版本 (理想為符合目標叢集 Python 版本的版本)，例如 3.8.14。

   pipenv --python <version>
   

   記下 Virtualenv location 命令輸出中的 pipenv 值，因為在下一個步驟中將需要該值。

4. 選取目標 Python 解譯器，然後啟動 Python 虛擬環境：

   1. 在選單列上，按一下 [檢視 > 命令選擇區]，輸入 Python: Select，然後按一下 [Python：選取解譯器]。

   2. 選取您剛才建立之 Python 虛擬環境路徑內的 Python 解譯器。 (此路徑會列為 Virtualenv location 命令輸出中的 pipenv 值。)

   3. 在選單列上，按一下 [檢視 > 命令選擇區]，輸入 Terminal: Create，然後按一下 [終端機：新增新終端機]。

   4. 請確定命令提示字元指出您位於殼層 pipenv 中。 若要確認，您應該會在命令提示字元之前看到類似 (<your-username>) 的內容。 如果沒有類似內容，請執行以下命令：

      pipenv shell
      

      若要結束 pipenv 殼層，請執行命令 exit，然後小括弧會消失。

   如需詳細資訊，請參閱 Visual Studio Code 文件中的在 VS Code 中使用 Python 環境環境 \(英文\)。

步驟 2：從 GitHub 複製程式碼範例

1. 在 Visual Studio Code 中，如果資料夾尚未開啟，請開啟 ide-demo 資料夾 ([檔案 > 開啟資料夾])。
2. 按一下 [檢視 > 命令選擇區]，輸入 Git: Clone，然後按一下 [Git：複製]。
3. 針對提供存放庫 URL 或挑選存放庫來源，輸入 https://github.com/databricks/ide-best-practices
4. 瀏覽至您的 ide-demo 資料夾，然後按一下 [選取存放庫位置]。

步驟 3：安裝程式碼範例的相依性

1. 安裝與 Python 版本相容的 dbx 版本和 Databricks CLI 0.18 版或更早版本。 若要這樣做，請在終端機的 Visual Studio Code 中，從已啟動 ide-demo 殼層的 pipenv 資料夾執行 (pipenv shell) 下列命令：

   pip install dbx
   

2. 確認已安裝 dbx。 若要這樣做，請執行下列命令：

   dbx --version
   

   如果傳回版本號碼，則已安裝 dbx。

   如果版本號碼低於 0.8.0，請執行下列命令以升級 dbx，然後再次檢查版本號碼：

   pip install dbx --upgrade
   dbx --version
   
   # Or ...
   python -m pip install dbx --upgrade
   dbx --version
   

3. 當您安裝 dbx時，也會自動安裝舊版 Databricks CLI (Databricks CLI 0.17 版)。 若要確認已安裝舊版 Databricks CLI (Databricks CLI 0.17 版)，請執行下列命令：

   databricks --version
   

   如果傳回 Databricks CLI 0.17 版，則會安裝舊版 Databricks CLI。

4. 如果您尚未使用驗證設定舊版 Databricks CLI (Databricks CLI 0.17 版)，您現在必須執行此動作。 若要確認已設定驗證，請執行下列基本命令，以取得 Azure Databricks 工作區的一些摘要資訊。 請務必在 ls 子命令後面包含斜線 (/)：

   databricks workspace ls /
   

   如果傳回工作區的根層級資料夾名稱清單，則會設定驗證。

5. 安裝此程式碼範例相依的 Python 套件。 若要這樣做，請從 ide-demo/ide-best-practices 資料夾執行下列命令：

   pip install -r unit-requirements.txt
   

6. 確認已安裝程式碼範例的相依套件。 若要這樣做，請執行下列命令：

   pip list
   

   如果 requirements.txt 和 unit-requirements.txt 檔案中列出的套件在此清單中的某處，則會安裝相依套件。

   注意

   在 requirements.txt 中列出的檔案適用於特定套件版本。 為了獲得更好的相容性，您可以使用您希望 Azure Databricks 工作區用於稍後執行部署的叢集節點類型，來交叉參考這些版本。 請參閱 Databricks Runtime 版本資訊版本和相容性中叢集 Databricks Runtime 版本的「系統環境」一節。

步驟 4：自訂 Azure Databricks 工作區的程式碼範例

1. 自訂 dbx 存放庫的專案設定。 若要這樣做，請在 .dbx/project.json 檔案中，將 profile 物件的值從 DEFAULT 變更為符合您使用舊版 Databricks CLI 進行驗證的設定檔名稱 (Databricks CLI 0.17 版)。 如果您未設定任何非預設設定檔，請保留 DEFAULT 為預設值。 例如：

   {
     "environments": {
       "default": {
         "profile": "DEFAULT",
         "storage_type": "mlflow",
         "properties": {
           "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
           "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
         }
       }
     },
     "inplace_jinja_support": false
   }
   

2. 自訂 dbx 專案的部署設定。 若要這樣做，請在 conf/deployment.yml 檔案中，將 spark_version 和 node_type_id 物件的值從 10.4.x-scala2.12 和 m6gd.large 變更為您想要 Azure Databricks 工作區用來執行部署的 Azure Databricks 運行時間版本字元串和叢集節點類型。

   例如，若要指定 Databricks Runtime 10.4 LTS 和 Standard_DS3_v2 節點類型：

   environments:
     default:
       workflows:
         - name: "covid_analysis_etl_integ"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
           node_type_id: "Standard_DS3_v2"
           spark_python_task:
             python_file: "file://jobs/covid_trends_job.py"
         - name: "covid_analysis_etl_prod"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
             node_type_id: "Standard_DS3_v2"
             spark_python_task:
               python_file: "file://jobs/covid_trends_job.py"
             parameters: ["--prod"]
         - name: "covid_analysis_etl_raw"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
             node_type_id: "Standard_DS3_v2"
             spark_python_task:
               python_file: "file://jobs/covid_trends_job_raw.py"
   

提示

在此範例中，這三個作業定義的每一個都有相同的 spark_version 和 node_type_id 值。 您可以將不同的值用於不同的作業定義。 您也可以建立共用值，並橫跨作業定義重複使用它們，以減少輸入錯誤和程式碼維護。 請參閱 dbx 文件中的 YAML 範例。

探討程式碼範例

設定程式碼範例之後，請使用下列資訊來了解 ide-demo/ide-best-practices 資料夾中各種檔案的運作方式。

程式碼模組化

未修改的程式碼

jobs/covid_trends_job_raw.py 檔案是程式碼邏輯的未修改版本。 您可以自行執行此檔案。

模組化的程式碼

jobs/covid_trends_job.py 檔案是程式碼邏輯的模組化版本。 此檔案依賴 covid_analysis/transforms.py 檔案中的共用程式碼。 covid_analysis/__init__.py 檔案會將 covide_analysis 資料夾視為包含的套件。

測試

單元測試

tests/testdata.csv 檔案包含 covid-hospitalizations.csv 檔案中一小部分資料以供測試之用。 tests/transforms_test.py 檔案包含 covid_analysis/transforms.py 檔案的單元測試。

單元測試執行器

pytest.ini 檔案包含使用 pytest 執行測試的設定選項。 請參閱 pytest 文件中的 pytest.ini 和組態選項。

此 .coveragerc 檔案包含 Python 程式碼涵蓋範圍測量的設定選項，其中包含 coverage.py。 請參閱 coverage.py 檔中的設定參考。

requirements.txt 檔案是您稍早使用 pip 執行的 unit-requirements.txt 檔案子集，包含單元測試也相依的套件清單。

包裝

setup.py 檔案會提供命令，以在控制台 (控制台指令碼) 上執行，例如命令 pip，以使用 setuptools 封裝 Python 專案。 請參閱 setuptools 檔中的進入點。

其他檔案

此程式碼範例中有其他尚未描述的檔案：

• .github/workflows 資料夾包含 databricks_pull_request_tests.yml、onpush.yml 和 onrelease.yaml 三個檔案，其代表 GitHub Actions，稍後會在 GitHub Actions 一節中說明。
• .gitignore 檔案包含 Git 針對存放庫忽略的本機資料夾和檔案清單。

執行程式碼範例

您可以在本機電腦上使用 dbx，指示 Azure Databricks 依需求在遠端工作區中執行程式碼範例，如下一個子章節所述。 或者，您可以使用 GitHub Actions 讓 GitHub 每次將程式碼變更推送至 GitHub 存放庫時，執行程式碼範例。

使用 dbx 執行

1. 從 covid_analysis 專案的根目錄執行下列命令，以 Python setuptools 開發模式將 dbx 資料夾的內容安裝為套件 (例如 ide-demo/ide-best-practices 資料夾)。 請務必此命令的結尾包含點 (.)：

   pip install -e .
   

   此命令會建立 covid_analysis.egg-info 資料夾，其中包含與 covid_analysis/__init__.py 和 covid_analysis/transforms.py 檔案的編譯版本的相關資訊。

2. 執行下列命令來執行測試：

   pytest tests/
   

   測試結果會顯示在終端機中。 這四個測試都應該顯示為通過。

   提示

   如需測試的其他方法，包括 R 和 Scala 筆記本的測試，請參閱筆記本的單元測試。

3. 或者，執行下列命令，以取得測試的測試涵蓋範圍計量：

   coverage run -m pytest tests/
   

   注意

   如果訊息顯示找不到 coverage，請執行 pip install coverage，然後再試一次。

   若要檢視測試涵蓋範圍結果，請執行下列命令：

   coverage report -m
   

4. 如果這四個測試都通過，請執行下列命令，將 dbx 專案的內容傳送至您的 Azure Databricks 工作區：

   dbx deploy --environment=default
   

   專案及其執行的相關資訊會傳送至 workspace_directory 檔案 .dbx/project.json 物件中指定的位置。

   專案的內容會傳送至 artifact_location 檔案 .dbx/project.json 物件中指定的位置。

5. 執行下列命令，在工作區中執行程式碼的生產前版本：

   dbx launch covid_analysis_etl_integ
   

   執行結果的連結會顯示在終端機中。 其外觀應該如下所示：

   https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
   

   在網頁瀏覽器中遵循此連結，以查看工作區中的執行結果。

6. 執行下列命令，在工作區中執行程式碼的生產版本：

   dbx launch covid_analysis_etl_prod
   

   執行結果的連結會顯示在終端機中。 其外觀應該如下所示：

   https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
   

   在網頁瀏覽器中遵循此連結，以查看工作區中的執行結果。

使用 GitHub Actions 執行

在專案的 .github/workflows 資料夾中，onpush.yml 和 onrelease.yml GitHub Actions 檔案會執行下列動作：

• 在每個至開頭為 v 標記的推送上，會使用 dbx 來部署 covid_analysis_etl_prod 作業。
• 在不是開頭為 v 標記的每個推播上：
  1. 使用 pytest 來執行單元測試。
  2. 使用 dbx 將 covid_analysis_etl_integ 作業中指定的檔案部署到遠端工作區。
  3. 使用 dbx 啟動遠端工作區上 covid_analysis_etl_integ 作業中指定的已部署檔案，追蹤此執行直到完成為止。

注意

另外提供一個 databricks_pull_request_tests.yml GitHub Actions 檔案作為範本，讓您在不會影響 onpush.yml 和 onrelease.yml GitHub Actions 檔案的情況下進行實驗。 您可以在不需要 databricks_pull_request_tests.yml GitHub Actions 檔案的情況下，執行此程式碼範例。 本文未涵蓋其使用方式。

下列子章節說明如何設定及執行 onpush.yml 和 onrelease.yml GitHub Actions 檔案。

設定以使用 GitHub Actions

遵循 CI/CD 服務主體中的指示，設定您的 Azure Databricks 工作區。 此包括下列動作：

1. 建立服務主體。
2. 為服務主體建立 Microsoft Entra ID 權杖。

作為安全性最佳作法，Databricks 建議您針對服務主體使用 Microsoft Entra ID 權杖，讓 GitHub 向 Azure Databricks 工作區進行驗證，而不是針對工作區使用者使用 Databricks 個人存取權杖。

建立服務主體及其 Microsoft Entra ID 權杖之後，請停止並記下下一節將使用的 Microsoft Entra ID 權杖值。

執行 GitHub Action

步驟 1：發佈複製的存放庫

1. 在 Visual Studio Code 的側邊欄中，按下 GitHub 圖示。 如果看不到圖示，請先透過延伸模組檢視 ([檢視>延伸模組]) 啟用 GitHub 提取要求和問題延伸模組。
2. 如果可以看到 [登入] 按鈕，請按下該按鈕，然後依照畫面上的指示登入您的 GitHub 帳戶。
3. 在功選單列上，按一下 [檢視 > 命令選擇區]，輸入 Publish to GitHub，然後按一下 [發佈至 GitHub]。
4. 選取選項，以將複製的存放庫發佈至 GitHub 帳戶。

步驟 2：將加密的秘密新增至存放庫

在已發佈存放庫的 GitHub 網站中，遵循為存放庫建立加密密碼中的指示，以取得下列加密的秘密：

• 建立名為 DATABRICKS_HOST 的加密密碼，設定為每個工作區 URL 的值，例如 https://adb-1234567890123456.7.azuredatabricks.net。
• 建立名為 DATABRICKS_TOKEN 的加密密碼，設定為服務主體 Microsoft Entra ID 權杖的值。

步驟 3：建立分支並將其發佈至存放庫

1. 在 Visual Studio Code 的 [原始檔控制] 檢視 ([檢視 > 原始檔控制]) 中，按一下 [...] ([檢視和更多動作]) 圖示。
2. 按一下 [分支 > 建立分支的來源]。
3. 輸入分支的名稱，例如 my-branch。
4. 選取要從中建立分支的分支，例如 main。
5. 對本機存放庫中的其中一個檔案進行細微變更，然後儲存檔案。 例如，對 tests/transforms_test.py 檔案中的程式碼備註進行細微變更。
6. 在 [原始檔控制] 檢視中，再次按一下 [...] ([檢視和更多動作]) 圖示。
7. 按一下 [變更 > 階段所有變更]。
8. 再次按一下 [...] (檢視和更多動作) 圖示。
9. 按一下 [提交 > 分段提交]。
10. 輸入訊息作為提交。
11. 再次按一下 [...] (檢視和更多動作) 圖示。
12. 按一下 [分支 > 發佈分支]。

步驟 4：建立提取要求和合併

1. 前往您已發佈 https://github/<your-GitHub-username>/ide-best-practices 存放庫的 GitHub 網站。
2. 在 [提取要求] 索引標籤上，在 [my-branch 有最近的推送] 旁，按一下 [比較和提取要求]。
3. 按一下 [建立提取要求]。
4. 在提取要求頁面上，等候 CI pipleline / ci-pipeline (推送) 旁的圖示顯示綠色複選標記。 (可能需要幾分鐘的時間，才會顯示圖示。)如果有紅色 X 而非綠色複選標記，請按一下 [詳細資料] 以找出原因。 如果圖示或詳細資料不再顯示，請按一下 [顯示所有檢查]。
5. 如果出現綠色複選標記，請按一下 [合併提取要求]，將提取要求合併至分支 main。