更新 Jobs API 从 2.1 到 2.2

本文详细介绍了Jobs API版本2.2的功能更新与增强。 它包含有助于更新现有 API 客户端以使用此新版本的信息。 这些更新包括默认对作业进行排队，以及在响应包含超过 100 个元素的字段时，更好地支持分页。 由于版本 2.2 增强了对分页大型结果集的现有支持，Databricks 建议将其用于 API 脚本和客户端，尤其是在响应可能包含许多任务时。

若要了解 API 版本 2.0 和 2.1 之间的更改，请参阅 从作业 API 2.0 更新到 2.1。

除了 Databricks 作业 API 版本 2.1 中包含的更改外，版本 2.2 还具有以下增强功能：

默认对作业进行排队

作业队列是一项可选功能，可阻止在资源不可用时跳过作业运行。 作业队列在 2.0、2.1 和 2.2 版本的作业 API 中受支持，在默认队列处理方面存在以下差异：

• 对于使用作业 API 2.2 创建的作业，默认启用排队。 可以通过在创建或更新作业时将请求正文中的 queue 字段设置为 false 来关闭队列。
• 对于使用 2.0 和 2.1 版本的作业 API 创建的作业，默认情况下不会启用排队。 使用这些版本时，你必须在创建或更新作业时，将 queue 字段设置为 true，以启用请求正文中的排队功能。

创建作业、部分更新作业或 更新所有作业设置时，可以启用或禁用排队。

请参阅作业队列。

支持对长任务和任务运行列表进行分页

为支持具有大量任务或任务运行的作业，作业 API 2.2 更改了为以下请求返回的大量结果集：

• 列出作业：请参阅对列出作业和列出作业运行请求的更改。
• 列出作业运行：请参阅对列出作业和列出作业运行请求的更改。
• 获取单个作业：请参阅获取单个作业。
• 获取单次作业运行：请参阅获取单次运行。

Jobs API 2.2 针对这些请求的分页进行了更改，具体如下：

• 表示任务、参数、job_clusters或环境等元素列表的字段限制为每个响应 100 个元素。 如果可用值超过 100 个，响应正文将包含一个 next_page_token 字段，其中包含用于检索下一页结果的令牌。
• 对 Get a single job 和 Get a single job run 请求的响应添加了分页。 在作业 API 2.1 中，新增了对 List job 和 List job runs 请求的响应分页功能。

下面是来自具有 100 多个任务的作业的 Get a single job 请求的示例响应正文。 为了演示基于令牌的分页功能，此示例省略响应正文中包含的大多数字段：

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

若要检索下一组结果，请将下一个请求中的 page_token 查询参数设置为 next_page_token 字段中返回的值。 例如，/api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=。

如果没有更多可用结果，则响应中不包含 next_page_token 字段。

以下部分详细介绍了每个 list 和 get 请求的更新。

对 List jobs 和 List job runs 请求的更改

对于列出作业和列出作业运行请求，删除响应对象根级的 has_more 参数。 而通过 next_page_token 是否存在来判断是否有更多结果可用。 否则，对结果进行分页的功能保持不变。

为了避免响应正文过大，默认情况下，响应中会省略每个作业的顶级 tasks 和 job_clusters 数组。 若要在这些请求的响应正文中为每个作业包含这些数组，请在请求中添加 expand_tasks=true 参数。 启用 expand_tasks 后，tasks 和 job_clusters 数组中最多返回 100 个元素。 如果其中任一数组具有 100 个以上的元素，则 has_more 字段（不会与 job 对象内的根级别 has_more 字段混淆）设置为 true. 但是，只能访问前 100 个元素。 在列出作业请求中超出前 100 个之后，无法检索额外的任务或群集。 要提取更多元素，请使用返回单个作业或单个作业运行的请求。 关于支持对大型响应字段分页的更新将在以下各节中讨论。

获取单个作业

在作业 API 2.2 中，当任一字段的大小超过 100 个元素时，获取单个作业 请求来检索有关单个作业的详细信息，现在支持对 tasks 和 job_clusters 字段进行分页。 使用对象根目录处的 next_page_token 字段来确定是否有更多结果可用。 然后，此字段的值用作后续请求中 page_token 查询参数的值。 一页中元素少于 100 的数组字段将在后续页面中为空。

获取单次运行

在作业 API 2.2 中，获取单次运行请求现在支持对 tasks 和 job_clusters 字段进行分页。当任一字段的大小超过 100 个元素时，可以检索有关单次运行的详细信息。 使用对象根目录处的 next_page_token 字段来确定是否有更多结果可用。 然后，此字段的值用作后续请求中page_token查询参数的值。 一页中元素少于 100 的数组字段将在后续页面上为空。

作业 API 2.2 还将 only_latest 查询参数添加到此终结点，以便仅显示 tasks 数组中的最新运行尝试。 当 only_latest 参数为 true时，任何因重试或修复而被替代的运行将被从响应中省略。

当 run_id 引用 ForEach 任务运行时，响应中存在名为 iterations 的字段。 iterations 字段是一个数组，其中包含 ForEach 任务的嵌套任务的所有运行的详细信息，具有以下属性：

• iterations 数组中每个对象的架构与 tasks 数组中的对象架构相同。
• 如果 only_latest 查询参数设置为 true，则 iterations 数组中仅包含最新的运行尝试。
• 分页应用于 iterations 数组，而不是 tasks 数组。
• tasks 数组仍包含在响应中，并包括 ForEach 任务运行。

若要了解有关 ForEach 任务的详细信息，请参阅 ForEach 任务文档。

例如，请参阅以下针对省略某些字段的 ForEach 任务的响应：

{
  "job_id": 53,
  "run_id": 759600,
  "number_in_job": 7,
  "original_attempt_run_id": 759600,
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": ""
  },
  "cluster_spec": {},
  "start_time": 1595943854860,
  "setup_duration": 0,
  "execution_duration": 0,
  "cleanup_duration": 0,
  "trigger": "ONE_TIME",
  "creator_user_name": "user@databricks.com",
  "run_name": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}