作业 CLI(旧)

重要

本文档已过时,将来可能不会更新。

此信息适用于旧版 Databricks CLI 0.18 及更低版本。 Databricks 建议改用较新的 Databricks CLI 0.205 或更高版本。 请参阅什么是 Databricks CLI?。 若要查找你的 Databricks CLI 的版本,请运行 databricks -v

若要从 Databricks CLI 0.18 或更低版本迁移到 Databricks CLI 0.205 或更高版本,请参阅 Databricks CLI 迁移

通过将 Databricks 作业 CLI 子命令追加到 databricks jobs 后面来运行 Databricks 作业 CLI 子命令,通过将 Databricks 作业运行 CLI 子命令追加到 databricks runs 后面来运行 Databricks 作业运行 CLI 子命令。 有关 Databricks 作业运行 CLI 子命令,请参阅运行 CLI(旧)。 这些子命令都调用作业 API作业 API 2.0

重要

Databricks 作业 CLI 支持调用两个版本的 Databricks 作业 REST API:2.1 和 2.0 版。 2.1 版增加了对多任务作业编排的支持;请参阅创建并运行 Azure Databricks 作业从作业 API 2.0 更新到 2.1。 Databricks 建议调用 2.1 版,除非有依赖 2.0 版且无法迁移的旧脚本。

除非另有说明,否则本文中描述的编程行为同样适用于 2.1 和 2.0 版。

调用作业 REST API 2.1 的要求

若要使用 Databricks 作业 CLI(和作业运行 CLI)并将其设置为调用作业 REST API 2.1,请执行以下操作:

  1. 将 CLI 更新到 0.16.0 或更高版本

  2. 执行下列操作之一:

    • 运行命令 databricks jobs configure --version=2.1。 这会将 jobs-api-version = 2.1 设置添加到 Unix、Linux 或 macOS 上的 ~/.databrickscfg 文件,或 Windows 上的 %USERPROFILE%\.databrickscfg。 默认情况下,所有作业 CLI(和作业运行 CLI)子命令都将调用作业 REST API 2.1。
    • 手动将 jobs-api-version = 2.1 设置添加到 Unix、Linux 或 macOS 上的 ~/.databrickscfg 文件,或 Windows 上的 %USERPROFILE%\.databrickscfg。 默认情况下,所有作业 CLI(和作业运行 CLI)子命令都将调用作业 REST API 2.1。
    • 附加选项 --version=2.1(例如 databricks jobs list --version=2.1)以指示作业 CLI 仅为该调用调用作业 REST API 2.1。

    如果未执行上述操作,则作业 CLI(和作业运行 CLI)将默认调用作业 REST API 2.0。

调用作业 REST API 2.0 的要求

若要使用 Databricks 作业 CLI(和作业运行 CLI)并将其设置为调用作业 REST API 2.0,请执行以下任一操作:

  • 使用低于 0.16.0 的 Databricks CLI 版本,或
  • 将 CLI 更新到 X.Y.Z 或更高版本,然后执行以下任一操作:
    • 运行 databricks jobs configure --version=2.0 命令。 这会将 jobs-api-version = 2.0 设置添加到 Unix、Linux 或 macOS 上的 ~/.databrickscfg 文件,或 Windows 上的 %USERPROFILE%\.databrickscfg。 默认情况下,所有作业 CLI(和作业运行 CLI)子命令都将调用作业 REST API 2.0。
    • 手动将 jobs-api-version = 2.0 设置添加到 Unix、Linux 或 macOS 上的 ~/.databrickscfg 文件,或 Windows 上的 %USERPROFILE%\.databrickscfg。 默认情况下,所有作业 CLI(和作业运行 CLI)子命令都将调用作业 REST API 2.0。
    • 附加选项 --version=2.1(例如 databricks jobs list --version=2.0)以指示作业 CLI 仅为该调用调用作业 REST API 2.0。

如果未执行上述操作,则作业 CLI(和作业运行 CLI)将默认调用作业 REST API 2.0。

子命令和常规用法

databricks jobs -h
Usage: databricks jobs [OPTIONS] COMMAND [ARGS]...

  Utility to interact with jobs.

  Job runs are handled by ``databricks runs``.

Options:
  -v, --version  [VERSION]
  -h, --help     Show this message and exit.

Commands:
  create   Creates a job.
    Options:
      --json-file PATH            File containing JSON request to POST to /api/2.0/jobs/create.
      --json JSON                 JSON string to POST to /api/2.0/jobs/create.
  delete   Deletes a job.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
  get      Describes the metadata for a job.
    Options:
    --job-id JOB_ID               Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
  list     Lists the jobs in the Databricks Job Service.
  reset    Resets (edits) the definition of a job.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
      --json-file PATH            File containing JSON request to POST to /api/2.0/jobs/create.
      --json JSON                 JSON string to POST to /api/2.0/jobs/create.
  run-now  Runs a job with optional per-run parameters.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/#job/$JOB_ID. [required]
      --jar-params JSON           JSON string specifying an array of parameters. i.e. '["param1", "param2"]'
      --notebook-params JSON      JSON string specifying a map of key-value pairs. i.e. '{"name": "john doe", "age": 35}'
      --python-params JSON        JSON string specifying an array of parameters. i.e. '["param1", "param2"]'
      --spark-submit-params JSON  JSON string specifying an array of parameters. i.e. '["--class", "org.apache.spark.examples.SparkPi"]'

