Databricks CLI（旧版）

旧版 Databricks 命令行接口（也称为旧版 Databricks CLI）是一个实用工具，它提供易用的接口通过终端、命令提示符或自动化脚本自动运行 Azure Databricks 平台。

要求

• Python 3 - 3.6 及更高版本
• Python 2 - 2.7.9 及更高版本

限制

不支持将旧版 Databricks CLI 与启用了防火墙的存储容器一起使用。 Databricks 建议使用 Databricks Connect 或 az storage。

安装 CLI

本部分介绍了如何设置旧版 Databricks CLI。

安装或更新 CLI

本部分介绍了如何安装或更新开发计算机以运行旧版 Databricks CLI。

安装 CLI

使用适合你的 Python 安装的 pip 版本运行 pip install databricks-cli：

pip install databricks-cli

更新 CLI

使用适合你的 Python 安装的 pip 版本运行 pip install databricks-cli --upgrade：

pip install databricks-cli --upgrade

要列出当前安装的旧版 Databricks CLI 版本，请运行 databricks --version：

databricks --version

设置身份验证

在运行旧版 Databricks CLI 命令之前，必须在旧版 Databricks CLI 和 Azure Databricks 之间设置身份验证。 本部分介绍如何为旧版 Databricks CLI 设置身份验证。

要通过旧版 Databricks CLI 进行身份验证，可以使用 Databricks 个人访问令牌或 Microsoft Entra ID（前Azure Active Directory）令牌。

使用 Databricks 个人访问令牌设置身份验证

要配置旧版 Databricks CLI 以使用个人访问令牌，请运行以下命令：

databricks configure --token

该命令首先发出提示：

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

按照 https://adb-<workspace-id>.<random-number>.databricks.azure.cn 的格式输入每工作区 URL。 若要获取每工作区 URL，请参阅每工作区 URL。

该命令继续发出提示，要求你输入个人访问令牌：

Token:

完成提示后，访问凭据将存储在 Linux 或 macOS 上的文件 ~/.databrickscfg 中，或存储在 Windows 上的文件 %USERPROFILE%\.databrickscfg 中。 该文件包含默认配置文件条目：

[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.8.0 及更高版本支持以下 Azure Databricks 环境变量：

• DATABRICKS_HOST
• DATABRICKS_TOKEN

环境变量设置优先于配置文件中的设置。

测试身份验证设置

若要检查是否正确设置了身份验证，可以运行如下所示的命令：

databricks fs ls dbfs:/

如果成功，此命令会列出与 DEFAULT 配置文件关联的工作区的 DBFS 根目录中的文件和目录。

连接配置文件

旧版 Databricks CLI 配置支持多个连接配置文件。 同一旧版 Databricks CLI 安装可用于在多个 Azure Databricks 工作区进行 API 调用。

若要添加连接配置文件，请为配置文件指定一个唯一名称：

databricks configure [--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

Alias 命令组

有时，使用命令组的名称作为每个旧版 Databricks CLI 调用的前缀并不方便，例如旧版 Databricks CLI 中的 databricks workspace ls。 要增强旧版 Databricks CLI 的易用性，可以通过使用命令组的别名来实现较短的命令。 例如，若要在 Bourne again shell 中将 databricks workspace ls 缩写为 dw ls，可以将 alias dw="databricks workspace" 添加到相应的 bash 配置文件。 通常，该文件位于 ~/.bash_profile。

使用 jq 分析 CLI 输出

某些旧版 Databricks CLI 命令可从 API 终结点输出 JSON 响应。 有时候，可以分析将要通过管道传输到其他命令中的 JSON 部件。 例如，若要复制作业定义，必须获取 get job 命令的 settings 字段并将其用作 create job 命令的参数。 在这些情况下，建议使用实用程序 jq。

例如，以下命令显示 ID 为 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
}

另举一例，以下命令仅输出工作区中所有可用群集的名称和 ID：

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 文件中，如host中所述。
• 将 Databricks CLI 安装降级到 0.11.0 或更低版本，然后再次运行脚本。

CLI 命令

• 群集策略 CLI（旧版）
• 群集 CLI（旧版）
• DBFS CLI（旧版）
• 增量实时表 CLI（旧版）
• 组 CLI（旧版）
• 实例池 CLI（旧版）
• 作业 CLI（旧版）
• 库 CLI（旧版）
• Repos CLI（旧版）
• 运行 CLI（旧版）
• 机密 CLI（旧版）
• 堆栈 CLI（旧版）
• 令牌 CLI（旧版）
• Unity Catalog CLI（旧版）
• 工作区 CLI（旧版）