この記事では、Jobs API のバージョン 2.2 の機能の更新と機能強化について詳しく説明します。 この新しいバージョンで動作するように既存の API クライアントを更新するのに役立つ情報が含まれています。 これらの更新には、ジョブの既定のキューが含まれており、応答に 100 を超える要素を含むフィールドが含まれている場合の ページ分割 のサポートが向上します。 バージョン 2.2 では、大規模な結果セットのページ分割に関する既存のサポートが強化されているため、Databricks では、特に応答に多くのタスクが含まれる可能性がある場合に、API スクリプトとクライアントに使用することをお勧めします。
API のバージョン 2.0 と 2.1 の間の変更については、「 ジョブ API 2.0 から 2.1 への更新」を参照してください。
Lakeflow Jobs API のバージョン 2.1 に含まれる変更に加えて、バージョン 2.2 には次の機能強化があります。
ジョブはデフォルトでキューに登録されます
ジョブ キューは、リソースが実行に使用できない場合にジョブの実行がスキップされないようにするオプションの機能です。 ジョブ キューは、ジョブ API の 2.0、2.1、および 2.2 バージョンでサポートされており、キューの既定の処理では次の違いがあります。
- Jobs API 2.2 で作成されたジョブの場合、キューは既定で有効になります。 ジョブを作成または更新するときに、
queueフィールドを要求本文でfalseに設定することで、キューを無効にすることができます。 - 2.0 バージョンと 2.1 バージョンのジョブ API で作成されたジョブの場合、キューは既定では有効 になりません 。 これらのバージョンでは、ジョブを作成または更新するときに、
queueフィールドを要求本文でtrueに設定して、キューを有効にする必要があります。
ジョブの作成時、ジョブの一部の更新時、またはすべてのジョブ設定の更新時に、キューを有効または無効にすることができます。
ジョブキューイングを参照してください。
長いタスクとタスクの実行リストのページングのサポート
タスクまたはタスクの実行数が多いジョブをサポートするために、Jobs API 2.2 では、次の要求に対して返される大きな結果セットの量が変更されます。
-
ジョブの一覧表示:
List jobsおよびList job runs要求に対する変更を参照してください。 -
ジョブの実行を一覧表示する:
List jobs要求とList job runs要求に対する変更を参照してください。 - 1 つのジョブを取得する: 「 1 つのジョブを取得する」を参照してください。
- 単一のジョブを実行する: 単一実行を取得するを参照してください。
Jobs API 2.2 は、これらの要求の改ページ位置を次のように変更します。
- タスク、パラメーター、job_clusters、環境などの要素のリストを表すフィールドは、応答ごとに 100 個の要素に制限されます。 100 を超える値が使用可能な場合、応答本文には、結果の次のページを取得するトークンを含む
next_page_tokenフィールドが含まれます。 -
Get a single jobおよびGet a single job run要求への応答に対する改ページが追加されます。 ジョブ API 2.1 を使用して、List job要求とList job runs要求への応答の改ページが追加されました。
100 個を超えるタスクを含むジョブの Get a single job 要求からの応答本文の例を次に示します。 トークンベースのページング機能を示すために、この例では応答本文に含まれるほとんどのフィールドを省略しています。
{
"job_id": 11223344,
"settings": {
"tasks": [
{
"task_key": "task-1"
},
{
"task_key": "task-2"
},
{
"task_key": "task-..."
},
{
"task_key": "task-100"
}
]
},
"next_page_token": "Z29...E="
}
次の結果セットを取得するには、次の要求の page_token クエリ パラメーターを、 next_page_token フィールドに返される値に設定します。 たとえば、/api/2.2/jobs/get?job_id=11223344&page_token=Z29...E= のようにします。
これ以上結果が得られない場合、 next_page_token フィールドは応答に含まれません。
次のセクションでは、各 list および get 要求の更新について詳しく説明します。
List jobs要求とList job runs要求に対する変更
List ジョブと List ジョブ実行要求の場合、応答オブジェクトのルート レベルの has_more パラメーターが削除されます。 代わりに、 next_page_token の存在を使用して、より多くの結果が使用可能かどうかを判断します。 それ以外の場合、結果を改ページ処理する機能は変更されません。
応答本文が大きくなるのを防ぐため、各ジョブの最上位 tasks 配列と job_clusters 配列は、既定では応答から省略されます。 これらの要求の応答本文に含まれるジョブごとにこれらの配列を含めるには、 expand_tasks=true パラメーターを要求に追加します。
expand_tasksが有効になっている場合、tasksおよびjob_clusters配列には最大 100 個の要素が返されます。 これらの配列のいずれかが 100 を超える要素を持つ場合、has_more オブジェクト内のhas_more フィールド (削除されるルート レベルのjob フィールドと混同しないでください) は true. に設定されますが、最初の 100 個の要素にのみアクセスできます。
List ジョブ要求で最初の 100 より後に追加のタスクまたはクラスターを取得することはできません。 さらに多くの要素をフェッチするには、単一のジョブまたは単一のジョブ実行を返すリクエストを使用します。 大きな応答フィールドのページ分割をサポートする更新については、次のセクションで説明します。
1つのタスクを得る
Jobs API 2.2 では、1 つのジョブに関する詳細を取得する 1 つのジョブ 要求の取得で、いずれかのフィールドのサイズが 100 個の要素を超えた場合に、 tasks フィールドと job_clusters フィールドの改ページがサポートされるようになりました。 オブジェクト ルートの next_page_token フィールドを使用して、より多くの結果が得られているかどうかを判断します。 このフィールドの値は、後続の要求で page_token クエリ パラメーターの値として使用されます。 1 ページの要素数が 100 未満の配列フィールドは、後続のページでは空になります。
1回の実行を得る
Jobs API 2.2 では、1 回の実行に関する詳細を取得する 1 回の実行 要求で、いずれかのフィールドのサイズが 100 個の要素を超えた場合の tasks フィールドと job_clusters フィールドの改ページがサポートされるようになりました。 オブジェクト ルートの next_page_token フィールドを使用して、より多くの結果が得られているかどうかを判断します。 このフィールドの値は、後続の要求でpage_tokenクエリ パラメーターの値として使用されます。 1 ページの要素数が 100 未満の配列フィールドは、後続のページでは空になります。
ジョブ API 2.2 では、 only_latest クエリ パラメーターもこのエンドポイントに追加され、 tasks 配列内の最新の実行試行のみを表示できるようになります。
only_latest パラメーターがtrueされると、再試行または修復によって置き換えられたすべての実行が応答から省略されます。
run_idがForEachタスクの実行を参照する場合、応答には iterations という名前のフィールドが存在します。
iterations フィールドは、ForEach タスクの入れ子になったタスクのすべての実行の詳細を含む配列で、次のプロパティを持ちます。
-
iterations配列内の各オブジェクトのスキーマは、tasks配列内のオブジェクトのスキーマと同じです。 -
only_latestクエリ パラメーターがtrueに設定されている場合、最新の実行試行のみがiterations配列に含まれます。 - 改ページは、
iterations配列に適用され、tasks配列には適用されません。 -
tasks配列は引き続き応答に含まれており、ForEachタスクの実行が含まれます。
ForEach タスクの詳細については、ForEach タスクのドキュメントを参照してください。
たとえば、一部のフィールドを省略した ForEach タスクについては、次の応答を参照してください。
{
"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": "process_all_numbers",
"run_type": "JOB_RUN",
"tasks": [
{
"run_id": 759600,
"task_key": "process_all_numbers",
"description": "Process all numbers",
"for_each_task": {
"inputs": "[ 1, 2, ..., 101 ]",
"concurrency": 10,
"task": {
"task_key": "process_number_iteration"
"notebook_task": {
"notebook_path": "/Users/user@databricks.com/process_single_number",
"base_parameters": {
"number": "{{input}}"
}
}
},
"stats": {
"task_run_stats": {
"total_iterations": 101,
"scheduled_iterations": 101,
"active_iterations": 0,
"failed_iterations": 0,
"succeeded_iterations": 101,
"completed_iterations": 101
}
}
}
"state": {
"life_cycle_state": "TERMINATED",
"result_state": "SUCCESS",
"state_message": ""
}
}
],
"iterations": [
{
"run_id": 759601,
"task_key": "process_number_iteration",
"notebook_task": {
"notebook_path": "/Users/user@databricks.com/process_single_number",
"base_parameters": {
"number": "{{input}}"
}
},
"state": {
"life_cycle_state": "TERMINATED",
"result_state": "SUCCESS",
"state_message": ""
}
},
{
"run_id": 759602,
"task_key": "process_number_iteration",
"notebook_task": {
"notebook_path": "/Users/user@databricks.com/process_single_number",
"base_parameters": {
"number": "{{input}}"
}
},
"state": {
"life_cycle_state": "TERMINATED",
"result_state": "SUCCESS",
"state_message": ""
}
}
],
"format": "MULTI_TASK",
"next_page_token": "eyJ..x9"
}