Udostępnij za pośrednictwem

Aktualizowanie interfejsu API Jobs z wersji 2.1 do 2.2

  • Artykuł

Ten artykuł zawiera szczegółowe informacje o aktualizacjach i ulepszeniach funkcji w wersji 2.2 interfejsu API zadań. Zawiera ona informacje ułatwiające aktualizowanie istniejących klientów interfejsu API w celu pracy z tą nową wersją. Te aktualizacje obejmują domyślne kolejkowanie zadań oraz lepszą obsługę stronicowania, gdy odpowiedzi zawierają pola z więcej niż 100 elementami. Ponieważ wersja 2.2 zwiększa istniejącą obsługę stronicowania dużych zestawów wyników, usługa Databricks zaleca używanie go dla skryptów interfejsu API i klientów, szczególnie wtedy, gdy odpowiedzi mogą obejmować wiele zadań.

Aby dowiedzieć się więcej o zmianach między wersjami 2.0 a 2.1 API zadań, zobacz Aktualizowanie z wersji 2.0 do 2.1 API zadań.

Oprócz zmian w wersji 2.1 interfejsu API zadań usługi Databricks w wersji 2.2 wprowadzono następujące ulepszenia:

Zadania są domyślnie kolejkowane

Kolejkowanie zadań to opcjonalna funkcja, która uniemożliwia pomijanie uruchomienia zadań, gdy zasoby są niedostępne do uruchomienia. Kolejkowanie zadań jest obsługiwane w wersjach 2.0, 2.1 i 2.2 interfejsu API zadań z następującymi różnicami w domyślnej obsłudze kolejkowania:

  • W przypadku zadań utworzonych za pomocą interfejsu API zadań 2.2 kolejkowanie jest domyślnie włączone. Kolejkowanie można wyłączyć, ustawiając pole queue na false w treści żądania podczas tworzenia lub aktualizowania zadania.
  • W przypadku zadań utworzonych w wersjach 2.0 i 2.1 interfejsu API zadań kolejkowanie nie jest domyślnie nie włączone. W przypadku tych wersji należy włączyć kolejkowanie, ustawiając pole queue na true w treści żądania podczas tworzenia lub aktualizowania zadania.

Kolejkowanie można włączyć lub wyłączyć podczas tworzenia zadania, częściowej aktualizacji zadanialub aktualizacji wszystkich ustawień zadania.

Zobacz Kolejkowanie zadań.

Obsługa stronicowania długich list zadań i list wykonania zadań

Aby obsługiwać zadania z dużą liczbą zadań lub przebiegów zadań, interfejs API zadań 2.2 zmienia sposób zwracania dużych zestawów wyników dla następujących żądań:

API Zadań 2.2 zmienia sposób stronicowania dla tych żądań w następujący sposób:

  • Pola reprezentujące listy elementów, takich jak zadania, parametry, job_clusters lub środowiska, są ograniczone do 100 elementów na odpowiedź. Jeśli dostępnych jest więcej niż 100 wartości, treść odpowiedzi zawiera pole next_page_token zawierające token umożliwiający pobranie następnej strony wyników.
  • Dodano stronicowanie do odpowiedzi na żądania Get a single job i Get a single job run. Stronicowanie odpowiedzi na żądania List job i List job runs zostało dodane w Jobs API 2.1.

Poniżej przedstawiono przykładową treść odpowiedzi z żądania Get a single job dla pracy zawierającej ponad 100 zadań. Aby zademonstrować funkcję stronicowania opartą na tokenach, w tym przykładzie pominięto większość pól zawartych w treści odpowiedzi:

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

Aby pobrać następny zestaw wyników, ustaw parametr zapytania page_token w następnym żądaniu na wartość zwróconą w polu next_page_token. Na przykład /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Jeśli więcej wyników nie jest dostępnych, pole next_page_token nie zostanie uwzględnione w odpowiedzi.

W poniższych sekcjach opisano bardziej szczegółowe informacje na temat aktualizacji poszczególnych żądań list i get.

zmiany w żądaniach List jobs i List job runs

