Jobs API 2.1 から 2.2 への更新
この記事では、Jobs API のバージョン 2.2 の機能の更新と強化について詳しく説明します。 これには、この新しいバージョンで動作するように既存の API クライアントを更新するのに役立つ情報が含まれています。 これらの更新には、ジョブのデフォルトのキューイングと、応答に 100 を超える要素を含むフィールドが含まれている場合の ページ分割 のサポートの改善が含まれます。 バージョン 2.2 では、大きな結果セットのページ分割に関する既存のサポートが強化されるため、Databricks では、特に応答に多くのタスクが含まれる可能性がある場合に、API スクリプトとクライアントに使用することをお勧めします。
API のバージョン 2.0 と 2.1 の間の変更点については、 Jobs API 2.0 から 2.1 への更新を参照してください。
Databricks ジョブ API のバージョン 2.1 に含まれる変更に加えて、バージョン 2.2 には次の機能強化があります。
ジョブはデフォルトでキューに入れられます
ジョブ キューイングは、リソースが実行に使用できない場合にジョブ実行がスキップされるのを防ぐオプション機能です。 ジョブのキューイングは、ジョブ API の 2.0、2.1、および 2.2 バージョンでサポートされていますが、キューイングのデフォルト処理には次の違いがあります。
- Jobs API 2.2 で作成されたジョブの場合、キューイングはデフォルトで有効になっています。 キューイングをオフにするには、ジョブを作成または更新するときに、要求本文で
queueフィールドをfalseに設定します。 - Jobs API の 2.0 および 2.1 バージョンで作成されたジョブの場合、キューイングはデフォルトでは有効に なっていません 。 これらのバージョンでは、ジョブを作成または更新するときに、要求本文で
queueフィールドをtrueに設定して、キューイングを有効にする必要があります。
キューイングは、 ジョブの作成時、 ジョブの部分的な更新時、または すべてのジョブ設定の更新時に有効または無効にできます。
ジョブのキューイングを参照してください。
長いタスクとタスク実行リストのページングのサポート
多数のタスクまたはタスク実行を持つジョブをサポートするために、ジョブ API 2.2 では、次の要求に対して返される大きな結果セットの方法が変更されます。
- ジョブの一覧表示: 「
List jobsおよびList job runs要求の変更」を参照してください。 - ジョブの実行を一覧表示する: 「
List jobsおよびList job runs要求の変更」を参照してください。 - 1 つのジョブを取得する: 「1 つのジョブを取得する」を参照してください。
- 1 つのジョブの実行を取得する: 「1 つの実行を取得する」を参照してください。
Jobs API 2.2 では、これらのリクエストのページネーションが次のように変更されます。
- タスク、パラメーター、ジョブ、環境などの要素のリストを表すフィールドは、応答ごとに 100 個の要素に制限されています。 100 を超える値が使用可能な場合、応答本文には、結果の次のページを取得するためのトークンを含む
next_page_tokenフィールドが含まれます。 Get a single job要求とGet a single job run要求への応答に対して、ページネーションが追加されます。List jobとList job runsリクエストへのレスポンスのページネーションは、Jobs API 2.1 で追加されました。
以下は、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 個を超える要素がある場合、job オブジェクト内の has_more フィールド (削除されるルート レベルの has_more フィールドと混同しないでください) は true. に設定されます。ただし、アクセスできるのは最初の 100 個の要素だけです。List ジョブ要求の最初の 100 個以降は、追加のタスクまたはクラスターを取得することはできません。より多くの要素をフェッチするには、1 つのジョブまたは 1 つのジョブ実行を返す要求を使用します。 大きなレスポンスフィールドのページ分割をサポートする更新については、次のセクションで説明します。
1つのジョブを取得する
ジョブ API 2.2 では、1 つのジョブの詳細を取得する Get a single ジョブ 要求で、いずれかのフィールドのサイズが 100 要素を超える場合に、tasks フィールドと job_clusters フィールドの改ページ位置の自動修正がサポートされるようになりました。 オブジェクト ルートの next_page_token フィールドを使用して、使用可能な結果が他にもあるかどうかを判断します。 このフィールドの値は、後続の要求で page_token クエリ パラメーターの値として使用されます。 1 ページ内の要素数が 100 未満の配列フィールドは、後続のページでは空になります。
1 回の実行を取得する
ジョブ API 2.2 では、1 つの実行に関する詳細を取得する Get a single 実行 要求で、いずれかのフィールドのサイズが 100 要素を超えた場合に、tasks フィールドと job_clusters フィールドの改ページ位置の自動修正がサポートされるようになりました。 オブジェクト ルートの next_page_token フィールドを使用して、使用可能な結果が他にもあるかどうかを判断します。 このフィールドの値は、後続の要求で page_token クエリ パラメーターの値として使用されます。 1 ページ内の要素数が 100 未満の配列フィールドは、後続のページでは空になります。
Jobs API 2.2 では、このエンドポイントに only_latest クエリ パラメーターも追加され、 tasks 配列内の最新の実行試行のみを表示できるようになります。 only_latest パラメーターが trueの場合、再試行または修復によって置き換えられた実行は応答から省略されます。
run_idがForEachタスクの実行を参照している場合、レスポンスには iterations という名前のフィールドが存在します。iterations フィールドは、ForEach タスクのネストされたタスクのすべての実行の詳細を含む配列で、次のプロパティがあります。
iterations配列内の各オブジェクトのスキーマは、tasks配列内のオブジェクトのスキーマと同じです。only_latestクエリ パラメーターがtrueに設定されている場合、最新の実行試行のみがiterations配列に含まれます。- 改ページ位置の自動修正は、
tasks配列ではなくiterations配列に適用されます。 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"
}