创建作业

若要显示使用情况文档,请运行 databricks jobs create --help

常规用法

databricks jobs create --json-file create-job.json

作业 CLI 2.1 用法说明和请求示例

请参阅从作业 API 2.0 更新到 2.1 中的创建

作业 CLI 2.0 请求有效负载和响应示例

create-job.json:

{
  "name": "my-job",
  "existing_cluster_id": "1234-567890-reef123",
  "notebook_task": {
    "notebook_path": "/Users/someone@example.com/My Notebook"
  },
  "email_notifications": {
    "on_success": [
      "someone@example.com"
    ],
    "on_failure": [
      "someone@example.com"
    ]
  }
}
{ "job_id": 246 }

提示

若要复制作业,请运行 create 命令并传递具有要复制的作业设置的 JSON 对象。 此示例将 ID 为 246 的作业的设置复制到新作业中。 它需要 jq 实用程序。

SETTINGS_JSON=$(databricks jobs get --job-id 246 | jq .settings)

databricks jobs create --json "$SETTINGS_JSON"
{ "job_id": 247 }

删除作业

若要显示使用情况文档,请运行 databricks jobs delete --help

databricks job delete --job-id 246

如果成功,则不显示任何输出。

提示

要删除多个具有相同设置的作业,请获取与该设置匹配的作业 ID 列表,然后针对每个匹配的作业 ID 运行 delete 命令。 此示例删除作业名称为 Untitled 的所有作业。 它需要 jq 实用程序。

databricks jobs list --output json | jq '.jobs[] | select(.settings.name == "Untitled") | .job_id' | xargs -n 1 databricks jobs delete --job-id

列出有关作业的信息

若要显示使用情况文档,请运行 databricks jobs get --help

常规用法

databricks jobs get --job-id 246

作业 CLI 2.1 用法说明和响应示例

请参阅从作业 API 2.0 更新到 2.1 中的获取

作业 CLI 2.0 响应示例

{
  "job_id": 246,
  "settings": {
    "name": "my-job",
    "existing_cluster_id": "1234-567890-reef123",
    "email_notifications": {
      "on_success": [
        "someone@example.com"
      ],
      "on_failure": [
        "someone@example.com"
      ]
    },
    "timeout_seconds": 0,
    "notebook_task": {
      "notebook_path": "/Users/someone@example.com/My Notebook"
    },
    "max_concurrent_runs": 1
  },
  "created_time": 1620163107742,
  "creator_user_name": "someone@example.com"
}

列出有关可用作业的信息

若要显示使用情况文档,请运行 databricks jobs list --help

常规用法

databricks jobs list

作业 CLI 2.1 用法说明和响应示例

请参阅从作业 API 2.0 更新到 2.1 中的列出

作业 CLI 2.0 响应示例

{
  "jobs": [
    {
      "job_id": 246,
      "settings": {
        "name": "my-job",
        "existing_cluster_id": "1234-567890-reef123",
        "email_notifications": {
          "on_success": [
            "someone@example.com"
          ],
          "on_failure": [
            "someone@example.com"
          ]
        },
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/someone@example.com/My Notebook"
        },
        "max_concurrent_runs": 1
      },
      "created_time": 1620163107742,
      "creator_user_name": "someone@example.com"
    },
    ...
  ]
}

列出所有作业(仅限 API 2.1)

若要指示 CLI 通过对 API 发出顺序调用来返回所有作业,请使用 --all 选项。 若要使用 --all 选项,必须将 API 版本设置为 2.1

databricks jobs list --all

将作业列表分页(仅限 API 2.1)

若要返回分页的作业列表,请使用 --limit--offset 参数。 默认情况下,作业列表作为包含作业 ID 和作业名称的表返回。 若要选择性地返回包含作业信息的 JSON 文档,请使用 --output JSON 参数。

若要使用 --limit--offset 参数,必须将 API 版本设置为 2.1

使用 --output JSON 时,列表将按作业创建日期的降序返回。 使用 --output TABLE 时,列表将按作业创建日期的降序返回,然后按作业名称的字母顺序排序。

以下示例将作业列表分页,每次列出 10 个作业,并以 JSON 格式返回结果:

databricks jobs list --output JSON --limit 10
databricks jobs list --output JSON --limit 10 --offset 10
databricks jobs list --output JSON --limit 10 --offset 20

更改作业的设置

若要显示使用情况文档,请运行 databricks jobs reset --help

常规用法

databricks jobs reset --job-id 246 --json-file reset-job.json

作业 CLI 2.1 用法说明和请求示例

请参阅从作业 API 2.0 更新到 2.1 中的更新重置

作业 CLI 2.0 请求示例

reset-job.json:

{
  "job_id": 246,
  "existing_cluster_id": "2345-678901-batch234",
  "name": "my-changed-job",
  "notebook_task": {
    "notebook_path": "/Users/someone@example.com/My Other Notebook"
  },
  "email_notifications": {
    "on_success": [
      "someone-else@example.com"
    ],
    "on_failure": [
      "someone-else@example.com"
    ]
  }
}

如果成功,则不显示任何输出。

运行作业

若要显示使用情况文档,请运行 databricks jobs run-now --help

databricks jobs run-now --job-id 246
{
  "run_id": 122,
  "number_in_job": 1
}