Aggiornamento da Jobs API 2.0 a 2.1

È ora possibile orchestrare più compiti con Azure Databricks attività. Questo articolo illustra in dettaglio le modifiche apportate all'API processi che supportano i processi con più attività e offre indicazioni utili per aggiornare i client API esistenti per lavorare con questa nuova funzionalità.

Databricks consiglia l'API Jobs 2.1 per i vostri script e client API, in particolare quando si usano job con più attività.

Questo articolo si riferisce ai lavori definiti con una singola attività come formato a singola attività e ai lavori definiti con più attività come formato multi-attività.

Jobs API 2.0 e 2.1 ora supportano la richiesta di aggiornamento . Usare la richiesta update per modificare un processo esistente anziché la richiesta di reimpostazione per ridurre al minimo le modifiche tra processi in formato attività singola e processi in formato multi-attività.

Modifiche api

L'API Lavori definisce ora un oggetto TaskSettings per acquisire le impostazioni per ogni attività in un lavoro. Per i processi in formato multi-attività, il campo tasks, una matrice di strutture di dati TaskSettings, è incluso nell'oggetto JobSettings. Alcuni campi che prima facevano parte di JobSettings ora sono inclusi nelle impostazioni dei task per i lavori in formato multi-attività. JobSettings viene aggiornato anche per includere il campo format. Il campo format indica il formato del lavoro ed è un valore di STRING impostato a SINGLE_TASK o MULTI_TASK.

È necessario aggiornare i client API esistenti per queste modifiche a JobSettings per i processi in formato multi-attività. Per altre informazioni sulle modifiche necessarie, vedere la guida client dell'API .

L'API Jobs 2.1 supporta il formato multi-attività. Tutte le richieste API 2.1 devono essere conformi a questo formato e le risposte sono strutturate in questo formato.

Jobs API 2.0 viene aggiornata con un campo aggiuntivo per supportare processi in formato multi-attività. Tranne dove indicato, gli esempi in questo documento usano l'API 2.0. Databricks consiglia tuttavia l'API 2.1 per gli script e i client API nuovi ed esistenti.

Documento JSON di esempio che rappresenta un processo in formato multi-attività per l'API 2.0 e 2.1:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

L'API lavori 2.1 supporta la configurazione di cluster a livello di attività o di uno o più cluster lavoro condivisi:

• Un cluster a livello di attività viene creato e avviato all'avvio di un'attività e termina al termine dell'attività.
• Un cluster di processi condivisi consente a più attività nello stesso processo di usare il cluster. Il cluster viene creato e avviato all'avvio della prima attività che usa il cluster e termina dopo il completamento dell'ultima attività usando il cluster. Un cluster di job condiviso non viene terminato quando è inattivo, ma viene terminato solo dopo il completamento di tutte le attività che lo usano. Più attività non dipendenti che condividono un cluster possono essere avviate contemporaneamente. Se un cluster di processi condivisi ha esito negativo o viene terminato prima del completamento di tutte le attività, viene creato un nuovo cluster.

Per configurare i cluster di processi condivisi, includere una matrice di JobCluster nell'oggetto JobSettings. È possibile specificare fino a un massimo di 100 cluster per processo. Di seguito è riportato un esempio di risposta API 2.1 per un processo configurato con due cluster condivisi:

Nota

