從工作 API 2.0 更新至 2.1

文章
10/11/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 欄位指示工作的格式，是設定為 SINGLE_TASK 或 MULTI_TASK 的 STRING 值。

您必須更新現有的 API 用戶端，才能將這些變更套用至多任務格式工作的 JobSettings。如需必要變更的詳細資訊，請參閱 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 欄位設定中設定程式庫；不能在共用工作叢集組態中設定程式庫。在下列範例中，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"
}

對於單一任務格式的工作，除了新增 format 欄位之外，JobSettings 資料結構會維持不變。未包含 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 範例，請參閱建立。

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

清單

對於單任務格式的工作，不需要任何用戶端變更，即可在工作 API 中處理來自列出所有工作操作 (GET /jobs/list) 的回覆。

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

剖析多任務格式工作的 job_id 欄位。
在工作 API 中將 job_id 傳遞至取得工作操作 (GET /jobs/get) 以擷取工作詳細資料。如需多任務格式工作之 Get API 呼叫的回覆範例，請參閱取得。

下列範例顯示包含單任務和多任務格式工作的回覆。此範例適用於 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 傳遞至取得工作執行操作 (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
}

分享方式：

從工作 API 2.0 更新至 2.1

API 變更

API 用戶端指南

本節內容：

建立

執行提交

更新

重設

清單

取得

執行取得

執行取得輸出

執行清單

意見反映

更多資源

分享方式：

從工作 API 2.0 更新至 2.1

API 變更

API 用戶端指南

本節內容：

建立​​

執行提交

更新

重設

清單

取得

執行取得

執行取得輸出

執行清單

意見反映

更多資源

建立