Dela via

Uppdaterar från Jobb-API 2.1 till 2.2

  • Artikel

Den här artikeln beskriver uppdateringar och förbättringar av funktionerna i version 2.2 av Jobb-API:et. Den innehåller information som hjälper dig att uppdatera dina befintliga API-klienter så att de fungerar med den här nya versionen. Dessa uppdateringar omfattar standardköning av jobb och bättre stöd för sidnumrering när svar inkluderar fält som innehåller fler än 100 element. Eftersom version 2.2 förbättrar det befintliga stödet för sidnumrering av stora resultatuppsättningar rekommenderar Databricks att du använder det för dina API-skript och -klienter, särskilt när svar kan innehålla många uppgifter.

Mer information om ändringarna mellan versionerna 2.0 och 2.1 av API:et finns i Uppdatera från Jobb-API 2.0 till 2.1.

Förutom de ändringar som ingår i version 2.1 av Databricks-jobb-API:et har version 2.2 följande förbättringar:

Jobb placeras i kö som standard

Jobbköer är en valfri funktion som förhindrar att körningar av jobb missas när resurser inte är tillgängliga för körningen. Jobbköer stöds i versionerna 2.0, 2.1 och 2.2 av Jobb-API:et, med följande skillnader i standardhanteringen av köer:

  • För jobb som skapats med Jobb-API 2.2 är köning aktiverat som standard. Du kan inaktivera köning genom att ställa in fältet queue till false i begärandetexten när du skapar eller uppdaterar ett jobb.
  • För jobb som skapats med versionerna 2.0 och 2.1 av Jobb-API:et är köhantering inte aktiverat som standard. Med dessa versioner måste du aktivera köning genom att ange fältet queue till true i begärandeorgan när du skapar eller uppdaterar ett jobb.

Du kan aktivera eller inaktivera kön när du skapar ett jobb, delvis uppdaterar ett jobbeller uppdaterar alla jobbinställningar.

Se Jobbkö.

Stöd för paginering av långa listor över uppgifter och uppgiftskörningar

För att stödja jobb med ett stort antal aktiviteter eller aktivitetskörningar ändrar Jobs API 2.2 hur stora resultatuppsättningar returneras för följande begäranden:

Jobb-API 2.2 ändrar sidnumrering för dessa begäranden enligt följande:

  • Fält som representerar listor över element som uppgifter, parametrar, job_clusters eller miljöer är begränsade till 100 element per svar. Om fler än 100 värden är tillgängliga innehåller svarstexten ett next_page_token fält som innehåller en token för att hämta nästa sida med resultat.
  • Sidnumrering läggs till för svar på Get a single job- och Get a single job run-begäranden. Sidnumrering för svaren på List job och List job runs begäran lades till med Jobb-API 2.1.

Följande är ett exempel på svarstext från en Get a single job begäran om ett jobb med fler än 100 uppgifter. För att demonstrera den tokenbaserade pagineringsfunktionen, utelämnar det här exemplet de flesta av fälten som ingår i svarstexten.

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

Om du vill hämta nästa uppsättning resultat anger du frågeparametern page_token i nästa begäran till värdet som returneras i fältet next_page_token. Till exempel /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Om inga fler resultat är tillgängliga inkluderas inte fältet next_page_token i svaret.

Följande avsnitt innehåller mer information om uppdateringar av var och en av list och get begäranden.

Ändringar i List jobs- och List job runs-begäranden

För begärandena Lista jobb och Lista jobb körningar tas parametern has_more på rotnivån för svarsobjektet bort. Använd i stället förekomsten av next_page_token för att avgöra om fler resultat är tillgängliga. Annars förblir funktionerna för att sidnumrera resultat oförändrade.

För att förhindra stora svarsinnehåll utelämnas de översta tasks- och job_clusters-matriserna för varje jobb standardmässigt från svaren. Om du vill inkludera dessa matriser för varje jobb som ingår i svarstexten för dessa begäranden lägger du till parametern expand_tasks=true i begäran. När expand_tasks är aktiverat returneras högst 100 element i matriserna tasks och job_clusters. Om någon av dessa matriser har fler än 100 element är ett has_more fält (inte att förväxla med det has_more fält på rotnivå som tas bort) i job-objektet inställt på true. Dock är endast de första 100 elementen tillgängliga. Du kan inte hämta ytterligare uppgifter eller kluster efter de första 100 med listjobb begäran. Om du vill hämta fler element använder du förfrågningar som returnerar ett enda jobb eller en enda jobbexekvering. De uppdateringar som stöder sidnumrering av stora svarsfält beskrivs i följande avsnitt.

Hämta ett enda jobb

I Jobb-API 2.2 stöds nu paginering av fälten tasks och job_clusters i förfrågan Get a single job för att hämta detaljer om ett enskilt jobb, när storleken på något av fälten överstiger 100 element. Använd fältet next_page_token i objektroten för att avgöra om fler resultat är tillgängliga. Värdet för det här fältet används sedan som värde för page_token frågeparameter i efterföljande begäranden. Matrisfält med färre än 100 element på en sida kommer att vara tomma på efterföljande sidor.

Hämta en enda körning

I Jobs-API 2.2 stöder förfrågan Get a single run för att hämta detaljer om en enda körning nu paginering av fälten tasks och job_clusters när storleken på något av fälten överstiger 100 element. Använd fältet next_page_token i objektroten för att avgöra om fler resultat är tillgängliga. Värdet för det här fältet används sedan som värde för page_token frågeparametern i efterföljande begäranden. Matrisfält med färre än 100 element på en sida kommer att vara tomma på efterföljande sidor.

Jobb-API 2.2 lägger också till frågeparametern only_latest till den här slutpunkten för att endast visa de senaste körningsförsöken i arrayen tasks. När parametern only_latest är trueutelämnas alla körningar som ersätts av ett nytt försök eller en reparation från svaret.

När run_id refererar till en ForEach uppgiftsutförande finns ett fält med namnet iterations i svaret. Fältet iterations är en matris som innehåller information om alla körningar av den ForEach aktivitetens kapslade uppgift och har följande egenskaper:

  • Schemat för varje objekt i matrisen iterations är detsamma som för objekten i tasks matrisen.
  • Om frågeparametern only_latest är inställd på trueinkluderas endast de senaste körningsförsöken i matrisen iterations.
  • Sidnumrering tillämpas på matrisen iterations i stället för den tasks matrisen.
  • Matrisen tasks är fortfarande en del av svaret och innehåller körning av uppgiften ForEach.

För att lära dig mer om ForEach-aktiviteten, se ForEach-aktivitetens dokumentation.

Se till exempel följande svar för en ForEach uppgift med vissa fält utelämnade:

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