Databricks CLI

Databricks 命令行界面 (CLI) 提供了针对 Azure Databricks 平台的易用界面。 此开放源代码项目承载在 GitHub 上。 CLI 基于 Databricks REST API 2.0构建,并基于群集策略API 2.0、群集 API 2.0、DBFSAPI 2.0、组 API 2.0组织成命令组 、实例池 API 2.0、作业 API 2.1、库 API 2.0、ReposAPI 2.0、机密 API 2.0、令牌 API 2.0和工作区API 2.0(通过 )。 、、、、 、、、、 命令组。

重要

我们正积极开发此 CLI,将以试验客户端的形式发布它。 这意味着,相关界面仍可能会变化。

设置 CLI

此部分列出了 CLI 的要求,还介绍了如何安装和配置用于运行 CLI 的环境。

要求

  • Python 3 - 3.6 及更高版本

  • Python 2 - 2.7.9 及更高版本

    重要

    在 macOS 上,默认的 Python 2 安装未实现 TLSv1_2 协议。将 CLI 与此 Python 安装一起运行会导致以下错误:AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'。 使用Homebrew安装具有 的 Python 版本

限制

不支持将 Databricks CLI 用于启用了防火墙的存储容器。 Databricks 建议使用 Databricks Connectaz storage

安装 CLI

请使用与 Python 安装相对应的 pip 版本运行 pip install databricks-cli

更新 CLI

请使用与 Python 安装相对应的 pip 版本运行 pip install databricks-cli --upgrade

若要列出当前安装的 CLI 版本,请运行 databricks --version(或 databricks -v)。

设置身份验证

在运行 CLI 命令之前,必须设置身份验证。 若要向 CLI 进行身份验证,可使用 Databricks 个人访问令牌Azure Active Directory (Azure AD) 令牌

使用 Azure AD 令牌设置身份验证

若要使用自定义令牌Azure AD CLI,请生成Azure AD令牌,并存储在环境变量 中

Unix、linux、macos
export DATABRICKS_AAD_TOKEN=<Azure-AD-token>

或者,使用 jq

export DATABRICKS_AAD_TOKEN=$(az account get-access-token | jq .accessToken --raw-output)
Windows
setx DATABRICKS_AAD_TOKEN "<Azure-AD-token>" /M

或者,使用 Windows PowerShell 和 jq

$databricks_aad_token = az account get-access-token | jq .accessToken --raw-output
[System.Environment]::SetEnvironmentVariable('DATABRICKS_AAD_TOKEN', $databricks_aad_token, [System.EnvironmentVariableTarget]::Machine)`

运行 databricks configure --aad-token。 此命令发出提示:

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

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

完成提示后,访问凭据存储在 ~/.databrickscfg(Unix、Linux、macOS 上)或 %USERPROFILE%\.databrickscfg 文件(Windows 上)中。 该文件包含默认配置文件条目:

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

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

若要将 CLI 配置为使用个人访问令牌,请运行 databricks configure --token。 该命令首先发出提示:

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

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

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

Token:

完成提示后,访问凭据存储在 ~/.databrickscfg(Unix、Linux、macOS 上)或 %USERPROFILE%\.databrickscfg 文件(Windows 上)中。 该文件包含默认配置文件条目:

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

对于 CLI 0.8.1 及以上版本,可以通过设置环境变量 来更改此文件的路径 DATABRICKS_CONFIG_FILE

Unix、linux、macos

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

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

重要

由于 CLI 基于 REST API,因此 .netrc 文件的身份验证配置优先于 中的配置

CLI 0.8.0 及更高版本支持以下环境变量:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN
  • DATABRICKS_CONFIG_PROFILE

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

连接配置文件

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。

Alias 命令组

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

提示

Azure Databricks 已将 databricks fs 的别名设置为 dbfsdatabricks fs lsdbfs ls 等效。

使用 CLI

此部分介绍如何获取 CLI 帮助、如何分析 CLI 输出,以及如何调用每个命令组中的命令。

显示 CLI 命令组帮助

可通过运行 databricks <group> --help(或 databricks <group> -h)列出任意命令组的子命令。 例如,可以通过运行 databricks fs -h 列出 DBFS CLI 子命令。

显示 CLI 子命令帮助

可以通过运行 databricks <group> <subcommand> --help(或 databricks <group> <subcommand> -h)来列出子命令的帮助。 例如,可以通过运行 databricks fs cp -h 列出 DBFS copy files 子命令的帮助。

使用 jq 分析 CLI 输出

某些 Databricks CLI 命令从 API 终结点输出 JSON 响应。 有时候,可以分析将要通过管道传输到其他命令中的 JSON 部件。 例如,若要复制作业定义,必须获取 databricks jobs get 命令的 settings 字段并将其用作 databricks jobs create 命令的参数。 在这些情况下,建议使用实用程序 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 字符串参数

字符串参数的处理方式各异,具体取决于你的操作系统:

Unix、linux、macos

必须将 JSON 字符串参数用单引号引起来。 例如:

databricks jobs run-now --job-id 9 --jar-params '["20180505", "alantest"]'

Windows

必须将 JSON 字符串参数用双引号引起来,字符串内的引号字符必须在 \ 之后。 例如:

databricks jobs run-now --job-id 9 --jar-params "[\"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

若要解决此问题,请执行以下任一操作:

  • 使用其他编程配置选项其中一种,如设置身份验证中所述。
  • hosttoken.databrickscfg 按照host中所述,将和值手动添加到文件中。
  • 将 Databricks CLI 安装降级到 0.11.0 或更低版本,然后再次运行脚本。

CLI 命令