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

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

Databricks では、特に複数のタスクを含むジョブを使用する場合、API スクリプトとクライアントにジョブ API 2.1 を推奨しています。

本稿では、単一のタスクで定義されたジョブをシングルタスク形式、複数のタスクで定義されたジョブをマルチタスク形式と呼びます。

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

APIの変更

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

マルチタスク形式のジョブの JobSettings に対するこれらの変更に合わせて、既存の API クライアントを更新する必要があります。必要な変更の詳細については、 APIクライアントガイドを参照してください。

Jobs API 2.1 はマルチタスク形式をサポートしています。すべての API 2.1 リクエストはマルチタスク形式に準拠する必要があり、応答はマルチタスク形式で構造化されます。新しい機能はまず API 2.1 でリリースされます。

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

ジョブ 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"
}

シングルタスク形式のジョブの場合、 JobSettingsデータ構造は、 formatフィールドの追加を除いて変更されません。 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 呼び出しのガイドライン、例、および必要な変更について説明します。

このセクションの内容：

作成
実行を送信
更新
リセット
リスト
取得
実行 get
実行すると出力が得られる
実行リスト

創造する

ジョブ API の「新しいジョブの作成」操作 ( 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
    }
  ]
}

実行を送信

ジョブ API の「1 回限りの実行の作成とトリガー」操作 ( POST /runs/submit ) を使用して、単一タスク形式のジョブの 1 回限りの実行を送信する場合、既存のクライアントを変更する必要はありません。

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

更新

ジョブ API のジョブの部分更新操作 ( POST /jobs/update ) を使用して単一タスク形式のジョブを更新する場合、既存のクライアントを変更する必要はありません。

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

リセット

ジョブ API の「ジョブのすべての設定を上書きする」操作 ( POST /jobs/reset ) を使用して単一タスク形式のジョブの設定を上書きする場合、既存のクライアントを変更する必要はありません。

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

更新を使用すると、シングルタスク形式からマルチタスク形式に切り替えることなく、個々のフィールドを変更できます。

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

マルチタスク形式のジョブのjob_idフィールドを解析します。
ジョブの詳細を取得するには、 job_idをジョブ API のジョブ取得操作 ( 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 /jobs/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

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

マルチタスク形式のジョブ実行に対する応答には、 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 クライアントガイド