Databricks CLI (舊版)

文章
10/02/2024

重要

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

Databricks 建議您使用 Databricks CLI 0.205 版或更新版本，而不是舊版 Databricks CLI 0.18 版或更低版本。 Databricks 不支援 Databricks CLI 0.18 版或更低版本。如需有關 Databricks CLI 0.205 版和更新版本的資訊，請參閱什麼是 Databricks CLI？。

若要從 Databricks CLI 0.18 版或更低版本移轉至 Databricks CLI 0.205 版或更新版本，請參閱 Databricks CLI 移轉。

舊版 Databricks CLI 處於實驗狀態。 Databricks 目前不會為舊版 Databricks CLI 規劃新的功能。

Databricks 支援通道不支援舊版 Databricks CLI。若要提供意見反應、提出問題及回報問題，請使用 GitHub 中 Databricks 存放庫命令列介面中的問題索引標籤。

舊版 Databricks 命令列介面 (也稱為舊版 Databricks CLI) 是一個公用程式，可提供便於使用的介面，透過終端機、命令提示字元或自動化指令碼自動化 Azure Databricks 平台。

需求

Python 3 - 3.6 和更新版本
Python 2 - 2.7.9 和更新版本

重要

在 macOS 上，預設 Python 2 安裝未實作 TLSv1_2 通訊協定，並且透過此 Python 安裝執行舊版 Databricks CLI 將會導致錯誤：AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'。使用 Homebrew 安裝具有 ssl.PROTOCOL_TLSv1_2 的 Python 版本。

限制

不支援將舊版 Databricks CLI 與啟用了防火牆的儲存體容器搭配使用。 Databricks 建議您使用 Databricks Connect 或 az storage。

設定 CLI

本節說明如何設定舊版 Databricks CLI。

安裝或更新 CLI

本節說明如何安裝或更新開發電腦，以執行舊版 Databricks CLI。

安裝 CLI

使用適合您的 Python 安裝的 pip install databricks-cli 版本執行 pip：

pip install databricks-cli

更新 CLI

使用適合您的 Python 安裝的 pip install databricks-cli --upgrade 版本執行 pip：

pip install databricks-cli --upgrade

若要列出目前安裝的舊版 Databricks CLI 版本，請執行 databricks --version：

databricks --version

設定驗證

您必須先設定舊版 Databricks CLI 與 Azure Databricks 之間的驗證，然後才能執行舊版 Databricks CLI 命令。本節說明如何設定舊版 Databricks CLI 的驗證。

若要使用舊版 Databricks CLI 進行驗證，您可以使用 Databricks 個人存取權杖或 Microsoft Entra ID (先前稱為 Azure Active Directory) 權杖。

注意

作為安全性最佳做法，當您使用自動化工具、系統、指令碼和應用程式進行驗證時，Databricks 建議您使用屬於服務主體的個人存取權杖，而不是工作區使用者。若要建立服務主體的權杖，請參閱管理服務主體的權杖。

使用 Microsoft Entra ID 權杖設定驗證

若要使用 Microsoft Entra ID 權杖設定舊版 Databricks CLI，請產生 Microsoft Entra ID (先前稱為 Azure Active Directory) 權杖，並將其儲存在環境變數 DATABRICKS_AAD_TOKEN 中。

執行以下命令：

databricks configure --aad-token

此命令會發出提示：

