Jobs API 2.1 から 2.2 への更新

この記事では、Jobs API のバージョン 2.2 の機能の更新と拡張について詳しく説明し、この新しいバージョンで動作するように既存の API クライアントを更新するのに役立つ情報が含まれています。 API のバージョン 2.0 と 2.1 の間の変更点については、 Jobs API 2.0 から 2.1 への更新を参照してください。

Jobs API 2.2 バージョンでは、大規模な結果セット のページ分割 に関する既存のサポートが強化されるため、Databricks では、特に応答に多数のタスクが含まれる可能性がある場合に、API スクリプトとクライアントに Jobs API 2.2 を使用することをお勧めします。

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 では、次の要求に対して返される大きな結果セットの方法が変更されます。

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 つのジョブ実行を返す要求 ( Get a single ジョブ と Get a single 実行) を使用します。

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 実行 要求で、tasks フィールドと job_clusters フィールドのいずれかのサイズが 100 要素を超えた場合のページネーションがサポートされるようになりました。 オブジェクト ルートの 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"
}