从作业 API 2.0 更新到 2.1

项目
11/13/2023

现在可以使用 Azure Databricks 作业编排多个任务。本文详细介绍支持包含多个任务的作业的作业 API 更改，并提供指导以帮助更新现有 API 客户端来使用此新功能。

Databricks 建议对 API 脚本和客户端使用作业 API 2.1，尤其是在使用包含多个任务的作业时。

本文将使用单个任务定义的作业称为单任务格式，将使用多个任务定义的作业称为多任务格式。

作业 API 2.0 和 2.1 现在支持 update 请求。使用 update 请求更改现有作业而不是 reset 请求，以最大程度地减少单任务格式作业和多任务格式作业之间的更改。

API 更改

作业 API 现在定义 TaskSettings 对象以捕获作业中每个任务的设置。对于多任务格式作业，tasks 字段（TaskSettings 数据结构的数组）包含在 JobSettings 中。以前是 JobSettings 一部分的某些字段现在是多任务格式作业的任务设置的一部分。 JobSettings 还会更新以包含 format 字段。 format 字段指示作业的格式，是设置为 STRING 或 SINGLE_TASK 的 MULTI_TASK 值。

对于多任务格式作业，需要更新现有 API 客户端以实现对 JobSettings 的这些更改。有关所需更改的详细信息，请参阅 API 客户端指。

作业 API 2.1 支持多任务格式。所有 API 2.1 请求都必须符合多任务格式，响应的结构也采用多任务格式。首先为 API 2.1 发布新功能。

对作业 API 2.0 进行了更新，增加了一个字段，以支持多任务格式作业。除非另有说明，否则本文档中的示例使用 API 2.0。但是，Databricks 建议对新的和现有的 API 脚本和客户端使用 API 2.1。

表示 API 2.0 和 2.1 的多任务格式作业的示例 JSON 文档：

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

作业 API 2.1 支持配置任务级群集或者一个或多个共享的作业群集：

任务级群集在任务启动时创建并启动，在任务完成时终止。
共享作业群集允许同一作业中的多个任务使用该群集。群集在使用群集的第一个任务启动时创建并启动，在使用群集的最后一个任务完成后终止。共享作业群集在空闲时不会终止，而是只在使用它的所有任务完成后终止。共享某个群集的多个非依赖任务可以同时启动。如果在所有任务完成之前共享作业群集失败或终止，则会创建一个新的群集。

若要配置共享作业群集，请在 JobSettings 对象中包括一个 JobCluster 数组。最多可为每个作业指定 100 个群集。下面是配置了两个共享群集的作业的 API 2.1 响应示例：

注意

如果任务具有库依赖项，则必须在 task 字段设置中配置库；不能在共享作业群集配置中配置库。在下面的示例中，ingest_orders 任务的配置中的 libraries 字段展示了库依赖项的规范。

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "job_clusters": [
      {
        "job_cluster_key": "default_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "i3.xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 2,
            "max_workers": 8
          }
        }
      },
      {
        "job_cluster_key": "data_processing_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "r4.2xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 8,
            "max_workers": 16
          }
        }
      }
    ],
    "tasks": [
      {
        "task_key": "ingest_orders",
        "description": "Ingest order data",
        "depends_on": [ ],
        "job_cluster_key": "auto_scaling_cluster",
        "spark_jar_task": {
          "main_class_name": "com.databricks.OrdersIngest",
          "parameters": [
            "--data",
            "dbfs:/path/to/order-data.json"
          ]
        },
        "libraries": [
          {
            "jar": "dbfs:/mnt/databricks/OrderIngest.jar"
          }
        ],
        "timeout_seconds": 86400,
        "max_retries": 3,
        "min_retry_interval_millis": 2000,
        "retry_on_timeout": false
      },
      {
        "task_key": "clean_orders",
        "description": "Clean and prepare the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "job_cluster_key": "default_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_orders",
        "description": "Perform an analysis of the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "job_cluster_key": "data_processing_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

对于单任务格式作业，JobSettings 数据结构保持不变，只不过添加了 format 字段。不包含 TaskSettings 数组，并且任务设置仍在 JobSettings 数据结构的顶层进行定义。无需对现有 API 客户端进行更改即可处理单任务格式作业。

表示 API 2.0 单任务格式作业的示例 JSON 文档：

{
  "job_id": 27,
  "settings": {
    "name": "Example notebook",
    "existing_cluster_id": "1201-my-cluster",
    "libraries": [
      {
        "jar": "dbfs:/FileStore/jars/spark_examples.jar"
      }
    ],
    "email_notifications": {},
    "timeout_seconds": 0,
    "schedule": {
      "quartz_cron_expression": "0 0 0 * * ?",
      "timezone_id": "US/Pacific",
      "pause_status": "UNPAUSED"
    },
    "notebook_task": {
      "notebook_path": "/notebooks/example-notebook",
      "revision_timestamp": 0
    },
    "max_concurrent_runs": 1,
    "format": "SINGLE_TASK"
  },
  "created_time": 1504128821443,
  "creator_user_name": "user@databricks.com"
}

API 客户端指南

本部分提供受新的多任务格式功能影响的 API 调用的指导原则、示例和所需更改。

创建

若要在作业 API 中通过创建新作业操作 (POST /jobs/create) 创建单任务格式作业，无需更改现有客户端。

若要创建多任务格式作业，请使用 JobSettings 中的 tasks 字段为每个任务指定设置。以下示例创建一个包含两个笔记本任务的作业。此示例适用于 API 2.0 和 2.1：

注意

最多可为每个作业指定 100 个任务。

{
  "name": "Multi-task-job",
  "max_concurrent_runs": 1,
  "tasks": [
    {
      "task_key": "clean_data",
      "description": "Clean and prepare the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/clean-data"
      },
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    },
    {
      "task_key": "analyze_data",
      "description": "Perform an analysis of the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/analyze-data"
      },
      "depends_on": [
        {
          "task_key": "clean_data"
        }
      ],
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    }
  ]
}