Databricks Host (should begin with https://):

輸入個別工作區 URL，格式為 https://adb-<workspace-id>.<random-number>.azuredatabricks.net。若要取得個別工作區 URL，請參閱個別工作區 URL。

完成提示之後，您的存取認證會儲存在 Linux 或 macOS 上的檔案 ~/.databrickscfg 中，或儲存在 Windows 上的 %USERPROFILE%\.databrickscfg 中。檔案包含預設設定檔項目：

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

如果 .databrickscfg 檔案已存在，該檔案的 DEFAULT 組態設定檔會以新的資料覆寫。若要改為使用不同的名稱建立組態設定檔，請參閱連線設定檔。

使用 Databricks 個人存取權杖設定驗證

若要設定舊版 Databricks CLI 以使用個人存取權杖，請執行下列命令：

databricks configure --token

此命令會首先發出提示：

Databricks Host (should begin with https://):

輸入個別工作區 URL，格式為 https://adb-<workspace-id>.<random-number>.azuredatabricks.net。若要取得個別工作區 URL，請參閱個別工作區 URL。

此命令會繼續發出提示，要求您輸入個人存取權杖：

Token:

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

如果 .databrickscfg 檔案已存在，該檔案的 DEFAULT 組態設定檔會以新的資料覆寫。若要改為使用不同的名稱建立組態設定檔，請參閱連線設定檔。

對於 CLI 0.8.1 和更新版本，您可以透過設定環境變數 DATABRICKS_CONFIG_FILE 來變更此檔案的路徑。

Linux 或 macOS

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

重要

從 CLI 0.17.2 開始，CLI 不適用於 .netrc 檔案。您的環境中可以有一個 .netrc 檔案用於其他用途，但 CLI 不會使用該 .netrc 檔案。

CLI 0.8.0 和更新版本支援下列 Azure Databricks 環境變數：

DATABRICKS_HOST
DATABRICKS_TOKEN

環境變數設定優先於組態檔案中的設定。

測試您的驗證設定

若要檢查是否已正確設定驗證，您可以執行如下所示的命令：

databricks fs ls dbfs:/

如果成功，此命令會列出與 DEFAULT 設定檔關聯的工作區的 DBFS 根目錄中的檔案和目錄。

連線設定檔

舊版 Databricks CLI 組態支援多個連線設定檔。舊版 Databricks CLI 的相同安裝可用於對多個 Azure Databricks 工作區進行 API 呼叫。

若要新增連線設定檔，請指定設定檔的唯一名稱：

databricks configure [--token | --aad-token] --profile <profile-name>

檔案 .databrickscfg 包含對應的設定檔項目：

[<profile-name>]
host = <workspace-URL>
token = <token>

若要使用連線設定檔，請執行以下操作：

databricks <group> <command> --profile <profile-name>

如果值未指定 --profile <profile-name>，則使用預設設定檔。如果找不到預設設定檔，系統會提示您使用預設設定檔來設定 CLI。

測試您的連線設定檔

若要檢查您是否已正確設定任何連線設定檔，您可以使用下列其中一個連線設定檔名稱執行如下所示的命令：

databricks fs ls dbfs:/ --profile <profile-name>

如果成功，此命令會列出所指定連線設定檔的工作區 DBFS 根目錄中的檔和目錄。對要測試的每個連線設定檔執行此命令。

若要檢視可用的設定檔，請參閱您的 .databrickscfg 檔案。

使用 CLI

本節說明如何取得舊版 Databricks CLI 說明、剖析舊版 Databricks CLI 輸出，以及叫用每個命令群組中的命令。

顯示 CLI 命令群組說明

您可以使用 --help 或 -h 選項列出任何命令群組的子命令。例如，若要列出 DBFS CLI 子命令，請執行以下操作：

databricks fs -h

顯示 CLI 子命令說明

您可以使用 --help 或 -h 選項列出子命令的說明。例如，若要列出 DBFS 複製檔案子命令的說明，請執行以下操作：

databricks fs cp -h

別名命令群組

有時，使用命令群組的名稱作為每個舊版 Databricks CLI 叫用的前置詞並不方便，例如舊版 Databricks CLI 中的 databricks workspace ls。若要讓舊版 Databricks CLI 更容易使用，您可以透過使用命令群組的別名來實現較短的命令。例如，若要在 Bourne again shell 中將 databricks workspace ls 縮寫為 dw ls，您可以將 alias dw="databricks workspace" 新增至適當的 bash 設定檔。通常，此目錄位於 ~/.bash_profile。

提示

舊版 Databricks CLI 已將 databricks fs 的別名設定為 dbfs；databricks fs ls 和 dbfs ls 等效。

使用 `jq` 來剖析 CLI 輸出

某些舊版 Databricks CLI 命令會從 API 端點輸出 JSON 回應。有時，剖析 JSON 部分以管線傳送至其他命令會很有用。例如，若要複製作業定義，您必須取得作業命令的 settings 欄位，並將該欄位用作建立作業命令的引數。在這些情況下，我們建議您使用公用程式 jq。

例如，下列命令會列印識別碼為 233 的作業設定。

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'

輸出：

{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

另舉一例，下列命令僅列印工作區中所有可用叢集的名稱和識別碼：

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'

輸出：

[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

例如，您可以將 Homebrew 與 brew install jq 搭配使用 (在 macOS 上) 或將 Chocolatey 與 choco install jq 搭配使用 (在 Windows 上) 來安裝 jq。如需有關 jq 的詳細資訊，請參閱 jq 手冊。

JSON 字串參數

字串參數的處理方式會因您的作業系統而異：

Linux 或 macOS

您必須以單引號括住 JSON 字串參數。例如：

'["20180505", "alantest"]'

Windows

您必須以雙引號括住 JSON 字串參數，而且字串內的引號字元前面必須加上 \。例如：

"[\"20180505\", \"alantest\"]"

疑難排解

下列各節提供對舊版 Databricks CLI 常見問題進行疑難排解的提示。

將 EOF 與 `databricks configure` 搭配使用無法運作

對於 Databricks CLI 0.12.0 和更新版本，使用指令碼中的檔案結尾 (EOF) 序列將參數傳遞至 databricks configure 命令無法運作。例如，下列指令碼會導致 Databricks CLI 忽略參數，而且不會擲回錯誤訊息：

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

若要修正此問題，請執行下列其中一個動作：

使用其他其中一個程式設計組態選項，如設定驗證中所述。
手動將 host 和 token 值新增至 .databrickscfg 檔案，如設定驗證中所述。
將 Databricks CLI 的安裝降級為 0.11.0 或更低版本，然後再次執行您的指令碼。

分享方式：

Databricks CLI (舊版)

需求

限制

設定 CLI

安裝或更新 CLI

安裝 CLI

更新 CLI

設定驗證

使用 Microsoft Entra ID 權杖設定驗證

使用 Databricks 個人存取權杖設定驗證

Linux 或 macOS

Windows

測試您的驗證設定

連線設定檔

測試您的連線設定檔

使用 CLI

顯示 CLI 命令群組說明

顯示 CLI 子命令說明

別名命令群組

使用 `jq` 來剖析 CLI 輸出

JSON 字串參數

Linux 或 macOS

Windows

疑難排解

將 EOF 與 `databricks configure` 搭配使用無法運作

CLI 命令

意見反映

更多資源

分享方式：

Databricks CLI (舊版)

需求

限制

設定 CLI

安裝或更新 CLI

安裝 CLI

更新 CLI

設定驗證

使用 Microsoft Entra ID 權杖設定驗證

使用 Databricks 個人存取權杖設定驗證

Linux 或 macOS

Windows

測試您的驗證設定

連線設定檔

測試您的連線設定檔

使用 CLI

顯示 CLI 命令群組說明

顯示 CLI 子命令說明

別名命令群組

使用 jq 來剖析 CLI 輸出

JSON 字串參數

Linux 或 macOS

Windows

疑難排解

將 EOF 與 databricks configure 搭配使用無法運作

CLI 命令

意見反映

更多資源

使用 `jq` 來剖析 CLI 輸出

將 EOF 與 `databricks configure` 搭配使用無法運作