Delen via

Bijwerken van Jobs API 2.1 naar 2.2

  • Artikel

In dit artikel vindt u informatie over updates en verbeteringen van de functionaliteit in versie 2.2 van de Taken-API. Het bevat informatie waarmee u uw bestaande API-clients kunt bijwerken om met deze nieuwe versie te werken. Deze updates omvatten standaardwachtrijen van taken en betere ondersteuning voor paginering wanneer antwoorden velden met meer dan 100 elementen bevatten. Omdat versie 2.2 de bestaande ondersteuning voor het pagineren van grote resultatensets verbetert, raadt Databricks aan deze te gebruiken voor uw API-scripts en -clients, met name wanneer antwoorden veel taken kunnen bevatten.

Zie Bijwerken van Jobs-API 2.0 naar 2.1voor meer informatie over de wijzigingen tussen versie 2.0 en 2.1 van de API.

Naast de wijzigingen die zijn opgenomen in versie 2.1 van de Databricks Jobs-API, heeft versie 2.2 de volgende verbeteringen:

Taken worden standaard in de wachtrij geplaatst

Taakwachtrij is een optionele functie die voorkomt dat taakuitvoeringen worden overgeslagen wanneer resources niet beschikbaar zijn voor de uitvoering. Taakwachtrijen worden ondersteund in de versies 2.0, 2.1 en 2.2 van de Taken-API, met de volgende verschillen in de standaardafhandeling van wachtrijen:

  • Voor jobs die zijn gecreëerd met de Jobs-API 2.2, staat de wachtrijfunctionaliteit standaard ingeschakeld. U kunt wachtrijen uitschakelen door het veld queue in te stellen op false in aanvraagteksten wanneer u een taak maakt of bijwerkt.
  • Voor taken die zijn gemaakt met de 2.0- en 2.1-versies van de Taken-API, is wachtrijvorming standaard niet ingeschakeld. Met deze versies moet u wachtrijen inschakelen door het veld queue in te stellen op true in aanvraaglichamen wanneer u een taak maakt of bijwerkt.

U kunt wachtrijen in- of uitschakelen wanneer u een taak maakt, een taak gedeeltelijk bijwerkenof alle taakinstellingen bijwerken.

Zie taakwachtrij.

Ondersteuning voor het pagiëren van lange taken- en taakuitvoeringslijsten

Ter ondersteuning van taken met een groot aantal taken of taakuitvoeringen wijzigt Jobs API 2.2 hoe grote resultatensets worden geretourneerd voor de volgende aanvragen:

De Jobs API 2.2 wijzigt de paginering van deze aanvragen als volgt:

  • Velden die lijsten met elementen vertegenwoordigen, zoals taken, parameters, job_clusters of omgevingen, zijn beperkt tot 100 elementen per antwoord. Als er meer dan 100 waarden beschikbaar zijn, bevat de hoofdtekst van het antwoord een next_page_token veld met een token om de volgende pagina met resultaten op te halen.
  • Paginering wordt toegevoegd voor de antwoorden op de Get a single job en Get a single job run verzoeken. Paginering voor de antwoorden op de List job en List job runs aanvraag is toegevoegd met jobs-API 2.1.

Hier volgt een voorbeeld van een antwoordtekst van een Get a single job aanvraag voor een taak met meer dan 100 taken. Om de token-gebaseerde pagineringsfunctionaliteit te demonstreren, worden in dit voorbeeld de meeste velden weggelaten die zijn opgenomen in het antwoordbody:

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

Als u de volgende set resultaten wilt ophalen, stelt u de page_token queryparameter in de volgende aanvraag in op de waarde die wordt geretourneerd in het next_page_token veld. Bijvoorbeeld /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Als er geen resultaten meer beschikbaar zijn, wordt het next_page_token veld niet opgenomen in het antwoord.

De volgende secties bevatten meer informatie over de updates voor elk van de list- en get-aanvragen.