运行提交

若要在作业 API 中通过创建和触发一次性运行操作 (POST /runs/submit) 提交单任务格式作业的一次性运行，无需更改现有客户端。

若要提交多任务格式作业的一次性运行，请使用 JobSettings 中的 tasks 字段为每个任务指定设置（包括群集）。在提交多任务格式作业时，必须在任务级别设置群集，因为 runs submit 请求不支持共享作业群集。有关指定多个任务的示例 JobSettings，请参阅创建。

更新

若要在作业 API 中通过部分更新作业操作 (POST /jobs/update) 更新单任务格式作业，无需更改现有客户端。

若要更新多任务格式作业的设置，必须使用唯一的 task_key 字段标识新 task 设置。有关指定多个任务的示例 JobSettings，请参阅创建。

重置

若要在作业 API 中通过覆盖作业的所有设置操作 (POST /jobs/reset) 覆盖单任务格式作业的设置，无需更改现有客户端。

若要覆盖多任务格式作业的设置，请指定具有 TaskSettings 数据结构数组的 JobSettings 数据结构。有关指定多个任务的示例 JobSettings，请参阅创建。

使用 Update 可以更改单个字段，而无需从单任务转换为多任务格式。

列表

对于单任务格式作业，无需进行客户端更改即可处理来自作业 API 中列出所有作业操作 (GET /jobs/list) 的响应。

对于多任务格式作业，大多数设置在任务级别而不是作业级别进行定义。可以在任务或作业级别设置群集配置。若要修改客户端以访问 Job 结构中返回的多任务格式作业的群集或任务设置，请执行以下操作：

分析多任务格式作业的 job_id 字段。
在作业 API 中将 job_id 传递到获取作业操作 (GET /jobs/get) 以检索作业详细信息。有关来自针对多任务格式作业的 API 调用的示例响应，请参阅获取Get。

下面的示例演示一个包含单任务和多任务格式作业的响应。此示例适用于 API 2.0：

{
  "jobs": [
    {
      "job_id": 36,
      "settings": {
        "name": "A job with a single task",
        "existing_cluster_id": "1201-my-cluster",
        "email_notifications": {},
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/example-notebook",
          "revision_timestamp": 0
        },
        "max_concurrent_runs": 1,
        "format": "SINGLE_TASK"
      },
      "created_time": 1505427148390,
      "creator_user_name": "user@databricks.com"
    },
    {
      "job_id": 53,
      "settings": {
        "name": "A job with multiple tasks",
        "email_notifications": {},
        "timeout_seconds": 0,
        "max_concurrent_runs": 1,
        "format": "MULTI_TASK"
      },
      "created_time": 1625841911296,
      "creator_user_name": "user@databricks.com"
    }
  ]
}

获取

对于单任务格式作业，无需进行客户端更改即可处理来自作业 API 中获取作业操作 (GET /jobs/get) 的响应。

多任务格式作业会返回包含任务设置的 task 数据结构数组。如果需要访问任务级别详细信息，则需要修改客户端以循环访问 tasks 数组并提取所需字段。

下面显示来自针对多任务格式作业的 Get API 调用的示例响应。此示例适用于 API 2.0 和 2.1：

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

运行获取

对于单任务格式作业，无需进行客户端更改即可处理来自作业 API 中获取作业运行操作 (GET /jobs/runs/get) 的响应。

多任务格式作业运行的响应包含 TaskSettings 的数组。若要检索每个任务的运行结果，请执行以下操作：

循环访问每个任务。
分析每个任务的 run_id。
使用 run_id 调用获取运行的输出操作 (GET /jobs/runs/get-output) 以获取关于每个任务的运行的详细信息。下面是此请求的示例响应：

{
  "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": "Query logs",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759601,
      "task_key": "query-logs",
      "description": "Query session logs",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/log-query"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "validate_output",
      "description": "Validate query output",
      "depends_on": [
        {
          "task_key": "query-logs"
        }
      ],
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/validate-query-results"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK"
}

运行获取输出

对于单任务格式作业，无需进行客户端更改即可处理来自作业 API 中获取运行的输出操作 (GET /jobs/runs/get-output) 的响应。

对于多任务格式作业，对父运行调用 Runs get output 会导致错误，因为运行输出仅适用于单个任务。若要获取多任务格式作业的输出和元数据，请执行以下操作：

调用获取运行的输出请求。
循环访问响应中的子 run_id 字段。
使用子 run_id 值调用 Runs get output。

运行列表

对于单任务格式作业，无需进行客户端更改即可处理来自列出作业运行操作 (GET /jobs/runs/list) 的响应。

对于多任务格式作业，会返回空 tasks 数组。将 run_id 传递到run_id操作 (GET /jobs/runs/get) 以检索任务。下面显示来自针对多任务格式作业的 Runs list API 调用的示例响应：

{
  "runs": [
    {
      "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": "Query logs",
      "run_type": "JOB_RUN",
      "tasks": [],
      "format": "MULTI_TASK"
    }
  ],
  "has_more": false
}

通过