適用於 Python 的 Databricks SDK

發行項
04/30/2024

在本文中，您將瞭解如何使用適用於 Python 的 Databricks SDK，將 Azure Databricks 帳戶、工作區和相關資源的作業自動化。本文補充了適用於 Python 的 Databricks SDK 檔，請參閱 GitHub 中 Databricks SDK for Python 存放庫中的 Docs 和程式碼範例。

注意

這項功能在 Beta 中，而且可在生產環境中使用。

在 Beta 期間，Databricks 建議您釘選相依於程式代碼所依賴之適用於 Python 之 Databricks SDK 的特定次要版本。例如，您可以在、或 pyproject.tomlpoetry.lock 詩歌等requirements.txtvenv檔案中釘選相依性。如需釘選相依性的詳細資訊，請參閱的venv虛擬環境和套件，或安裝詩歌的相依性。

開始之前

您可以從 Azure Databricks Notebook 或本機開發計算機，使用適用於 Python 的 Databricks SDK。

若要從 Azure Databricks 筆記本內使用適用於 Python 的 Databricks SDK，請跳至從 Azure Databricks 筆記本使用適用於 Python 的 Databricks SDK。
若要從本機開發計算機使用適用於 Python 的 Databricks SDK，請完成本節中的步驟。

開始使用適用於 Python 的 Databricks SDK 之前，您的開發電腦必須具有：

已設定 Azure Databricks 驗證。
已安裝 Python 3.8 或更高版本。為了自動化 Azure Databricks 計算資源，Databricks 建議您已安裝與目標 Azure Databricks 計算資源上安裝的 Python 主要和次要版本相符。本文的範例依賴使用已安裝 Python 3.10 的 Databricks Runtime 13.3 LTS 來自動化叢集。如需正確的版本，請參閱 Databricks Runtime 版本資訊，以及叢集 Databricks Runtime 版本的相容性。
Databricks 建議您為與適用於 Python 的 Databricks SDK 搭配使用的每個 Python 程式代碼專案建立並啟用 Python 虛擬環境 。 Python 虛擬環境有助於確保您的程式碼專案使用相容的 Python 和 Python 套件版本（在此案例中為適用於 Python 的 Databricks SDK 套件）。本文說明如何針對 Python 虛擬環境使用 venv 或 Potetry 。

使用建立 Python 虛擬環境 `venv`

從終端機設定為 Python 程式代碼專案的根目錄，執行下列命令。此命令會 venv 指示針對虛擬環境使用 Python 3.10，然後在 Python 程式代碼專案的根目錄中 .venv ，建立虛擬環境的支援檔案。
```
# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv
```
使用 venv 來啟用虛擬環境。請參閱 venv 檔，以取得正確的命令，以根據您的作業系統和終端機類型使用。例如，在執行的macOS zsh上：
```
source ./.venv/bin/activate
```
當虛擬環境的名稱（例如，）顯示在終端機提示前的括弧中時， .venv您將知道您的虛擬環境已啟動。

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

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

請跳到開始使用適用於 Python 的 Databricks SDK。

使用詩歌建立虛擬環境

安裝詩歌，如果您尚未這麼做。
從終端機設定為 Python 程式代碼專案的根目錄，執行下列命令以指示 poetry 初始化 Poetry 的 Python 程式代碼專案。
```
poetry init
```
詩歌顯示數個提示，讓你完成。這些提示都不是適用於 Python 的 Databricks SDK 專屬。如需這些提示的相關信息，請參閱 init。
完成提示之後，Poetry 會將檔案 pyproject.toml 新增至 Python 專案。如需檔案的相關信息 pyproject.toml ，請參閱 pyproject.toml 檔案。
如果您的終端機仍設定為 Python 程式代碼專案的根目錄，請執行下列命令。此命令會 poetry 指示讀取 pyproject.toml 檔案、安裝和解析相依性、建立 poetry.lock 檔案來鎖定相依性，最後建立虛擬環境。
```
poetry install
```
從終端機設定為 Python 程式代碼專案的根目錄，執行下列命令以指示 poetry 啟動虛擬環境並輸入殼層。
```
poetry shell
```
您將知道您的虛擬環境已啟動，而且當虛擬環境的名稱顯示在終端機提示前的括弧中時，會輸入殼層。

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

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

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