Dla żądań List jobs oraz List job runs, parametr has_more na poziomie głównym obiektu odpowiedzi zostanie usunięty. Zamiast tego należy użyć istnienia next_page_token, aby określić, czy są dostępne więcej wyników. W przeciwnym razie funkcjonalność stronicowania wyników pozostaje niezmieniona.

Aby zapobiec dużym objętościom odpowiedzi, najwyższego poziomu tablice tasks i job_clusters dla każdego zadania są domyślnie pomijane w odpowiedziach. Aby uwzględnić te tablice dla każdego zadania uwzględnionego w treści odpowiedzi dla tych żądań, dodaj parametr expand_tasks=true do żądania. Po włączeniu expand_tasks w tablicach tasks i job_clusters zwracanych jest maksymalnie 100 elementów. Jeśli którakolwiek z tych tablic ma więcej niż 100 elementów, pole has_more (nie należy mylić z polem has_more na poziomie głównym, które zostało usunięte) wewnątrz obiektu job jest ustawione na true. Jednak tylko pierwsze 100 elementów jest dostępnych. Nie można pobrać dodatkowych zadań lub klastrów po pobraniu pierwszych 100 za pomocą żądania Listy zadań . Aby pobrać więcej elementów, użyj żądań, które zwracają pojedyncze zadanie lub pojedyncze wykonanie zadania. Aktualizacje obsługujące stronicowanie dużych pól odpowiedzi zostały omówione w poniższych sekcjach.

Zdobądź pojedyncze zadanie

W interfejsie Jobs API 2.2 metoda Pobierz pojedyncze zadanie, służąca do uzyskiwania szczegółowych informacji o pojedynczym zadaniu, teraz obsługuje stronicowanie dla pól tasks i job_clusters, gdy którykolwiek z tych pól przekracza 100 elementów. Użyj pola next_page_token w głównej części obiektu, aby określić, czy dostępne są więcej wyników. Wartość tego pola jest następnie używana jako wartość parametru zapytania page_token w kolejnych żądaniach. Pola tablicy z mniej niż 100 elementami na jednej stronie będą puste na kolejnych stronach.

Uzyskaj pojedynczy przebieg

W interfejsie API zadań 2.2 Żądanie uzyskania pojedynczego uruchomienia w celu pobrania szczegółów dotyczących pojedynczego uruchomienia obsługuje teraz stronicowanie pól tasks i job_clusters, gdy rozmiar każdego pola przekracza 100 elementów. Użyj pola next_page_token w głównej części obiektu, aby określić, czy dostępne są więcej wyników. Wartość tego pola jest następnie używana jako wartość parametru zapytania page_token w kolejnych żądaniach. Pola tablicy z mniej niż 100 elementami na jednej stronie będą puste na kolejnych stronach.

Interfejs Jobs API 2.2 dodaje również parametr zapytania only_latest do tego punktu końcowego, aby umożliwić wyświetlanie tylko najnowszych prób uruchomienia w tablicy tasks. Gdy parametr only_latest jest true, wszystkie uruchomienia zastąpione przez ponowną próbę lub naprawę zostaną pominięte z odpowiedzi.

Gdy run_id odwołuje się do uruchomienia zadania ForEach, w odpowiedzi znajduje się pole o nazwie iterations. Pole iterations to tablica zawierająca szczegóły wszystkich wykonań zagnieżdżonego zadania ForEach i posiada następujące właściwości:

  • Schemat każdego obiektu w tablicy iterations jest taki sam jak schemat obiektów w tablicy tasks.
  • Jeśli parametr zapytania only_latest jest ustawiony na true, w tablicy iterations zostaną uwzględnione tylko najnowsze próby uruchomienia.
  • Stronicowanie jest stosowane do tablicy iterations zamiast tablicy tasks.
  • Tablica tasks jest nadal zawarta w odpowiedzi i zawiera wykonanie zadania ForEach.

Aby dowiedzieć się więcej o zadaniu ForEach, zapoznaj się z dokumentacją zadania ForEach .

Zobacz na przykład następującą odpowiedź dla zadania ForEach z pominiętymi polami:

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