Condividi tramite

Aggiornamento da Jobs API 2.1 a 2.2

  • Articolo

Questo articolo illustra dettagliatamente gli aggiornamenti e i miglioramenti della funzionalità nella versione 2.2 dell'API Lavori. Include informazioni che consentono di aggiornare i client API esistenti in modo che funzionino con questa nuova versione. Questi aggiornamenti includono la coda predefinita dei processi e un supporto migliore per paginazione quando le risposte includono campi con più di 100 elementi. Poiché la versione 2.2 migliora il supporto esistente per impaginare set di risultati di grandi dimensioni, Databricks consiglia di usarlo per gli script e i client API, in particolare quando le risposte potrebbero includere molte attività.

Per informazioni sulle modifiche tra le versioni 2.0 e 2.1 dell'API, vedere Aggiornamento dall'API lavori da 2.0 a 2.1.

Oltre alle modifiche incluse nella versione 2.1 dell'API Processi di Databricks, la versione 2.2 include i miglioramenti seguenti:

I lavori vengono accodati per impostazione predefinita

La coda di processi è una funzionalità facoltativa che impedisce che le esecuzioni del processo vengano ignorate quando le risorse non sono disponibili per l'esecuzione. L'inserimento in coda dei lavori è supportato nelle versioni 2.0, 2.1 e 2.2 della Jobs API, con le differenze seguenti nella gestione predefinita dell'inserimento in coda:

  • Per i lavori creati con l'API Jobs 2.2, la funzione di coda è abilitata per impostazione predefinita. È possibile disattivare la coda impostando il campo queue su false nelle richieste quando si crea o si aggiorna un'attività.
  • Per i processi creati con le versioni 2.0 e 2.1 dell'API Processi, l'accodamento è non abilitato per impostazione predefinita. Con queste versioni, è necessario abilitare l'accodamento impostando il campo queue su true nel corpo della richiesta quando si crea o si aggiorna un processo.

È possibile abilitare o disabilitare la coda quando si creare un processo, aggiornare parzialmente un processoo aggiornare tutte le impostazioni del processo.

Vedere coda dei lavori.

Supporto per il paging degli elenchi di attività lunghe e di esecuzioni di attività.

Per supportare i processi con un numero elevato di attività o esecuzioni di attività, l'API Processi 2.2 modifica la modalità di restituzione dei set di risultati di grandi dimensioni per le richieste seguenti:

L'API Lavori 2.2 modifica la paginazione per queste richieste come segue:

  • I campi che rappresentano elenchi di elementi, ad esempio attività, parametri, job_clusters o ambienti, sono limitati a 100 elementi per risposta. Se sono disponibili più di 100 valori, il corpo della risposta include un campo next_page_token contenente un token per recuperare la pagina successiva dei risultati.
  • L'impaginazione è stata aggiunta per le risposte alle richieste Get a single job e Get a single job run. La paginazione per le risposte alle richieste List job e List job runs è stata aggiunta con l'API Lavori 2.1.

Di seguito è riportato un esempio del corpo del contenuto della risposta da una richiesta di Get a single job per un processo con più di 100 attività. Per illustrare la funzionalità di paging basata su token, questo esempio omette la maggior parte dei campi inclusi nel corpo della risposta:

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

Per recuperare l'insieme di risultati successivo, impostare il parametro di query page_token nella richiesta successiva sul valore restituito nel campo next_page_token. Ad esempio, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Se non sono disponibili altri risultati, il campo next_page_token non viene incluso nella risposta.

Nelle sezioni seguenti vengono forniti maggiori dettagli sugli aggiornamenti di ciascuna delle richieste list e get.

Modifiche alle richieste di List jobs e List job runs

Nelle richieste per List jobs e List job runs, il parametro has_more al livello radice dell'oggetto risposta viene rimosso. Usare invece l'esistenza del next_page_token per determinare se sono disponibili più risultati. In caso contrario, la funzionalità per impaginare i risultati rimane invariata.

Per evitare corpi di risposta di grandi dimensioni, le matrici tasks e job_clusters di primo livello per ogni processo vengono omesse dalle risposte per impostazione standard. Per includere queste matrici per ogni processo incluso nel corpo della risposta per queste richieste, aggiungere il parametro expand_tasks=true alla richiesta. Quando expand_tasks è abilitato, vengono restituiti un massimo di 100 elementi nelle matrici tasks e job_clusters. Se una di queste matrici ha più di 100 elementi, un campo has_more (da non confondere con il campo has_more di livello radice rimosso) all'interno dell'oggetto job è impostato su true., tuttavia, sono accessibili solo i primi 100 elementi. Non è possibile recuperare attività o cluster aggiuntivi dopo i primi 100 con la richiesta List jobs. Per recuperare più elementi, utilizzare le richieste che restituiscono una singola attività o un'esecuzione di una singola attività. Gli aggiornamenti che supportano l'impaginazione di campi di risposta di grandi dimensioni sono descritti nelle sezioni seguenti.

Ottenere un singolo lavoro

Nell'API Processi 2.2, la richiesta di ottenere un singolo lavoro per recuperare i dettagli su un singolo lavoro ora supporta l'impaginazione per i campi tasks e job_clusters quando la dimensione di uno dei due campi supera i 100 elementi. Utilizzare il campo next_page_token nella radice dell'oggetto per determinare se sono disponibili altri risultati. Il valore di questo campo viene quindi usato come valore per il parametro di query page_token nelle richieste successive. I campi della matrice con meno di 100 elementi in una pagina saranno vuoti nelle pagine successive.

Ottenere una singola esecuzione

Nell'API Processi 2.2, la richiesta per ottenere i dettagli di una singola esecuzione supporta ora l'impaginazione dei campi tasks e job_clusters quando la dimensione di uno dei campi supera i 100 elementi. Utilizzare il campo next_page_token nella radice dell'oggetto per determinare se sono disponibili altri risultati. Il valore di questo campo viene quindi usato come valore per il parametro di query page_token nelle richieste successive. I campi della matrice con meno di 100 elementi in una pagina saranno vuoti nelle pagine successive.

L'API Jobs 2.2 aggiunge anche il parametro di query only_latest a questo endpoint per consentire la visualizzazione solo dei tentativi più recenti nell'array tasks. Quando il parametro only_latest è true, tutte le esecuzioni sostituite da un nuovo tentativo o un ripristino vengono omesse dalla risposta.

Quando il run_id si riferisce all'esecuzione di un'attività ForEach, nella risposta è presente un campo denominato iterations. Il campo iterations è un array che contiene i dettagli relativi a tutte le esecuzioni del sotto-task dell'attività ForEach e presenta le seguenti proprietà:

  • Lo schema di ogni oggetto nella matrice di iterations è uguale a quello degli oggetti nella matrice tasks.
  • Se il parametro di query only_latest è impostato su true, nella matrice di iterations vengono inclusi solo i tentativi di esecuzione più recenti.
  • L'impaginazione viene applicata alla matrice iterations anziché alla matrice tasks.
  • La matrice tasks è ancora inclusa nella risposta e contiene l'esecuzione dell'attività ForEach.

Per ulteriori informazioni sull'attività ForEach, consultare la documentazione relativa all'attività ForEach .

Ad esempio, vedere la risposta seguente per un'attività ForEach con alcuni campi omessi:

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