開始使用適用於 Python 的 Databricks SDK

本節說明如何從本機開發計算機開始使用適用於 Python 的 Databricks SDK。若要從 Azure Databricks 筆記本內使用適用於 Python 的 Databricks SDK，請跳至從 Azure Databricks 筆記本使用適用於 Python 的 Databricks SDK。

在已設定 Azure Databricks 驗證的開發計算機上，已安裝 Python，且已啟動 Python 虛擬環境，從 Python 套件索引（PyPI）安裝 databricks-sdk 套件（及其相依性），如下所示：

Venv

使用 pip 來安裝 databricks-sdk 套件。（在某些系統上，您可能需要將取代 pip3 為 pip，這裡和整個。
```
pip3 install databricks-sdk
```
詩歌
```
poetry add databricks-sdk
```
若要在適用於 Python 的 databricks-sdk Databricks SDK 處於 Beta 版時安裝特定版本的套件，請參閱套件的發行歷程記錄。例如，若要安裝版本 0.1.6：

Venv
```
pip3 install databricks-sdk==0.1.6
```
詩歌
```
poetry add databricks-sdk==0.1.6
```
提示

若要將 Databricks SDK for Python 套件的現有安裝升級為最新版本，請執行下列命令：

Venv
```
pip3 install --upgrade databricks-sdk
```
詩歌
```
poetry add databricks-sdk@latest
```
若要顯示適用於 Python 套件的 Databricks SDK 目前 Version 和其他詳細數據，請執行下列命令：

