Freigeben über

Das Aktualisieren der Jobs-API von 2.1 auf 2.2

In diesem Artikel werden Updates und Verbesserungen der Funktionalität in Version 2.2 der Auftrags-API beschrieben. Es enthält Informationen, mit denen Sie Ihre vorhandenen API-Clients aktualisieren können, um mit dieser neuen Version zu arbeiten. Zu diesen Updates gehören standardmäßige Warteschlangen von Aufträgen und eine bessere Unterstützung für das Paginieren , wenn Antworten Felder mit mehr als 100 Elementen enthalten. Da Version 2.2 die vorhandene Unterstützung für das Paginieren großer Resultsets verbessert, empfiehlt Databricks die Verwendung für Ihre API-Skripts und -Clients, insbesondere wenn Antworten viele Aufgaben umfassen können.

Informationen zu den Änderungen zwischen Den Versionen 2.0 und 2.1 der API finden Sie unter Aktualisieren von Jobs API 2.0 auf 2.1.

Zusätzlich zu den Änderungen, die in Version 2.1 der Lakeflow Jobs-API enthalten sind, hat Version 2.2 die folgenden Verbesserungen:

Aufträge werden standardmäßig in die Warteschlange gestellt.

Die Auftragswarteschlange ist ein optionales Feature, das verhindert, dass der Auftrag übersprungen wird, wenn Ressourcen für die Ausführung nicht verfügbar sind. Die Auftragswarteschlange wird in den Versionen 2.0, 2.1 und 2.2 der Auftrags-API unterstützt; dabei treten die folgenden Unterschiede bei der Standardbehandlung der Warteschlange auf:

  • Für Jobs, die mit der Jobs-API 2.2 erstellt wurden, ist die Warteschlange standardmäßig aktiviert. Sie können die Warteschlangenfunktion deaktivieren, indem Sie das Feld queue auf false im Anforderungskörper festlegen, wenn Sie einen Auftrag erstellen oder aktualisieren.
  • Für Aufträge, die mit den Versionen 2.0 und 2.1 der Auftrags-API erstellt wurden, ist die Warteschlange standardmäßig nicht aktiviert. Bei diesen Versionen müssen Sie das Queueing aktivieren, indem Sie das Feld queue im Anforderungskörper auf true festlegen, wenn Sie einen Auftrag erstellen oder aktualisieren.

Sie können die Warteschlangen aktivieren oder deaktivieren, wenn Sie einen Auftrag erstellen, einen Auftrag teilweise aktualisieren oder alle Auftragseinstellungen aktualisieren.

Siehe Auftragswarteschlange.

Unterstützung für die Blätterung langer Aufgaben- und Aufgabenlauflisten

Um Aufträge mit einer großen Anzahl von Aufgaben oder Aufgabenausführungen zu unterstützen, ändert die Auftrags-API 2.2, wie große Resultsets für die folgenden Anforderungen zurückgegeben werden:

Die Jobs-API 2.2 ändert die Paginierung für diese Anforderungen wie folgt:

  • Felder, die Listen von Elementen wie Aufgaben, Parametern, job_clusters oder Umgebungen darstellen, sind pro Antwort auf 100 Elemente beschränkt. Wenn mehr als 100 Werte verfügbar sind, enthält der Antworttext ein next_page_token Feld, das ein Token enthält, um die nächste Seite mit Ergebnissen abzurufen.
  • Die Paginierung wird für die Antworten auf die Get a single job und Get a single job run Anfragen hinzugefügt. Die Paginierung für die Antworten auf die List job und List job runs Anfragen wurde mit der Auftrags-API 2.1 hinzugefügt.

Es folgt ein Beispielantworttext aus einer Get a single job Anforderung für einen Auftrag mit mehr als 100 Aufgaben. Um die tokenbasierte Pagingfunktion zu veranschaulichen, werden in diesem Beispiel die meisten Felder ausgelassen, die im Antworttext enthalten sind:

{
  "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="
}

Um den nächsten Satz von Ergebnissen abzurufen, legen Sie den page_token Abfrageparameter in der nächsten Anforderung auf den Wert fest, der im next_page_token Feld zurückgegeben wird. Beispiel: /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Wenn keine weiteren Ergebnisse verfügbar sind, ist das next_page_token Feld nicht in der Antwort enthalten.

In den folgenden Abschnitten finden Sie weitere Details zu den Aktualisierungen der einzelnen list- und get-Anforderungen.

Änderungen an den List jobs Und List job runs Anforderungen

