Databricks CLI（旧版）

项目
09/25/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 版本运行 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 建议使用属于服务主体（而不是工作区用户）的个人访问令牌。若要为服务主体创建令牌，请参阅管理服务主体的令牌。

使用 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://):

按照 https://adb-<workspace-id>.<random-number>.azuredatabricks.net 的格式输入每工作区 URL。若要获取每工作区 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://):

按照 https://adb-<workspace-id>.<random-number>.azuredatabricks.net 的格式输入每工作区 URL。若要获取每工作区 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

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。

提示

旧版 Databricks CLI 已将 databricks fs 的别名设置为 dbfs；databricks fs ls 和 dbfs ls 等效。

使用 `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 或更低版本，然后再次运行脚本。

通过

Databricks CLI（旧版）

要求

限制

安装 CLI

安装或更新 CLI

安装 CLI

更新 CLI

设置身份验证

使用 Microsoft Entra ID 令牌设置身份验证

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

Linux 或 macOS

Windows

测试身份验证设置

连接配置文件

测试连接配置文件

使用 CLI

显示 CLI 命令组帮助

显示 CLI 子命令帮助

Alias 命令组

使用 jq 分析 CLI 输出

JSON 字符串参数

Linux 或 macOS

Windows

故障排除

将 EOF 与 databricks configure 一起使用不起作用

CLI 命令

反馈

其他资源

使用 `jq` 分析 CLI 输出

将 EOF 与 `databricks configure` 一起使用不起作用