Databricks CLI 移轉
本文說明如何從 Databricks CLI 0.18 版或更新版本移轉至 Databricks CLI 0.205 版或更新版本。 Databricks CLI 0.205 版和更新版本處於 公開預覽狀態。
為了簡潔起見，本文將 Databricks CLI 0.18 版和以下版本稱為「舊版」CLI，以及 Databricks CLI 0.205 版和更新版本作為「新增」CLI。
如需舊版和新 CLIS 的詳細資訊，請參閱：
卸載舊版 CLI
如果您已安裝舊版 CLI，而且想要將它卸載，請使用 pip （或 pip3，視 Python 版本而定）來執行 uninstall 命令，如下所示：
pip uninstall databricks-cli
安裝新的 CLI
若要瞭解如何安裝新的 CLI，請參閱 安裝或更新 Databricks CLI。
確認 CLI 安裝
如果您不確定您是否使用新的 CLI，請遵循本節中的指示，視需要進行驗證和調整。 遵循這些指示之前，請務必結束任何 Python 虛擬環境、 conda 環境或類似的環境。
若要檢查 CLI 的預設安裝版本，請執行下列命令：
databricks -v
如果版本號碼不是您所預期的，請執行下列其中一項動作：
- 如果您想要只使用一個 CLI 版本：卸載您不想再使用的所有舊版 CLI。 您可能需要更新作業的 ，
PATH以便列出您想要使用之 CLI 剩餘版本的路徑。 - 如果您想要繼續使用多個版本的 CLI：在您想要用於每個 CLI 和每次呼叫 CLI 的 CLI 版本前面加上完整路徑。
- 如果您想要繼續使用多個版本的 CLI，但您不想繼續將您最常使用之 CLI 版本的完整路徑加上：請確定該版本的完整路徑會先列在操作系統的
PATH中。 請注意，您仍然必須前面加上操作系統 中未列出之PATHCLI 版本的完整路徑。
若要更新作業系統的 PATH，請執行下列動作：
MacOS 或 Linux
列出執行下列其中一個命令所安裝的路徑
databricks：which -a databricks # Or: where databricks取得您想要使用之安裝的路徑，而不需在每次呼叫 CLI 之前加上完整路徑。 如果您不確定這是哪一個路徑，請執行每個位置的完整路徑，後面接著
-v，例如：/usr/local/bin/databricks -v若要將您想要先使用的路徑放在 中
PATH，請執行下列命令，並將 取代/usr/local/bin為您要使用的路徑。 請勿新增databricks至此路徑的結尾。 例如：export PATH="/usr/local/bin:$PATH"若要確認已
PATH針對目前的終端機會話正確設定 ，請執行databricks，然後-v檢查版本號碼：databricks -vPATH若要在每次重新啟動終端機時以這種方式設定 ，請將步驟 3 中的命令新增至殼層初始化檔案。 例如，針對 Zshell，此檔案通常位於~/.zshrc。 對於 Bash，此檔案通常位於~/.bashrc。 如需其他殼層，請參閱殼層提供者的檔。更新殼層初始化檔案之後，您必須重新啟動終端機以套用更新
PATH的值。
Windows
以滑鼠右鍵按下您想要使用的安裝
databricks，而不需在每次呼叫 CLI 之前加上完整路徑。按兩下 [ 開啟檔案位置]。
請注意 的路徑
databricks，例如C:\Windows。在 [ 開始] 功能表上，搜尋 環境變數。
按兩下 [編輯您帳戶的環境變數]。
在 [用戶變數]
<username>區段中選取 [路徑] 變數。按一下 [編輯] 。
按一下新增。
輸入您要新增的路徑，不含
databricks.exe（例如 ）。C:\Windows使用 [ 上移] 按鈕來移動您剛新增至列表開頭的路徑。
按一下 [確定]。
若要確認
PATH已正確設定 ，請開啟新的命令提示字元，然後執行databricks-v，然後檢查版本號碼：databricks -v
使用其他驗證類型
舊版 CLI 和新的 CLI 都支援 Azure Databricks 個人存取令牌驗證。 不過，Databricks 建議您盡可能使用其他 Azure Databricks 驗證類型，只有新的 CLI 支援。
如果您必須使用 Azure Databricks 個人存取令牌驗證，Databricks 建議您使用與服務主體相關聯的令牌，而不是 Azure Databricks 帳戶或工作區使用者。 請參閱管理服務主體。
除了 Azure Databricks 個人存取令牌之外，新的 CLI 還支援 Microsoft Entra ID 令牌。 這些額外的令牌較安全，因為它們通常會在一小時內到期，而 Azure Databricks 個人存取令牌可以從一天到無限期有效。 如果令牌不小心簽入其他人可以存取的版本控制系統，這特別重要。 此外，新的 CLI 可以在過期時自動重新整理這些額外的令牌，而重新整理 Azure Databricks 個人存取令牌是手動程式或難以自動化。
如需詳細資訊，請參閱 Databricks CLI 的驗證。
命令群組和命令比較
下表列出舊版 CLI 命令群組及其新 CLI 命令群組對等專案。 在 CLIS 之間存在顯著差異時，其他數據表會列出舊版 CLI 命令或選項，以及其新的 CLI 命令或選項對等專案。
命令群組
| 舊版命令群組 | 新增命令群組 |
|---|---|
cluster-policies |
cluster-policies. 所有命令名稱都相同。 |
clusters |
clusters. 所有命令名稱都相同。 |
configure |
configure. 請參閱 設定選項。 |
fs |
fs. 請參閱 fs 命令。 |
groups |
groups. 請參閱 群組命令。 |
instance-pools |
instance-pools. 所有命令名稱都相同。 |
jobs |
jobs. 所有命令名稱都相同。 |
libraries |
libraries. 除了 之外，所有命令名稱都相同 list。 命令 list 已無法使用;請改用 all-cluster-statuses 或 cluster-status 命令。 |
pipelines |
pipelines. 請參閱 管線命令。 |
repos |
repos. 所有命令名稱都相同。 |
runs |
jobs. 請參閱 執行命令。 |
secrets |
secrets. 請參閱 秘密命令。 |
stack |
新 CLI 中無法使用。 Databricks 建議您改用 Databricks Terraform 提供者 。 |
tokens |
tokens. 請參閱 令牌命令。 |
unity-catalog |
各種。 請參閱 unity-catalog 命令群組。 |
workspace |
workspace. 請參閱 工作區命令。 |
configure 選項
| 舊版選項 | 新增選項 |
|---|---|
-o |
舊版 CLI 會使用 -o OAuth 驗證。 新的 CLI 會重新用途 -o ，以指定 CLI 輸出是否為文字或 JSON 格式。 不適用於 Azure Databricks。 |
--oauth |
不適用於 Azure Databricks。 |
-s 或 --scope |
不適用於 Azure Databricks。 |
-t 或 --token |
-t 或 --token （相同） |
-f 或 --token-file |
新 CLI 中無法使用。 |
--host |
--host （相同） |
--aad-token |
當系統提示而不是 Azure Databricks 個人存取令牌時，請使用 --host 並指定Microsoft Entra ID 令牌。 |
--insecure |
新 CLI 中無法使用。 |
--jobs-api-version |
新 CLI 中無法使用。 新的 CLI 只會使用作業 API 2.1。 若要呼叫舊版作業 API 2.0，請使用舊版 CLI，並參閱作業 CLI（舊版）。 |
--debug |
如需在新 CLI 中偵錯和記錄，請參閱 偵錯模式。 |
--profile |
--profile （相同） 或 -p |
-h 或 --help |
-h 或 --help （相同） |
fs 命令
舊版 CLI 中的所有 fs 命令在新 CLI 中都相同，但 fs mv 新 CLI 中無法使用。
| 舊版命令 | 新增命令 |
|---|---|
fs cat |
fs cat （相同） |
fs cp |
fs cp （相同） |
fs ls |
fs ls （相同） |
fs mkdirs |
fs mkdir |
fs mv |
新 CLI 中無法使用。 |
fs rm |
fs rm （相同） |
groups 命令
| 舊版命令 | 新增命令 |
|---|---|
groups add-member |
groups patch |
groups create |
groups create （相同） |
groups delete |
groups delete （相同） |
groups list |
groups list （相同） |
groups list-members |
groups list |
groups list-parents |
groups list |
groups remove-member |
groups patch |
pipelines 命令
| 舊版命令 | 新增命令 |
|---|---|
pipelines create |
pipelines create （相同） |
pipelines delete |
pipelines delete （相同） |
pipelines deploy |
pipelines create |
pipelines edit |
pipelines update |
pipelines get |
pipelines get （相同） |
pipelines list |
pipelines list-pipeline-events、pipelines list-pipelines 或 pipelines list-updates |
pipelines reset |
pipelines reset （相同） |
pipelines start |
pipelines start update |
pipelines stop |
pipelines stop （相同） |
pipelines update |
pipelines update （相同） |
runs 命令
| 舊版命令 | 新增命令 |
|---|---|
runs cancel |
jobs cancel-run |
runs get |
jobs get-run |
runs get-output |
jobs get-run-output |
runs list |
jobs list-runs |
runs submit |
jobs submit |
secrets 命令
| 舊版命令 | 新增命令 |
|---|---|
secrets create-scope |
secrets create-scope （相同） |
secrets delete |
secrets delete-secret |
secrets delete-acl |
secrets delete-acl （相同） |
secrets delete-scope |
secrets delete-scope （相同） |
secrets get-acl |
secrets get-acl （相同） |
secrets list |
secrets list-secrets |
secrets list-acls |
secrets list-acls （相同） |
secrets list-scopes |
secrets list-scopes （相同） |
secrets put |
secrets put-secret |
secrets put-acl |
secrets put-acl （相同） |
secrets write |
secrets put-secret |
secrets write-acl |
secrets put-acl |
tokens 命令
| 舊版命令 | 新增命令 |
|---|---|
tokens create |
tokens create （相同） |
tokens list |
tokens list （相同） |
tokens revoke |
tokens delete |
unity-catalog 命令群組
unity-catalog <command> 在舊版 CLI 中，只會 <command> 在新 CLI 中變成 。
| 舊版命令群組 | 新增命令群組 |
|---|---|
unity-catalog catalogs |
catalogs （相同但下降 unity-catalog） |
unity-catalog external-locations |
external-locations （相同但下降 unity-catalog） |
unity-catalog lineage |
新 CLI 中無法使用。 請參閱 使用數據譜系 REST API 擷取譜系。 |
unity-catalog metastores |
metastores （相同但下降 unity-catalog） |
unity-catalog permissions |
grants |
unity-catalog providers |
providers （相同但下降 unity-catalog） |
unity-catalog recipients |
recipients （相同但下降 unity-catalog） |
unity-catalog schemas |
schemas （相同但下降 unity-catalog） |
unity-catalog shares |
shares （相同但下降 unity-catalog） |
unity-catalog storage-credentials |
storage-credentials （相同但下降 unity-catalog） |
unity-catalog tables |
tables （相同但下降 unity-catalog） |
workspace 命令
| 舊版命令 | 新增命令 |
|---|---|
workspace delete |
workspace delete （相同） |
workspace export |
workspace export （相同） |
workspace export-dir |
workspace export |
workspace import |
workspace import （相同） |
workspace import-dir |
workspace import |
workspace list |
workspace list （相同） |
workspace ls |
workspace list |
workspace mkdirs |
workspace mkdirs （相同） |
workspace rm |
workspace delete |
預設和位置自變數
大部分的新 CLI 命令至少有一個沒有隨附選項的預設自變數。 某些新的 CLI 命令有兩個或多個位置自變數，必須以特定順序指定，而且沒有隨附的選項。 這與舊版 CLI 不同，其中大部分的命令都需要為所有自變數指定選項。 例如，新 CLI 的 clusters get 命令會採用叢集標識碼作為預設自變數。 不過，舊版 CLI 的 clusers get 命令會要求您指定 --cluster-id 選項以及叢集標識碼。 例如：
針對舊版 CLI：
# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d
# This does **not** work with the legacy CLI - "Error:
# Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d
針對新的 CLI：
# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d
# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d
另一個範例是，新 CLI 的 grants get 命令會採用兩個預設自變數：安全性實體類型，後面接著安全性實體的完整名稱。 不過，舊版 CLI 的 unity-catalog permissions get 命令會要求您指定 --<securable-type> 選項以及安全性實體的完整名稱。 例如：
針對舊版 CLI：
databricks unity-catalog permissions get --schema main.default
針對新的 CLI：
# This works with the new CLI.
databricks grants get schema main.default
# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default
偵錯模式
舊版 CLI 提供在 --debug 錯誤時顯示完整堆疊追蹤的選項。 對於新的 CLI， --debug 無法辨識選項。 請改用下列選項：
- 使用
--log-file <path>將記錄資訊寫入 中指定的<path>檔案。 如果未提供此選項，則記錄資訊會輸出至 stderr。 若--log-file未指定 ，也不會指定--log-level任何寫入檔案的記錄檔資訊。 - 使用
--log-format <type>來指定所記錄資訊的格式。<type>可以是text（如果未指定，則為預設值）或json。 - 使用
--log-level <format>來指定記錄的資訊層級。 允許的值為disabled（預設值，如果未指定），trace、、debug、info、warn和error。
針對舊版 CLI，下列範例會顯示錯誤時的完整堆疊追蹤：
databricks fs ls / --debug
# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"
針對新的 CLI，下列範例會將完整堆疊追蹤記錄至目前工作目錄中名為 new-cli-errors.log 的檔案。 堆疊追蹤會以 JSON 格式寫入檔案：
databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace
# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)
常見問題
本節列出從舊版移轉至新 CLI 的常見問題。
舊版 CLI 會發生什麼事？
舊版 CLI 仍可供使用，但未收到任何非重大更新。 舊 版 CLI 檔 會反映這一點。 Databricks 建議用戶儘快移轉至新的 CLI。
舊版 CLI 一直處於實驗狀態，免責聲明 Databricks 計劃沒有舊版 CLI 的新功能運作，而且舊版 CLI 不支援透過 Databricks 支援通道。
何時會淘汰舊版 CLI？
舊版 CLI 一直處於實驗狀態，免責聲明 Databricks 計劃沒有舊版 CLI 的新功能運作，而且舊版 CLI 不支援透過 Databricks 支援通道。
Databricks 尚未建立取代舊版 CLI 的日期或時程表。 不過，Databricks 建議用戶儘快移轉至新的 CLI。
何時會以正式推出的形式發行新的 CLI？
發行新 CLI 的發行日期或時程表，因為尚未建立 GA。 這取決於 Databricks 在公開預覽期間收到使用者的意見反應。
舊版和新 CLIS 之間的主要差異為何？
- 舊版 CLI 已發行為 Python 套件。 新的 CLI 會以獨立可執行檔的形式發行，而且不需要安裝任何運行時間相依性。
- 新的 CLI 已完整涵蓋 Databricks REST API。 舊版 CLI 不會。
- 新的 CLI 以公開預覽的形式提供。 舊版 CLI 會維持在實驗狀態。
新的 CLI 是否與舊版 CLI 具有完整的功能同位？
新的 CLI 幾乎涵蓋舊版 CLI 的所有命令。 不過，新 CLI 明顯不存在的是 stacks 舊版 CLI 中的命令群組。 此外，一些舊版 CLI 命令群組，例如 unity-catalog ，並 runs 已重構為新 CLI 中的新命令群組。 如需移轉指引，請參閱本文稍早提供的資訊。
如何? 從舊版移轉至新的 CLI？
如需移轉指引，請參閱本文稍早提供的資訊。 請注意，新的 CLI 不是舊版 CLI 的卸除取代專案，而且需要一些設定才能從舊版移至新的 CLI。
舊版和新 CLIS 的安裝是否可以存在於同一部電腦上？
是。 舊版和新 CLIS 的安裝可以存在於同一部電腦上，但必須位於不同的目錄中。 因為可執行檔都命名 databricks為 ，因此您必須設定計算機的 PATH，以控制預設執行的可執行檔。 如果您想要執行新的 CLI，但不知怎麼地不小心執行舊版 CLI，根據預設，舊版 CLI 會使用相同的自變數執行新的 CLI，並顯示下列警告訊息：
Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>
Because both are installed and available in PATH,
I assume you are trying to run the newer version.
If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.
Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>
如上述警告訊息所示，您可以將環境變數設定 DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION 為 1 來停用此行為，並改為執行舊版 CLI。
取得協助
若要取得從舊版 CLI 移轉至新 CLI 的說明，請參閱下列資源：