您現在可以使用 Azure Databricks 任務協作多個工作，。 本文詳細說明了 Jobs API 的變更，支援多任務的工作，並提供指引，幫助你更新現有的 API 客戶端以配合這項新功能。
Databricks 建議在 API 腳本和客戶端中使用作業 API 2.1，特別是在執行含有多個任務的作業時。
本文將定義為單一任務的作業稱為 單一任務格式，而定義為多個任務的作業稱為 多重任務格式。
Jobs API 2.0 和 2.1 現在支援 更新 請求。 使用 update 變更現有工作請求而非 重置 請求，以減少單一任務格式工作與多任務格式工作之間的變更。
API 變更
作業 API 現在會定義 TaskSettings 物件，以擷取作業中每個工作的設定。 對於多任務格式作業，tasks 欄位是 TaskSettings 數據結構的陣列，包含在 JobSettings 物件中。 先前屬於 JobSettings 的某些字段現在是多任務格式工作的任務設定的一部分。
JobSettings 也會更新以包含 format 欄位。 欄位 format 表示作業格式，是設定為 STRING 的值，可為 SINGLE_TASK 或 MULTI_TASK。
你需要更新現有的 API 用戶端，針對多工格式的工作設定進行這些變更。 如需必要變更的詳細資訊，請參閱 API 用戶端指南。
職位 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
}
]
}
執行提交
若要使用 Create 並觸發一次性執行 操作（POST /runs/submit）在作業 API 中提交單任務格式的作業，您不需要更改現有的客戶端。
若要提交多任務格式作業的一次性執行，請使用 tasks 中的 [JobSettings] 欄位來指定每個工作的設定，包括叢集。 提交多工格式工作時，叢集必須在任務層級設定，因為該 runs submit 請求不支援共享工作叢集。 如需指定多個工作的 範例，請參閱 JobSettings。
更新
若要在 Jobs API 中使用 Partially update a job 操作（POST /jobs/update）來更新單一任務格式的工作，你不需要更改現有的客戶端。
要更新多工格式工作的設定，必須使用獨特 task_key 欄位來識別新的 task 設定。 如需指定多個工作的 範例，請參閱 JobSettings。
重置
若要在工作 API 中使用 覆寫作業 操作（POST /jobs/reset）來覆寫單一任務格式作業的設定，您不需要變更現有的客戶端。
若要覆寫多重工作格式作業的設定，請指定包含 JobSettings 數據結構陣列的 TaskSettings 數據結構。 如需指定多個工作的 範例，請參閱 JobSettings。
使用 Update 可以更改個別欄位，無需從單工切換為多工格式。
清單
對於單一任務格式的工作，處理工作 API 中 「列出所有工作 」操作（GET /jobs/list）的回應時，無需更改用戶端。
對於多任務格式作業，大部分的設定都是在工作層級定義，而不是作業層級。 叢集配置可在任務或工作層級設定。 若要修改用戶端，以存取在 Job 結構中傳回之多重工作格式作業的叢集或工作設定：
- 剖析多工格式作業的 [
job_id] 欄位。 - 將 傳遞
job_id到 Jobs API 中的「Get a job operations」（GET /jobs/get）以取得工作細節。 請參閱 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"
}
得分獲得
對於單任務格式的工作，處理 Jobs 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"
}
運行將產生成果
對於單一任務格式的工作，在處理來自取得執行結果操作的回應時，無需更改用戶端設置，即可處理Jobs API 的輸出（GET /jobs/runs/get-output）。
針對多任務格式作業，在父執行上呼叫 Runs get output 會導致錯誤，因為執行輸出僅適用於個別工作。 要取得多工格式作業的輸出與元資料：
- 呼叫 取得執行的輸出 請求。
- 逐一查看回應中的子
run_id欄位。 - 使用子節點的
run_id值來呼叫Runs get output。
執行清單
對於單任務格式的工作，處理來自 列出作業的運行清單操作 的回應無需客戶端變更（GET /jobs/runs/list）。
針對多任務格式作業，會傳回空的 tasks 陣列。 將 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
}