Für die Listenaufträge und Listen der Jobausführungen Anfragen wird der has_more Parameter auf der Stammebene des Antwortobjekts entfernt. Verwenden Sie stattdessen das Vorhandensein der next_page_token Daten, um festzustellen, ob weitere Ergebnisse verfügbar sind. Andernfalls bleiben die Funktionen zum Paginieren von Ergebnissen unverändert.

Um große Antworttexte zu vermeiden, werden standardmäßig die Top-Level-Arrays der tasks und job_clusters für jeden Job aus den Antworten ausgelassen. Um diese Arrays für jeden Auftrag einzuschließen, der im Antworttext für diese Anforderungen enthalten ist, fügen Sie der Anforderung den expand_tasks=true Parameter hinzu. Wenn expand_tasks aktiviert ist, werden maximal 100 Elemente in den Arrays tasks und job_clusters zurückgegeben. Wenn eines dieser Arrays mehr als 100 Elemente hat, wird ein has_more-Feld innerhalb des has_more-Objekts auf job gesetzt (nicht zu verwechseln mit dem entfernten Feld auf der Stammebene true.). Es kann jedoch nur auf die ersten 100 Elemente zugegriffen werden. Sie können nach der ersten 100 mit der Anforderung " Aufträge auflisten " keine weiteren Aufgaben oder Cluster abrufen. Verwenden Sie zum Abrufen weiterer Elemente die Anfragen, die einen einzelnen Job oder einen einzelnen Auftrag ausführen. Die Updates, die das Paginieren großer Antwortfelder unterstützen, werden in den folgenden Abschnitten erläutert.

Einzelnen Auftrag erhalten

In der Jobs-API 2.2 unterstützt die Anforderung, Details zu einem einzelnen Auftrag abzurufen, jetzt die Paginierung der Felder tasks und job_clusters, wenn die Größe eines der beiden Felder mehr als 100 Elemente überschreitet. Verwenden Sie das next_page_token Feld im Objektstamm, um zu ermitteln, ob weitere Ergebnisse verfügbar sind. Der Wert dieses Felds wird dann als Wert für den page_token Abfrageparameter in nachfolgenden Anforderungen verwendet. Arrayfelder mit weniger als 100 Elementen auf einer Seite sind auf nachfolgenden Seiten leer.

Eine einzelne Ausführung abrufen

In der Auftrags-API 2.2 unterstützt die Anforderung zum Abrufen von Details zu einer einzelnen Ausführung jetzt die Paginierung der Felder tasks und job_clusters, wenn die Größe eines der beiden Felder mehr als 100 Elemente beträgt. Verwenden Sie das next_page_token Feld im Objektstamm, um zu ermitteln, ob weitere Ergebnisse verfügbar sind. Der Wert dieses Felds wird dann als Wert für den page_token Abfrageparameter in nachfolgenden Anforderungen verwendet. Arrayfelder mit weniger als 100 Elementen auf einer Seite sind auf nachfolgenden Seiten leer.

Die Auftrags-API 2.2 fügt auch den only_latest Abfrageparameter zu diesem Endpunkt hinzu, um nur die neuesten Ausführungsversuche im tasks Array anzuzeigen. Wenn der only_latest Parameter true ist, werden alle Ausführungen, die durch einen Wiederholungsversuch oder eine Reparatur ersetzt wurden, aus der Antwort weggelassen.

Wenn es sich bei dem run_id um einen ForEach-Tasklauf handelt, ist ein Feld namens iterations in der Antwort enthalten. Das iterations-Feld ist ein Array, das Details für alle Durchläufe der ForEach-verschachtelten Aufgaben des Hauptvorgangs enthält und die folgenden Eigenschaften aufweist.

  • Das Schema jedes Objekts im iterations Array ist identisch mit dem der Objekte im tasks Array.
  • Wenn der only_latest Abfrageparameter auf "true" festgelegt ist, sind nur die neuesten Ausführungsversuche im iterations Array enthalten.
  • Die Paginierung wird auf das iterations-Array anstelle des tasks-Arrays angewendet.
  • Das tasks Array ist weiterhin in der Antwort enthalten und enthält die Ausführung der ForEach Aufgabe.

Weitere Informationen zur Aufgabe finden Sie in der Dokumentation zur ForEachForEach-Aufgabe.

Sehen Sie sich z. B. die folgende Antwort für einen ForEach Vorgang an, bei dem einige Felder weggelassen werden:

{
  "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"
}
  • Last updated on