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 update 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 ange fältet queue till false i begärandeorgan när du skapar eller update 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ö genom att ställa in fältet queue till true i begärandetext när du skapar eller update ett jobb.

Du kan aktivera eller inaktivera köning när du skapa ett jobb, delvis update ett jobbeller update 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 aktiviteter, parameters, job_clusters eller miljöer är begränsade till 100 element per svar. Om fler än 100 values är tillgängliga innehåller svarstexten ett next_page_token fält som innehåller en token för att hämta nästa resultatsida.
  • 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 set resultat setpage_token frågeparametern 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 List jobb och List jobb körs begäranden tas has_more parametern 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, tilldelas ett has_more-fält (som inte ska förväxlas med has_more-fältet på rotnivå som tas bort) i job-objektet värdet set till 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 List jobb 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.

Get ett enda jobb

I Jobb-API 2.2 stöder Get ett enda jobb begäran om att hämta information om ett enda jobb nu sidnumrering av fälten tasks och job_clusters när storleken på något av fälten överskrider 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.

Get en enda körning

I Jobb-API 2.2 stöder Get en enskild körning begäran om att hämta information om en enskild körning nu sidnumrering av fälten tasks och job_clusters när storleken på något av fälten överskrider 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:

  • schema för varje objekt i matrisen iterations är samma som objekten i tasks matrisen.
  • Om frågeparametern only_latest är set till 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"
}