ジョブ API 2.0 から 2.1への更新

Databricks ジョブを使用して複数のタスクを調整できるようになりました。この記事では、複数のタスクを持つジョブをサポートするジョブ API の変更について詳しく説明し、この新機能で動作するように既存の API クライアントを更新するのに役立つガイダンスを提供します。

Databricks では、特に複数のタスクでジョブを使用する場合に、API スクリプトとクライアントにジョブ API 2.1 をお勧めします。

この記事では、1 つのタスクで定義されたジョブを単一タスク形式として、複数のタスクで定義されたジョブを マルチタスク形式と呼びます。

ジョブ API 2.0 および 2.1 で更新要求がサポートされるようになりました。リセット要求の代わりに既存のジョブを変更するには、 update 要求を使用して、単一タスク形式ジョブとマルチタスク形式ジョブ間の変更を最小限に抑えます。

API の変更

ジョブ API は、ジョブ内の各タスクの設定をキャプチャするための TaskSettings オブジェクトを定義するようになりました。マルチタスク・フォーマット・ジョブの場合、 TaskSettings データ構造の配列である tasks フィールドが JobSettings オブジェクトに含まれます。以前は JobSettings の一部であった一部のフィールドは、マルチタスク形式ジョブのタスク設定の一部になりました。 JobSettings も更新され、 format フィールドが含まれるようになりました。 format フィールドはジョブの形式を示し、 SINGLE_TASK または MULTI_TASKに設定された STRING 値です。

マルチタスク形式ジョブの JobSettings に対するこれらの変更については、既存の API クライアントを更新する必要があります。必要な変更の詳細については、 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"
}

Jobs API 2.1 では、タスクレベルクラスターまたは 1 つ以上の共有ジョブクラスターの構成がサポートされています。

タスクレベルのクラスターは、タスクの開始時に作成および開始され、タスクが完了すると終了します。
共有ジョブクラスターでは、同じジョブ内の複数のタスクでクラスターを使用できます。クラスターは、クラスターを使用する最初のタスクの開始時に作成および開始され、クラスターを使用する最後のタスクの完了後に終了します。共有ジョブクラスターは、アイドル状態のときに終了するのではなく、それを使用するすべてのタスクが完了した後にのみ終了します。クラスターを共有する複数の非依存タスクを同時に開始できます。共有ジョブクラスターが失敗した場合、またはすべてのタスクが完了する前に終了した場合は、新しいクラスターが作成されます。

共有ジョブクラスターを構成するには、 JobSettings オブジェクトに JobCluster 配列を含めます。ジョブごとに最大 100 個のクラスターを指定できます。以下は、2 つの共有クラスターで構成されたジョブに対する 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 クライアントに変更を加える必要はありません。

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 呼び出しのガイドライン、例、および必要な変更について説明します。

このセクションの内容：

創造する
実行の送信
更新
リセット
リスト
取得
実行取得
実行は出力を取得します
実行リスト

創造する

Jobs API の Create a new job 操作 (POST /jobs/create) を使用してシングルタスク形式のジョブを作成する場合、既存のクライアントを変更する必要はありません。

マルチタスク形式のジョブを作成するには、 JobSettings の tasks フィールドを使用して、各タスクの設定を指定します。次の例では、2 つのノートブックタスクを持つジョブを作成します。次の例は、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
    }
  ]
}

実行の送信

Jobs API の Create and trigger a one-time run operation (POST /runs/submit)を使用して、シングルタスク形式のジョブの 1 回限りの実行を送信する場合、既存のクライアントを変更する必要はありません。

マルチタスク形式のジョブを 1 回だけ実行するには、 JobSettings の tasks フィールドを使用して、クラスターを含む各タスクの設定を指定します。runs submit 要求は共有ジョブクラスターをサポートしていないため、マルチタスク形式のジョブを送信するときは、クラスターをタスクレベルで設定する必要があります。複数のタスクを指定する JobSettings 例については、「作成」を参照してください。

更新

Jobs API の [Partially update a job ] 操作 (POST /jobs/update) を使用してシングルタスク形式のジョブを更新する場合、既存のクライアントを変更する必要はありません。

マルチタスク形式ジョブの設定を更新するには、一意の task_key フィールドを使用して新しい task 設定を識別する必要があります。複数のタスクを指定する JobSettings 例については、「作成」を参照してください。

リセット

ジョブ API の [ Overwrite all settings for a job operation] (ジョブ操作のすべての設定を上書きする) (POST /jobs/reset) でシングルタスク形式のジョブの設定を上書きする場合、既存のクライアントを変更する必要はありません。

マルチタスク形式ジョブの設定を上書きするには、 TaskSettings データ構造の配列を持つ JobSettings データ構造を指定します。複数のタスクを指定する JobSettings 例については、「作成」を参照してください。

[更新] を使用して、単一タスク形式からマルチタスク形式に切り替えることなく個々のフィールドを変更します。

マルチタスク形式のジョブの場合、ほとんどの設定はジョブレベルではなくタスクレベルで定義されます。クラスター構成は、タスクレベルまたはジョブレベルで設定できます。 Job 構造で返されるマルチタスク形式ジョブのクラスターまたはタスク設定にアクセスするようにクライアントを変更するには:

マルチタスク形式ジョブの job_id フィールドを解析します。
ジョブ API の Get a job 操作 (GET /jobs/get) にjob_idを渡して、ジョブの詳細を取得します。マルチタスク形式のジョブの 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"
    }
  ]
}

取得

シングルタスク形式のジョブの場合、Jobs API の Get a job 操作 (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 a job 実行操作 (GET /jobs/runs/get) からの応答を処理するためにクライアントを変更する必要はありません。

マルチタスク形式のジョブ実行の応答には、 TaskSettingsの配列が含まれます。各タスクの実行結果を取得するには:

各タスクを反復処理します。
各タスクの run_id を解析します。
run_idで Get the output for a run 操作 (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"
}

実行は出力を取得します

シングルタスク形式のジョブの場合、Jobs API の Get the output for a execute 操作 (GET /jobs/runs/get-output) からの応答を処理するためにクライアントを変更する必要はありません。

マルチタスク形式のジョブの場合、実行出力は個々のタスクでのみ使用できるため、親実行で Runs get output を呼び出すとエラーが発生します。マルチタスク形式ジョブの出力とメタデータを取得するには:

実行要求の出力を取得するを呼び出します。
応答の子フィールド run_id 反復処理します。
子 run_id 値を使用して Runs get outputを呼び出します。

実行リスト

シングルタスク形式のジョブの場合、ジョブ操作 (GET /jobs/runs/list) の実行リストからの応答を処理するためにクライアントを変更する必要はありません。

マルチタスク形式のジョブの場合、空の tasks 配列が返されます。 run_id を Get a ジョブ実行操作 (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
}