Sdílet prostřednictvím

Aktualizace z rozhraní API úloh 2.1 na verzi 2.2

  • Článek

Tento článek podrobně popisuje aktualizace a vylepšení funkcí ve verzi 2.2 rozhraní API úloh. Obsahuje informace, které vám pomůžou aktualizovat stávající klienty rozhraní API tak, aby fungovaly s touto novou verzí. Mezi tyto aktualizace patří výchozí zařadování úloh do fronty a lepší podpora stránkování , když odpovědi obsahují pole s více než 100 elementy. Vzhledem k tomu, že verze 2.2 vylepšuje stávající podporu stránkování velkých sad výsledků, doporučuje Databricks ho používat pro vaše skripty a klienty rozhraní API, zejména pokud odpovědi můžou zahrnovat mnoho úloh.

Informace o změnách mezi verzemi 2.0 a 2.1 rozhraní API najdete v tématu Aktualizace z rozhraní API úloh 2.0 na verzi 2.1.

Kromě změn obsažených ve verzi 2.1 rozhraní Databricks Jobs API má verze 2.2 následující vylepšení:

Úlohy se ve výchozím nastavení zařadí do fronty.

Fronta úloh je volitelná funkce, která brání vynechání úloh, pokud nejsou pro spuštění k dispozici prostředky. Podpora front úloh je zajištěna ve verzích 2.0, 2.1 a 2.2 Jobs API, přičemž se ve výchozím zpracování front vyskytují následující rozdíly:

  • Pro úlohy vytvořené pomocí rozhraní API úloh 2.2 je ve výchozím nastavení povoleno zařadování do fronty. Můžete vypnout řazení do fronty tím, že nastavíte pole queue na false v těle žádosti při vytváření nebo aktualizaci úlohy.
  • U úloh vytvořených s verzemi 2.0 a 2.1 rozhraní API pro úlohy není ve výchozím nastavení zařazení do fronty povoleno. není ve výchozím nastavení. V těchto verzích je nutné povolit zařadování do fronty nastavením pole queue na true v těle požadavku při vytváření nebo aktualizaci úlohy.

Můžete povolit nebo zakázat zařazení do fronty při vytvoření úlohy, částečně aktualizovat úlohunebo aktualizovat všechna nastavení úlohy.

Viz Úlohy zařazené do fronty.

Podpora stránkování dlouhých seznamů úloh a seznamů běhu úloh

Pokud chcete podporovat úlohy s velkým počtem úloh nebo spuštěním úloh, změní rozhraní API úloh 2.2 způsob vrácení velkých sad výsledků pro následující požadavky:

Jobs API verze 2.2 mění stránkování pro tyto požadavky následujícím způsobem:

  • Pole představující seznamy prvků, jako jsou úkoly, parametry, job_clusters nebo prostředí, jsou omezená na 100 prvků na odpověď. Pokud je k dispozici více než 100 hodnot, text odpovědi obsahuje pole next_page_token obsahující token pro načtení další stránky výsledků.
  • Stránkování se přidá pro odpovědi na požadavky Get a single job a Get a single job run. Stránkování odpovědí na požadavky List job a List job runs bylo přidáno pomocí rozhraní API Jobs 2.1.

Následuje příklad textu odpovědi z Get a single job požadavku na úlohu s více než 100 úkoly. Pro předvedení stránkovací funkce založené na tokenech tento příklad vynechá většinu polí zahrnutých v textu odpovědi:

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

Pokud chcete načíst další sadu výsledků, nastavte parametr dotazu page_token v dalším požadavku na hodnotu vrácenou v poli next_page_token. Například /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Pokud nejsou k dispozici žádné další výsledky, pole next_page_token se do odpovědi nezahrne.

V následujících částech najdete podrobnější informace o aktualizacích jednotlivých list a get požadavků.

změny v požadavcích pro List jobs a List job runs

Pro úlohy Seznam a List úloha spouští požadavky, odebere se parametr has_more na kořenové úrovni objektu odpovědi. Místo toho použijte existenci next_page_token k určení, zda jsou k dispozici více výsledků. V opačném případě zůstane funkce stránkování výsledků nezměněná.

Aby se zabránilo velkým objemům odpovědí, jsou pole tasks a job_clusters nejvyšší úrovně pro každou úlohu ve výchozím nastavení vynechána z odpovědí. Pokud chcete zahrnout tato pole pro každou úlohu obsaženou v textu odpovědi pro tyto požadavky, přidejte do požadavku parametr expand_tasks=true. Při povolení expand_tasks se v polích tasks a job_clusters vrátí maximálně 100 prvků. Pokud některé z těchto polí obsahuje více než 100 prvků, je pole has_more (nezaměňovat s kořenovým polem has_more, které je odebráno) uvnitř objektu job je nastaveno na true. Nicméně jsou přístupné pouze prvních 100 prvků. Nelze načíst další úlohy nebo clustery po prvních 100 s žádostí List jobs. Pokud chcete načíst více prvků, použijte požadavky, které vracejí jednu úlohu nebo jedno spuštění úlohy. Aktualizace, které podporují stránkování velkých polí odpovědí, jsou popsány v následujících částech.

Získejte jednu úlohu

V Jobs API 2.2 nyní požadavek Získat jednu úlohu pro načtení podrobností o jedné úloze podporuje stránkování pro pole tasks a job_clusters, pokud velikost kterékoli z těchto polí přesahuje 100 prvků. Pomocí pole next_page_token v kořenovém adresáři objektu určete, jestli jsou k dispozici více výsledků. Hodnota tohoto pole se pak použije jako hodnota parametru dotazu page_token v následných požadavcích. Pole s méně než 100 prvky na jedné stránce budou na dalších stránkách prázdná.

Získat jedno spuštění

V rozhraní Jobs API 2.2 nyní požadavek Získat jediný běh pro načtení podrobností o jednom běhu podporuje stránkování polí tasks a job_clusters, pokud velikost jednoho z těchto polí přesahuje 100 prvků. Pomocí pole next_page_token v kořenovém adresáři objektu určete, jestli jsou k dispozici více výsledků. Hodnota tohoto pole se pak použije jako hodnota parametru dotazu page_token v následných požadavcích. Pole s méně než 100 prvky na jedné stránce budou na dalších stránkách prázdná.

Rozhraní API úloh 2.2 také přidá do tohoto koncového bodu parametr dotazu only_latest, aby se v poli tasks zobrazovaly pouze nejnovější pokusy o spuštění. Pokud je parametr only_latesttrue, z odpovědi se vynechá všechna spuštění nahrazená opakováním nebo opravou.

Když run_id odkazuje na spuštění úlohy ForEach, v odpovědi se zobrazí pole s názvem iterations. Pole iterations je pole, které obsahuje podrobnosti o všech spuštěních vnořené úlohy úkolu ForEach a má následující vlastnosti:

  • Schéma každého objektu v poli iterations je stejné jako u objektů v tasks poli.
  • Pokud je parametr dotazu only_latest nastavený na true, jsou do pole iterations zahrnuty pouze nejnovější pokusy o spuštění.
  • Stránkování se použije na pole iterations místo pole tasks.
  • Pole tasks je stále zahrnuté v odpovědi a zahrnuje spuštění úlohy ForEach.

Další informace o úloze ForEach najdete v dokumentaci k úloze ForEach .

Podívejte se například na následující odpověď pro úkol ForEach, která má vynechaná některá pole:

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