Venv
```
pip3 show databricks-sdk
```
詩歌
```
poetry show databricks-sdk
```
在您的 Python 虛擬環境中，建立 Python 程式代碼檔案，以匯入適用於 Python 的 Databricks SDK。下列範例會在名為 main.py 且具有下列內容的檔案中，只列出 Azure Databricks 工作區中的所有叢集：
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)
```
執行命令，以執行名為 main.pypython 的檔案來執行 Python 程式代碼檔案：

Venv
```
python3.10 main.py
```
詩歌

如果您位於虛擬環境的殼層中：
```
python3.10 main.py
```
如果您不在虛擬環境的殼層中：
```
poetry run python3.10 main.py
```
注意

透過上述呼叫 w = WorkspaceClient()中未設定任何自變數，適用於 Python 的 Databricks SDK 會使用其預設程式嘗試執行 Azure Databricks 驗證。若要覆寫此預設行為，請參閱下列驗證一節。

使用 Azure Databricks 帳戶或工作區驗證適用於 Python 的 Databricks SDK

本節說明如何將適用於 Python 的 Databricks SDK 從本機開發計算機驗證到 Azure Databricks 帳戶或工作區。若要從 Azure Databricks 筆記本內驗證適用於 Python 的 Databricks SDK，請直接跳至從 Azure Databricks Notebook 使用適用於 Python 的 Databricks SDK。

適用於 Python 的 Databricks SDK 會 實作 Databricks 用戶端統一驗證 標準，這是一種整合且一致的架構和驗證程式設計方法。這種方法有助於使用 Azure Databricks 更集中且可預測的方式來設定和自動化驗證。它可讓您設定 Databricks 驗證一次，然後在多個 Databricks 工具和 SDK 之間使用該組態，而不需要進一步的驗證組態變更。如需詳細資訊，包括 Python 中更完整的程式代碼範例，請參閱 Databricks 用戶端整合驗證。

注意

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

使用適用於 Python 的 Databricks SDK 初始化 Databricks 驗證的一些可用編碼模式包括：

執行下列其中一項動作，使用 Databricks 預設驗證：
- 建立或識別具有目標 Databricks 驗證類型所需字段的自定義 Databricks 組態配置檔。然後將環境變數設定 DATABRICKS_CONFIG_PROFILE 為自定義組態配置檔的名稱。
- 設定目標 Databricks 驗證類型所需的環境變數。
然後具現化，例如 WorkspaceClient 具有 Databricks 預設驗證的物件，如下所示：
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...
```
支援硬式編碼所需的字段，但不建議這麼做，因為它可能會暴露程序代碼中的敏感性資訊，例如 Azure Databricks 個人存取令牌。下列範例硬式編碼 Azure Databricks 主機和 Databricks 令牌驗證的存取令牌值：
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host  = 'https://...',
  token = '...'
)
# ...
```

另請參閱 Databricks SDK for Python 檔中的驗證。

從 Azure Databricks 筆記本使用適用於 Python 的 Databricks SDK

您可以從已安裝適用於 Python 的 Databricks SDK 連結 Azure Databricks 叢集的 Azure Databricks 筆記本呼叫適用於 Python 的 Databricks SDK 功能。 Databricks SDK for Python 已經安裝在使用 Databricks Runtime 13.3 LTS 或更新版本的所有 Azure Databricks 叢集上。針對使用 Databricks Runtime 12.2 LTS 和以下的 Azure Databricks 叢集，您必須先安裝適用於 Python 的 Databricks SDK。請參閱步驟 1：安裝或升級適用於 Python 的 Databricks SDK。

若要查看預設針對 Databricks Runtime 版本所安裝的 Databricks SDK for Python 版本號碼，請參閱該 Databricks Runtime 版本的 Databricks Runtime 版本資訊中的<已安裝的 Python 連結庫>一節。

Databricks SDK for Python 0.6.0 和更新版本會使用預設的 Azure Databricks Notebook 驗證。默認 Azure Databricks Notebook 驗證仰賴 Azure Databricks 個人存取令牌，Azure Databricks 會在背景自動產生供自己使用。 Azure Databricks 會在筆記本停止執行之後刪除此暫存令牌。

重要

默認的 Azure Databricks Notebook 驗證僅適用於叢集的驅動程序節點上，而不適用於任何叢集的背景工作或執行程序節點。

Databricks Runtime 13.3 LTS 和更新版本支援使用適用於 Python 0.1.7 或更新版本之 Databricks SDK 的預設 Azure Databricks Notebook 驗證。 Databricks Runtime 10.4 LTS 和更新版本支援安裝 Databricks SDK for Python 0.1.10 或更新版本的預設 Azure Databricks Notebook 驗證。不過，不論 Databricks 運行時間版本為何，Databricks 建議安裝或升級至適用於 Python 0.6.0 或更新版本的 Databricks SDK，以達到預設 Azure Databricks Notebook 驗證的最大相容性。

如果您想要呼叫 Azure Databricks 帳戶層級 API，或是想要使用預設 Azure Databricks Notebook 驗證以外的 Azure Databricks 驗證類型，則必須在 Azure Databricks 叢集上安裝或升級適用於 Python 的 Databricks SDK，如下所示：

驗證類型	適用於 Python 版本的 Databricks SDK
OAuth 機器對機器 (M2M) 驗證	0.18.0 和更新版本
OAuth 使用者對電腦（U2M）驗證	0.19.0 和更新版本
Microsoft Entra ID 服務主體驗證	所有版本
Azure CLI 驗證	所有版本
Databricks 個人存取令牌驗證	所有版本

尚不支援 Azure 受控識別驗證。

Azure Databricks Notebook 驗證不適用於 Azure Databricks 組態配置檔。

步驟 1：安裝或升級適用於 Python 的 Databricks SDK

Azure Databricks Python 筆記本可以使用 Databricks SDK for Python，就像任何其他 Python 連結庫一樣。若要在連結的 Azure Databricks 叢集上安裝或升級適用於 Python 的 Databricks SDK 連結庫，請從筆記本數據格執行 %pip magic 命令，如下所示：
```
%pip install databricks-sdk --upgrade
```
執行 %pip magic 命令之後，您必須重新啟動 Python，才能將已安裝或升級的連結庫提供給筆記本使用。若要這樣做，請使用magic命令，立即從筆記本數據格 %pip 執行下列命令：
```
dbutils.library.restartPython()
```
若要顯示適用於 Python 的 Databricks SDK 已安裝版本，請從筆記本數據格執行下列命令：
```
%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
```

步驟 2：執行您的程式代碼

在您的筆記本數據格中，建立可匯入的 Python 程式代碼，然後呼叫適用於 Python 的 Databricks SDK。下列範例會使用預設的 Azure Databricks Notebook 驗證來列出 Azure Databricks 工作區中的所有叢集：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)

當您執行此數據格時，Azure Databricks 工作區中所有可用叢集的名稱清單隨即出現。

若要使用不同的 Azure Databricks 驗證類型，請參閱支援的 Azure Databricks 驗證類型，然後按兩下對應的連結以取得其他技術詳細數據。

使用 Databricks 公用程式

您可以從在本機開發計算機上執行的 Databricks SDK 或 Azure Databricks Notebook 內執行的 Python 程式代碼呼叫 Databricks 公用程式（dbutils）參考。

從本機開發計算機，Databricks Utilities 只能 dbutils.fs存取、 dbutils.secrets、 dbutils.widgets和 dbutils.jobs 命令群組。
從連結至 Azure Databricks 叢集的 Azure Databricks Notebook 中，Databricks 公用程式可以存取所有可用的 Databricks Utilities 命令群組，而不只是 dbutils.fs、 dbutils.secrets和 dbutils.widgets。此外， dbutils.notebook 命令群組僅限於兩個層級的命令，例如 dbutils.notebook.run 或 dbutils.notebook.exit。

若要從本機開發計算機或 Azure Databricks Notebook 呼叫 Databricks 公用程式，請在 dbutils 中使用 WorkspaceClient。此程式代碼範例會使用預設的 Azure Databricks Notebook 驗證來呼叫 dbutils ， WorkspaceClient 以列出工作區之 DBFS 根目錄中所有對象的路徑。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
d = w.dbutils.fs.ls('/')

for f in d:
  print(f.path)

或者，您可以直接呼叫 dbutils 。不過，您只能使用預設的 Azure Databricks Notebook 驗證。此程式代碼範例會直接呼叫 dbutils 以列出工作區之 DBFS 根目錄中的所有物件。

from databricks.sdk.runtime import *

d = dbutils.fs.ls('/')

for f in d:
  print(f.path)

您無法單獨使用 dbutils 或內部 WorkspaceClient 來存取 Unity 目錄磁碟區。請改用 files 在內 WorkspaceClient。此程式代碼範例會在內WorkspaceClient呼叫 files ，以列印指定磁碟區中指定檔案的內容。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

resp = w.files.download('/Volumes/main/default/my-volume/sales.csv')
print(str(resp.contents.read(), encoding='utf-8'))

另請參閱與 dbutils 的互動。

程式碼範例

下列程式代碼範例示範如何使用適用於 Python 的 Databricks SDK 來建立和刪除叢集、執行作業，以及列出帳戶層級群組。這些程式代碼範例會使用預設的 Azure Databricks Notebook 驗證。如需預設 Azure Databricks Notebook 驗證的詳細資訊，請參閱從 Azure Databricks Notebook 使用適用於 Python 的 Databricks SDK。如需筆記本外部預設驗證的詳細資訊，請參閱使用 Azure Databricks 帳戶或工作區驗證適用於 Python 的 Databricks SDK。

如需其他程式代碼範例，請參閱 GitHub 中適用於 Python 的 Databricks SDK 存放庫中的範例。另請參閱：

Databricks 工作區 API 參考
Databricks 帳戶 API 參考
建立叢集
永久刪除叢集
建立作業
建立使用無伺服器計算的作業
列出帳戶層級群組

建立叢集

此程式代碼範例會建立具有指定 Databricks Runtime 版本和叢集節點類型的叢集。此叢集有一個背景工作角色，且叢集會在閑置時間 15 分鐘後自動終止。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

print("Attempting to create cluster. Please wait...")

c = w.clusters.create_and_wait(
  cluster_name             = 'my-cluster',
  spark_version            = '12.2.x-scala2.12',
  node_type_id             = 'Standard_DS3_v2',
  autotermination_minutes  = 15,
  num_workers              = 1
)

print(f"The cluster is now ready at " \
      f"{w.config.host}#setting/clusters/{c.cluster_id}/configuration\n")

永久刪除叢集

此程式代碼範例會從工作區中永久刪除具有指定叢集標識符的叢集。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

c_id = input('ID of cluster to delete (for example, 1234-567890-ab123cd4): ')

w.clusters.permanent_delete(cluster_id = c_id)

建立作業

此程式代碼範例會建立 Azure Databricks 作業，以在指定的叢集上執行指定的筆記本。當程式代碼執行時，它會從終端機的使用者取得現有的筆記本路徑、現有的叢集標識碼和相關作業設定。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import Task, NotebookTask, Source

w = WorkspaceClient()

job_name            = input("Some short name for the job (for example, my-job): ")
description         = input("Some short description for the job (for example, My job): ")
existing_cluster_id = input("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4): ")
notebook_path       = input("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook): ")
task_key            = input("Some key to apply to the job's tasks (for example, my-key): ")

print("Attempting to create the job. Please wait...\n")

j = w.jobs.create(
  name = job_name,
  tasks = [
    Task(
      description = description,
      existing_cluster_id = existing_cluster_id,
      notebook_task = NotebookTask(
        base_parameters = dict(""),
        notebook_path = notebook_path,
        source = Source("WORKSPACE")
      ),
      task_key = task_key
    )
  ]
)

print(f"View the job at {w.config.host}/#job/{j.job_id}\n")

建立使用無伺服器計算的作業

重要

工作流程的無伺服器計算處於公開預覽狀態。如需資格和啟用的相關信息，請參閱啟用無伺服器計算公開預覽。

下列範例會建立使用無伺服器計算工作流程的作業：

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import NotebookTask, Source, Task

w = WorkspaceClient()

j = w.jobs.create(
  name = "My Serverless Job",
  tasks = [
    Task(
      notebook_task = NotebookTask(
      notebook_path = "/Users/user@databricks.com/MyNotebook",
      source = Source("WORKSPACE")
      ),
      task_key = "MyTask",
   )
  ]
)

列出帳戶層級群組

此程式代碼範例會列出 Azure Databricks 帳戶內所有可用群組的顯示名稱。

from databricks.sdk import AccountClient

a = AccountClient()

for g in a.groups.list():
  print(g.display_name)

測試

若要測試程序代碼，請使用 Python 測試架構，例如 pytest。若要在模擬條件下測試程序代碼，而不呼叫 Azure Databricks REST API 端點，或變更 Azure Databricks 帳戶或工作區的狀態，請使用 Python 模擬連結庫，例如 unittest.mock。

例如，假設下列名為 helpers.py 的檔案，其中包含 create_cluster 傳回新叢集相關信息的函式：

# helpers.py

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.compute import ClusterDetails

def create_cluster(
  w: WorkspaceClient,
  cluster_name:            str,
  spark_version:           str,
  node_type_id:            str,
  autotermination_minutes: int,
  num_workers:             int
) -> ClusterDetails:
  response = w.clusters.create(
    cluster_name            = cluster_name,
    spark_version           = spark_version,
    node_type_id            = node_type_id,
    autotermination_minutes = autotermination_minutes,
    num_workers             = num_workers
  )
  return response

並指定下列名為的檔案，該檔案會 main.py 呼叫函 create_cluster 式：

# main.py

from databricks.sdk import WorkspaceClient
from helpers import *

w = WorkspaceClient()

# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = create_cluster(
  w = w,
  cluster_name            = 'Test Cluster',
  spark_version           = '<spark-version>',
  node_type_id            = '<node-type-id>',
  autotermination_minutes = 15,
  num_workers             = 1
)

print(response.cluster_id)

下列名為 test_helpers.py 的檔案會測試函 create_cluster 式是否傳回預期的回應。此測試會模擬 WorkspaceClient 物件、定義模擬對象的設定，然後將模擬物件傳遞至 create_cluster 函式，而不是在目標工作區中建立叢集。然後測試會檢查函式是否傳回新模擬叢集的預期標識碼。

# test_helpers.py

from databricks.sdk import WorkspaceClient
from helpers import *
from unittest.mock import create_autospec # Included with the Python standard library.

def test_create_cluster():
  # Create a mock WorkspaceClient.
  mock_workspace_client = create_autospec(WorkspaceClient)

  # Set the mock WorkspaceClient's clusters.create().cluster_id value.
  mock_workspace_client.clusters.create.return_value.cluster_id = '123abc'

  # Call the actual function but with the mock WorkspaceClient.
  # Replace <spark-version> with the target Spark version string.
  # Replace <node-type-id> with the target node type string.
  response = create_cluster(
    w = mock_workspace_client,
    cluster_name            = 'Test Cluster',
    spark_version           = '<spark-version>',
    node_type_id            = '<node-type-id>',
    autotermination_minutes = 15,
    num_workers             = 1
  )

  # Assert that the function returned the mocked cluster ID.
  assert response.cluster_id == '123abc'

若要執行此測試，請從程式代碼專案的根目錄執行 pytest 命令，其應該會產生類似下列的測試結果：

$ pytest
=================== test session starts ====================
platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.4.0
rootdir: <project-rootdir>
collected 1 item

test_helpers.py . [100%]
======================== 1 passed ==========================

其他資源

如需詳細資訊，請參閱

Share via

適用於 Python 的 Databricks SDK

開始之前

使用建立 Python 虛擬環境 `venv`

使用詩歌建立虛擬環境

開始使用適用於 Python 的 Databricks SDK

Venv

詩歌

Venv

詩歌

Venv

詩歌

Venv

詩歌

Venv

詩歌

使用 Azure Databricks 帳戶或工作區驗證適用於 Python 的 Databricks SDK

從 Azure Databricks 筆記本使用適用於 Python 的 Databricks SDK

步驟 1：安裝或升級適用於 Python 的 Databricks SDK

步驟 2：執行您的程式代碼

使用 Databricks 公用程式

程式碼範例

建立叢集

永久刪除叢集

建立作業

建立使用無伺服器計算的作業

列出帳戶層級群組

測試

其他資源

意見反應

意見反應

其他資源

Share via

適用於 Python 的 Databricks SDK

開始之前

使用 建立 Python 虛擬環境 venv

使用詩歌建立虛擬環境

開始使用適用於 Python 的 Databricks SDK

Venv

詩歌

Venv

詩歌

Venv

詩歌

Venv

詩歌

Venv

詩歌

使用 Azure Databricks 帳戶或工作區驗證適用於 Python 的 Databricks SDK

從 Azure Databricks 筆記本使用適用於 Python 的 Databricks SDK

步驟 1：安裝或升級適用於 Python 的 Databricks SDK

步驟 2：執行您的程式代碼

使用 Databricks 公用程式

程式碼範例

建立叢集

永久刪除叢集

建立作業

建立使用無伺服器計算的作業

列出帳戶層級群組

測試

其他資源

意見反應

意見反應

其他資源

使用建立 Python 虛擬環境 `venv`