Wijzigingen in de List jobs- en List job runs-aanvragen

Voor de aanvragen lijsttaken en lijsttaakuitvoeringen wordt de parameter has_more op het hoogste niveau van het antwoordobject verwijderd. Gebruik in plaats daarvan het bestaan van de next_page_token om te bepalen of er meer resultaten beschikbaar zijn. Anders blijft de functionaliteit voor het pagineren van resultaten ongewijzigd.

Om grote antwoordteksten te voorkomen, worden de tasks- en job_clusters-arrays op topniveau bij elke taak standaard weggelaten uit antwoorden. Als u deze matrices wilt opnemen voor elke taak die in de antwoordtekst voor deze aanvragen is opgenomen, voegt u de parameter expand_tasks=true toe aan de aanvraag. Wanneer expand_tasks is ingeschakeld, worden maximaal 100 elementen geretourneerd in de tasks en job_clusters matrices. Als een van deze matrices meer dan 100 elementen bevat, wordt een has_more veld (niet te verwarren met het has_more veld op hoofdniveau dat wordt verwijderd) in het job-object ingesteld op true. Alleen de eerste 100 elementen zijn toegankelijk. U kunt geen extra taken of clusters ophalen na de eerste 100 met de Lijst taken aanvraag. Als u meer elementen wilt ophalen, gebruikt u de aanvragen die één taak retourneren of één taakuitvoering. De updates die ondersteuning bieden voor het pagineren van grote antwoordvelden, worden in de volgende secties besproken.

Één taak ophalen

In Jobs API 2.2 ondersteunt de Eén taak ophalen aanvraag om details over één taak op te halen, nu paginering van de tasks- en job_clusters-velden wanneer de grootte van een van beide velden groter is dan 100 elementen. Gebruik het next_page_token veld in de hoofdmap van het object om te bepalen of er meer resultaten beschikbaar zijn. De waarde van dit veld wordt vervolgens gebruikt als de waarde voor de page_token queryparameter in volgende aanvragen. Matrixvelden met minder dan 100 elementen op één pagina zijn leeg in volgende pagina's.

Eén taak ophalen

In Jobs API 2.2 ondersteunt Een enkele uitvoering ophalen aanvraag nu het ophalen van details over één uitvoering, inclusief paginering van de velden tasks en job_clusters wanneer de grootte van een van deze velden groter is dan 100 elementen. Gebruik het next_page_token veld in de hoofdmap van het object om te bepalen of er meer resultaten beschikbaar zijn. De waarde van dit veld wordt vervolgens gebruikt als de waarde voor de page_token queryparameter in volgende aanvragen. Matrixvelden met minder dan 100 elementen op één pagina zijn leeg op volgende pagina's.

Taken-API 2.2 voegt ook de only_latest queryparameter toe aan dit eindpunt om alleen de meest recente uitvoeringspogingen in de tasks matrix weer te geven. Wanneer de parameter only_latesttrueis, worden alle runnen die zijn vervangen door een nieuwe poging of reparatie, weggelaten uit het antwoord.

Wanneer de run_id verwijst naar een ForEach taakuitvoering, is er een veld met de naam iterations aanwezig in het antwoord. Het iterations veld is een array die details bevat voor alle uitvoeringen van de geneste taak van de ForEach taak en heeft de volgende eigenschappen:

  • Het schema van elk object in de iterations matrix is hetzelfde als het schema van de objecten in de tasks matrix.
  • Als de only_latest queryparameter is ingesteld op true, worden alleen de meest recente uitvoeringspogingen opgenomen in de iterations matrix.
  • Paginering wordt toegepast op de iterations matrix in plaats van de tasks matrix.
  • De tasks matrix is nog steeds opgenomen in het antwoord en bevat de ForEach taakuitvoering.

Zie de ForEachvoor meer informatie over de taak.

Zie bijvoorbeeld het volgende antwoord voor een ForEach taak waarbij sommige velden zijn weggelaten:

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