Se un'attività presenta dipendenze di libreria, è necessario configurare le librerie nelle impostazioni del campo task; Le librerie non possono essere configurate in una configurazione del cluster di processi condivisi. Nell'esempio seguente, il campo libraries nella configurazione dell'attività ingest_orders dimostra la specificazione di una dipendenza di libreria.

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "job_clusters": [
      {
        "job_cluster_key": "default_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "i3.xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 2,
            "max_workers": 8
          }
        }
      },
      {
        "job_cluster_key": "data_processing_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "r4.2xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 8,
            "max_workers": 16
          }
        }
      }
    ],
    "tasks": [
      {
        "task_key": "ingest_orders",
        "description": "Ingest order data",
        "depends_on": [ ],
        "job_cluster_key": "auto_scaling_cluster",
        "spark_jar_task": {
          "main_class_name": "com.databricks.OrdersIngest",
          "parameters": [
            "--data",
            "dbfs:/path/to/order-data.json"
          ]
        },
        "libraries": [
          {
            "jar": "dbfs:/mnt/databricks/OrderIngest.jar"
          }
        ],
        "timeout_seconds": 86400,
        "max_retries": 3,
        "min_retry_interval_millis": 2000,
        "retry_on_timeout": false
      },
      {
        "task_key": "clean_orders",
        "description": "Clean and prepare the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "job_cluster_key": "default_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_orders",
        "description": "Perform an analysis of the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "job_cluster_key": "data_processing_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

Per i processi con formato a singola attività, la struttura dei dati JobSettings rimane invariata, ad eccezione dell'aggiunta del campo format. Non è inclusa alcuna matrice TaskSettings e le impostazioni dell'attività rimangono definite al livello superiore della struttura dei dati JobSettings. Non sarà necessario apportare modifiche ai client API esistenti per elaborare processi in formato singola attività.

Documento JSON di esempio che rappresenta un'attività a compito singolo per l'API 2.0:

{
  "job_id": 27,
  "settings": {
    "name": "Example notebook",
    "existing_cluster_id": "1201-my-cluster",
    "libraries": [
      {
        "jar": "dbfs:/FileStore/jars/spark_examples.jar"
      }
    ],
    "email_notifications": {},
    "timeout_seconds": 0,
    "schedule": {
      "quartz_cron_expression": "0 0 0 * * ?",
      "timezone_id": "US/Pacific",
      "pause_status": "UNPAUSED"
    },
    "notebook_task": {
      "notebook_path": "/notebooks/example-notebook",
      "revision_timestamp": 0
    },
    "max_concurrent_runs": 1,
    "format": "SINGLE_TASK"
  },
  "created_time": 1504128821443,
  "creator_user_name": "user@databricks.com"
}

Guida client dell'API

Questa sezione fornisce linee guida, esempi e modifiche necessarie per le chiamate API interessate dalla nuova funzionalità di formato multi-attività.

In questa sezione:

• Creare
• Le esecuzioni sono inviate
• aggiornamento
• Reimposta
• Elenco
• Ottieni
• Lanci di dati
• Le esecuzioni producono un output
• Elenco esecuzioni

Creare

Per creare un processo in formato singola attività tramite l'Creare un nuovo processo operazione (POST /jobs/create) nell'API Processi, non è necessario modificare i client esistenti.

Per creare un compito in formato multi-attività, usare il campo tasks in JobSettings per specificare le impostazioni per ogni attività. Nell'esempio seguente viene creato un processo con due attività del notebook. Questo esempio è relativo all'API 2.0 e alla versione 2.1:

Nota

È possibile specificare un massimo di 100 attività per ogni processo.

{
  "name": "Multi-task-job",
  "max_concurrent_runs": 1,
  "tasks": [
    {
      "task_key": "clean_data",
      "description": "Clean and prepare the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/clean-data"
      },
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    },
    {
      "task_key": "analyze_data",
      "description": "Perform an analysis of the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/analyze-data"
      },
      "depends_on": [
        {
          "task_key": "clean_data"
        }
      ],
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    }
  ]
}

esecuzioni inviate

Per inviare un'esecuzione unica di un processo a singola attività con l'operazione Creare e attivare un'esecuzione unica (POST /runs/submit) nell'API dei Processi, non è necessario modificare i client esistenti.

Per inviare una sola esecuzione di un processo in formato multiattività, usare il campo tasks in JobSettings per specificare le impostazioni per ogni attività, inclusi i cluster. I cluster devono essere configurati a livello di singola attività quando si invia un processo in formato multi-attività perché la richiesta di runs submit non supporta i cluster di processi condivisi. Vedi Creare per un esempio JobSettings che specifica più attività.

aggiornamento

Per aggiornare un processo in formato a singola attività con l'Aggiornare parzialmente un'operazione processo (POST /jobs/update) nell'API Processi, non è necessario cambiare i client esistenti.

Per aggiornare le impostazioni di un lavoro in formato multi-attività, è necessario utilizzare il campo univoco task_key per identificare le nuove impostazioni task. Vedi Creare per un esempio JobSettings che specifica più attività.

reimpostazione

Per sovrascrivere le impostazioni di un lavoro di formato a singolo compito con l'operazione Sovrascrivere tutte le impostazioni per un lavoro (POST /jobs/reset) nell'API Processi, non è necessario modificare i clienti esistenti.

Per sovrascrivere le impostazioni di un processo in formato multi-attività, specificare una struttura di dati JobSettings con una matrice di strutture di dati TaskSettings. Vedi Creare per un esempio JobSettings che specifica più attività.

Usare Aggiornare per modificare i singoli campi senza passare dal formato a attività singola a quello multi-attività.

elenco

Per le attività nel formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione Elenca tutte le attività (GET /jobs/list) nell'API Attività.

