共用方式為

從 Jobs API 2.0 更新至 2.1

  • 發行項

您現在可以使用 Azure Databricks 任務協作多個工作，。 本文詳述 作業 API 的變更，這些變更支援包含多個任務的作業，且提供指引協助您 update 現有的 API 用戶端以因應此新功能。

Databricks 建議在 API 腳本和客戶端中使用作業 API 2.1，特別是在執行含有多個任務的作業時。

本文將定義為單一任務的作業稱為 單一任務格式，而定義為多個任務的作業稱為 多重任務格式。

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

API 變更

作業 API 現在會定義 TaskSettings 物件，以擷取作業中每個工作的設定。 對於多任務格式作業，tasks 欄位是 TaskSettings 數據結構的陣列，包含在 JobSettings 物件中。 先前屬於 JobSettings 的某些字段現在是多任務格式工作的任務設定的一部分。 JobSettings 也會更新以包含 format 欄位。 [format] 字段指出作業的格式，並且是從 set 到 SINGLE_TASK 或 MULTI_TASK的 STRING 值。

您必須 update 現有的 API 用戶端，才能針對多重工作格式作業變更 JobSettings。 如需必要變更的詳細資訊，請參閱 API 用戶端指南。

職位 API 2.1 支援多任務格式。 所有 API 2.1 要求都必須符合此格式，且回應會以此格式進行結構化。

作業 API 2.0 已更新，新增一個欄位，以支援多任務格式的作業。 除了 where 所述，本檔中的範例會使用 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] 欄位來指定每個工作的設定，包括叢集。 提交多任務格式作業時，叢集必須在工作層級 set，因為 runs submit 要求不支援共用作業叢集。 如需指定多個工作的 範例，請參閱 JobSettings。

Update

若要在作業 API 中以 部分 update 的 作業（POST /jobs/update）來執行 update 單一任務格式的作業，您不需要更改現有的用戶端。

若要 update 多重工作格式作業的設定，您必須使用唯一 task_key 欄位來識別新的 task 設定。 如需指定多個工作的 範例，請參閱 JobSettings。

Reset

若要在工作 API 中使用 覆寫作業 操作（POST /jobs/reset）來覆寫單一任務格式作業的設定，您不需要變更現有的客戶端。

若要覆寫多重工作格式作業的設定，請指定包含 JobSettings 數據結構陣列的 TaskSettings 數據結構。 如需指定多個工作的 範例，請參閱 JobSettings。

使用 Update 來變更個別欄位，而不需從單一工作切換到多任務格式。

List

對於單一工作格式作業，不需要任何用戶端變更，即可處理作業 API 中所有作業 作業 作業 （） 的 回應。

對於多任務格式作業，大部分的設定都是在工作層級定義，而不是作業層級。 叢集組態可能是在工作或任務層級 set。 若要修改用戶端，以存取在 Job 結構中傳回之多重工作格式作業的叢集或工作設定：

  • 剖析多工格式作業的 [job_id] 欄位。
  • 將 job_id 傳遞至「作業 API」中的 Get 作業 操作（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"
    }
  ]
}

Get

對於單一工作格式作業，在作業 API 中處理作業 作業 （） 回應時，不需要任何客戶端變更。

多任務格式工作會傳回包含工作設定的 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"
}

執行 get

對於單一工作格式作業，在作業 API 中處理作業執行 作業 （） 回應時，不需要任何客戶端變更。

多工格式作業的執行回應包含一個 TaskSettings陣列。 若要擷取每個工作的執行結果：

  • 反覆執行每個任務。
  • 剖析每個工作中的 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"
}

執行 get 輸出

對於單一工作格式作業，在作業 API 中處理執行 作業 （） 輸出 回應時，不需要任何客戶端變更。

針對多任務格式作業，在父執行上呼叫 Runs get output 會導致錯誤，因為執行輸出僅適用於個別工作。 要執行 get 來處理多工作格式作業的輸出和元數據：

  • 呼叫 Get 執行 要求的輸出。
  • 逐一查看回應中的子 run_id 欄位。
  • 使用子物件 run_idvalues 呼叫 Runs get output。

執行 list

對於單一工作格式作業，處理作業 作業執行 的回應不需要任何用戶端變更（）。

針對多任務格式作業，會傳回空的 tasks 陣列。 將 run_id 傳輸至 Get 執行 任務操作（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
}