從作業 API 2.0 更新至 2.1

發行項
03/01/2024

您現在可以使用 Azure Databricks 作業協調多個工作。本文詳細說明支援具有多個工作之作業的作業 API 變更，並提供指引，協助您更新現有的 API 用戶端以使用這項新功能。

Databricks 會針對 API 腳本和用戶端建議作業 API 2.1，特別是在搭配多個工作使用作業時。

本文將單一工作 定義為單一工作格式 的作業，以及以多個 工作定義為多工格式 的工作。

作業 API 2.0 和 2.1 現在支援更新要求。 update使用要求來變更現有的作業，而不是重設要求，將單一工作格式作業與多工作格式作業之間的變更降到最低。

API 變更

作業 API 現在會 TaskSettings 定義物件，以擷取作業中每個工作的設定。針對多工格式作業， tasks 欄位是資料結構的陣列 TaskSettings ，會包含在物件中 JobSettings 。先前部分的 JobSettings 一些欄位現在是多工格式作業之工作設定的一部分。 JobSettings 也會更新為包含 format 欄位。欄位 format 會指出作業的格式，而且是 STRING 設定為 SINGLE_TASK 或 MULTI_TASK 的值。

您必須更新現有的 API 用戶端，才能將這些變更更新為 Job設定多重工作格式作業。如需必要變更的詳細資訊，請參閱 API 用戶端指南。

作業 API 2.1 支援多重工作格式。所有 API 2.1 要求都必須符合多重工作格式，且回應的結構為多重工作格式。新功能會先針對 API 2.1 發行。

作業 API 2.0 會以額外的欄位更新，以支援多重工作格式作業。除非有說明，本檔中的範例會使用 API 2.0。不過，Databricks 建議針對新的和現有的 API 腳本和用戶端使用 API 2.1。

JSON 檔範例，表示 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 2.1 支援設定工作層級叢集或一或多個共用作業叢集：

工作層級叢集會在工作完成時建立並啟動。
共用作業叢集可讓相同作業中的多個工作使用叢集。使用叢集的第一個工作在叢集完成最後一項工作之後開始和終止時，就會建立叢集並啟動叢集。共用作業叢集不會在閒置時終止，而是只有在使用它的所有工作完成之後才會終止。共用叢集的多個非相依工作可以同時啟動。如果共用作業叢集在完成所有工作之前失敗或終止，則會建立新的叢集。

若要設定共用作業叢集， JobCluster 請在物件中包含 JobSettings 陣列。您可以為每個作業指定最多 100 個叢集。以下是使用兩個共用叢集設定之作業的 API 2.1 回應範例：

注意

如果工作具有程式庫相依性，您必須在欄位設定中 task 設定程式庫;無法在共用作業叢集組態中設定程式庫。在下列範例中， libraries 工作組態 ingest_orders 中的欄位示範程式庫相依性規格。

{
  "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 用戶端，即可處理單一工作格式作業。

JSON 檔範例，代表 API 2.0 的單一工作格式作業：

{
  "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 ）建立單一工作格式作業，您不需要變更現有的用戶端。

若要建立多工格式作業，請使用 tasks 中的 JobSettings 欄位來指定每個工作的設定。下列範例會建立具有兩個筆記本工作的作業。此範例適用于 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 ），您不需要變更現有的用戶端。

若要提交多工格式作業的一次性執行，請使用 tasks 中的 JobSettings 欄位來指定每個工作的設定，包括叢集。提交多工格式作業時，必須在工作層級設定叢集，因為 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 多工格式作業的欄位。
job_id將傳遞至作業 API 中的取得作業作業（ 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 陣列並擷取所需的欄位。

下列顯示來自 API 呼叫多重工作格式作業的 Get 範例回應。此範例適用于 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 每個工作的。
使用呼叫取得執行作業的輸出（ GET /jobs/runs/get-output ）， run_id 以取得每個工作執行的詳細資料。以下是來自此要求的範例回應：

{
  "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 。

執行清單

對於單一工作格式作業，不需要任何用戶端變更，即可處理從 List 執行作業的回應（ GET /jobs/runs/list ）。

針對多工格式作業，會傳回空 tasks 陣列。 run_id將傳遞至取得作業執行作業（ GET /jobs/runs/get ）以擷取工作。以下顯示來自 API 呼叫多重工作格式作業的 Runs list 範例回應：

{
  "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
}

共用方式為

從作業 API 2.0 更新至 2.1

API 變更

API 用戶端指南

本節內容：

創建

執行提交

更新

重置

清單

獲取

執行取得

執行取得輸出

執行清單

其他資源

共用方式為

從作業 API 2.0 更新至 2.1

API 變更

API 用戶端指南

本節內容：

創建

執行提交

更新

重 置

清單

獲取

執行取得

執行取得輸出

執行清單

其他資源

重置