Per i processi in formato multi-attività, la maggior parte delle impostazioni è definita a livello di attività e non a livello di processo. La configurazione del cluster può essere impostata a livello di attività o processo. Per consentire ai client di accedere alle impostazioni del cluster o delle attività per un'attività in formato multi-task restituita nella struttura Job:

• Analizzare il campo job_id per il lavoro di formato multiarea.
• Passare il job_id all'operazione Ottieni un lavoro (GET /jobs/get) nell'API Lavori per recuperare i dettagli del lavoro. Consulta e ottieni per una risposta di esempio dalla chiamata API Get per un lavoro in formato multitasking.

L'esempio seguente mostra una risposta contenente processi in formato attività singola e multi-attività. Questo esempio è per l'API 2.0:

{
  "jobs": [
    {
      "job_id": 36,
      "settings": {
        "name": "A job with a single task",
        "existing_cluster_id": "1201-my-cluster",
        "email_notifications": {},
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/example-notebook",
          "revision_timestamp": 0
        },
        "max_concurrent_runs": 1,
        "format": "SINGLE_TASK"
      },
      "created_time": 1505427148390,
      "creator_user_name": "user@databricks.com"
    },
    {
      "job_id": 53,
      "settings": {
        "name": "A job with multiple tasks",
        "email_notifications": {},
        "timeout_seconds": 0,
        "max_concurrent_runs": 1,
        "format": "MULTI_TASK"
      },
      "created_time": 1625841911296,
      "creator_user_name": "user@databricks.com"
    }
  ]
}

Ottieni

Per le attività in formato singola, non sono necessarie modifiche del client per elaborare la risposta dall'operazione di Ottenere un'attività (GET /jobs/get) nell'API delle Attività.

I processi in formato multi-attività restituiscono una matrice di strutture di dati task contenenti le impostazioni delle attività. Se è necessario accedere ai dettagli a livello di attività, è necessario modificare i tuoi client per scorrere la matrice di tasks ed estrarre i campi richiesti.

Di seguito viene illustrata una risposta di esempio dalla chiamata API Get per un processo in formato multi-attività. Questo esempio è relativo all'API 2.0 e alla versione 2.1:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

Esecuzioni di processi

Per i processi in formato singola attività, non sono necessarie modifiche client per elaborare la risposta dalla Ottenere un'operazione di esecuzione di un processo (GET /jobs/runs/get) nell'API Processi.

La risposta per l'esecuzione di un lavoro in formato multi-task contiene un array di TaskSettings. Per ottenere i risultati delle esecuzioni per ogni attività:

• Iterare ciascuna delle attività.
• Analizzare il run_id per ogni attività.
• Chiamare il per ottenere l'output di un'operazione di esecuzione (GET /jobs/runs/get-output) usando il run_id per ottenere i dettagli sull'esecuzione di ciascuna attività. Di seguito è riportata una risposta di esempio da questa richiesta:

{
  "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": "Query logs",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759601,
      "task_key": "query-logs",
      "description": "Query session logs",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/log-query"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "validate_output",
      "description": "Validate query output",
      "depends_on": [
        {
          "task_key": "query-logs"
        }
      ],
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/validate-query-results"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK"
}

Le esecuzioni ottengono l'output

Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dalla Ottenere l'output per un'operazione di esecuzione (GET /jobs/runs/get-output) nell'API Processi.

Per lavori nel formato multi-task, la chiamata di Runs get output su un'esecuzione principale genera un errore poiché l'output dell'esecuzione è disponibile solo per le singole attività. Per ottenere l'output e i metadati per un lavoro in formato multi-task:

• Chiamare il Ottenere l'output per una richiesta di esecuzione.
• Scorri i campi figlio run_id nella risposta.
• Usare i valori del figlio run_id per chiamare Runs get output.

elenco esecuzioni di

Per i processi in formato singola attività, non sono necessarie modifiche client per elaborare la risposta dall'elenco di esecuzioni per un'operazione di processo (GET /jobs/runs/list).

Per i processi in formato multi-attività, viene restituita una matrice di tasks vuota. Passare il run_id all'Ottenere un'operazione di esecuzione del processo (GET /jobs/runs/get) per recuperare le attività. Di seguito viene illustrata una risposta di esempio della chiamata API Runs list per un processo in formato multi-attività:

{
  "runs": [
    {
      "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": "Query logs",
      "run_type": "JOB_RUN",
      "tasks": [],
      "format": "MULTI_TASK"
    }
  ],
  "has_more": false
}