从作业 API 2.1 更新到 2.2

项目
2025-01-10

本文详细介绍了作业 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 还具有以下增强：

作业默认队列

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

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

可以在创建作业、不分更新作业或更新所有作业设置时启用或禁用队列。

请参阅作业队列。

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

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

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

作业 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 中，检索有关单个运行的详细信息的获取单个运行请求现在支持在任一字段的大小超过 100 个元素时对 tasks 和 job_clusters 字段进行分页。使用对象根处的 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"
}

通过