Aggiornamento da API Processi 2.0 a 2.1
È ora possibile orchestrare più attività con i processi di Azure Databricks. Questo articolo illustra in dettaglio le modifiche apportate all'API Processi che supportano i processi con più attività e fornisce indicazioni utili per aggiornare i client API esistenti per usare questa nuova funzionalità.
Databricks consiglia l'API Processi 2.1 per gli script e i client API, in particolare quando si usano processi con più attività.
Questo articolo si riferisce ai processi con una singola attività definiti formato a singola attività e processi con più attività definiti formato multi-attività.
L'API Processi 2.0 e 2.1 supportano ora la richiesta di aggiornamento. Usare la richiesta update per modificare un processo esistente anziché la richiesta di ripristino per ridurre al minimo le modifiche tra processi in formato a singola attività e processi in formato multi-attività.
Modifiche API
L'API Processi definisce ora un oggetto TaskSettings per acquisire le impostazioni per ogni attività di un processo. Per i processi in formato multi-attività, il campo tasks, una matrice di strutture di dati TaskSettings, è incluso nell'oggetto JobSettings. Alcuni campi in precedenza appartenenti a JobSettings, fanno ora parte delle impostazioni delle attività per i processi in formato multi-attività. JobSettings viene inoltre aggiornato in modo da includere il campo format. Il campo format indica il formato del processo ed è un valore STRING impostato su 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 al client API.
L'API Processi 2.1 supporta il formato multi-attività. Tutte le richieste API 2.1 devono essere conformi al formato multi-attività e le risposte sono strutturate nel formato multi-attività. Le nuove funzionalità vengono rilasciate per l'API 2.1.
L'API Processi 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 Processi 2.1 supporta la configurazione di cluster a livello di attività o di uno o più cluster di processi 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 condiviso consente a più attività nello stesso processo di utilizzare 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à che usa il cluster. Un cluster di processi condiviso non viene terminato quando è inattivo, ma termina solo dopo il completamento di tutte le attività che lo usano. È possibile avviare contemporaneamente più attività non dipendenti che condividono un cluster. Se un cluster di processi condiviso 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 JobCluster nell'oggetto JobSettings. È possibile specificare 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 dei campi task. Le librerie non possono essere configurate in una configurazione con cluster di processi condiviso. Nell'esempio seguente il campo libraries nella configurazione dell'attività ingest_orders illustra la specifica 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 in 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à restano definite al livello superiore della struttura dei dati JobSettings. Non sarà necessario apportare modifiche ai client API esistenti per elaborare processi in formato a singola attività.
Documento JSON di esempio che rappresenta un processo di formato a singola attività 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 API
Questa sezione fornisce linee guida, esempi e modifiche necessarie per le chiamate API interessate dalla nuova funzionalità di formato multi-attività.
Contenuto della sezione:
- Create (Crea)
- Runs submit (Invio esecuzioni)
- Update (Aggiorna)
- Reset (Ripristina)
- List (Elenca)
- Get (Ottieni)
- Runs get (Ottieni esecuzioni)
- Runs get output (Ottieni output esecuzioni)
- Runs list (Elenco esecuzioni)
Create (Crea)
Per creare un processo in formato a singola attività tramite l'operazione Create a new job (Crea un nuovo processo) (POST /jobs/create) nell'API Processi, non è necessario modificare i client esistenti.
Per creare un processo 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à notebook. Questo esempio è relativo alle API 2.0 e 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
}
]
}
Runs submit (Invio esecuzioni)
Per inviare un'unica esecuzione di un processo in formato a singola attività con l'operazione Create and trigger a one-time run (Crea e attiva un'esecuzione una tantum) (POST /runs/submit) nell'API Processi, non è necessario modificare i client esistenti.
Per inviare un'esecuzione una tantum di un processo in formato multi-attività, usare il campo tasks in JobSettings per specificare le impostazioni per ogni attività, inclusi i cluster. Poiché la richiesta runs submit non supporta i cluster di processi condivisi, quando si invia un processo in formato multi-attività, i cluster devono essere impostati a livello di attività. Vedere Create (Crea) per un esempio JobSettings che specifica più attività.
Update (Aggiorna)
Per aggiornare un processo in formato a singola attività con l'operazione Partially update a job (Aggiorna parzialmente un processo) (POST /jobs/update) nell'API Processi, non è necessario modificare i client esistenti.
Per aggiornare le impostazioni di un processo in formato multi-attività, è necessario usare il campo univoco task_key per identificare le nuove impostazioni task. Vedere Create (Crea) per un esempio JobSettings che specifica più attività.
Reset (Ripristina)
Per sovrascrivere le impostazioni di un processo in formato a singola attività con l'operazione Overwrite all settings for a job (Sovrascrivi tutte le impostazioni di un processo) (POST /jobs/reset) nell'API Processi, non è necessario modificare i client 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. Vedere Create (Crea) per un esempio JobSettings che specifica più attività.
Usare Update (Aggiorna) per modificare i singoli campi senza passare dal formato a singola attività a quello multi-attività.
List (Elenca)
Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione List all jobs (Elenca tutti i processi) (GET /jobs/list) nell'API Processi.
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 modificare i client per accedere alle impostazioni del cluster o delle attività per un processo in formato multi-attività restituito nella struttura Job:
- Analizzare il campo
job_idper il processo in formato multi-attività. - Per recuperare i dettagli del processo, passare
job_idall'operazione Get a job (Ottieni processo) (GET /jobs/get) nell'API Processi. Per una risposta di esempio dalla chiamata APIGetper un processo in formato multi-attività, vedere Get (Ottieni).
L'esempio seguente mostra una risposta contenente processi in formato a singola attività 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"
}
]
}
Get (Ottieni)
Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione Get a job (Recupera un processo) (GET /jobs/get) nell'API Processi.
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 client per scorrere la matrice tasks ed estrarre i campi obbligatori.
Di seguito viene illustrata una risposta di esempio dalla chiamata API Get per un processo in formato multi-attività. Questo esempio è relativo alle 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"
}
Runs get (Ottieni esecuzioni)
Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione Get a job run (Recupera un'esecuzione di processo) (GET /jobs/runs/get) nell'API Processi.
La risposta per l'esecuzione di un processo in formato multi-attività contiene una matrice di TaskSettings. Per recuperare i risultati dell'esecuzione per ogni attività:
- Scorrere ognuna delle attività.
- Analizzare
run_idper ogni attività. - Chiamare l'operazione Get the output for a run (
GET /jobs/runs/get-output) conrun_idper ottenere i dettagli sull'esecuzione per ogni attività. Di seguito è riportato un esempio di risposta per 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"
}
Runs get output (Ottieni output esecuzioni)
Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione Get the output for a run (Recupera l'output per un'esecuzione) (GET /jobs/runs/get-output) nell'API Processi.
Per i processi in formato multi-attività, la chiamata Runs get output a un'esecuzione di livello superiore genera un errore perché l'output di esecuzione è disponibile solo per le singole attività. Per ottenere l'output e i metadati per un processo in formato multi-attività:
- Chiamare la richiesta Get the output for a run (Ottieni l'output di una esecuzione).
- Scorrere i campi di livello inferiore
run_idnella risposta. - Usare i valori di livello inferiore
run_idper chiamareRuns get output.
Runs list (Elenco esecuzioni)
Per i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione List runs for a job (Elenca esecuzioni per un processo) (GET /jobs/runs/list).
Per i processi in formato multi-attività, viene restituita una matrice vuota tasks. Passare run_id all'operazione Get a job run (Ottieni l'esecuzione di un processo) (GET /jobs/runs/get) per recuperare le attività. Di seguito viene illustrata una risposta di esempio dalla 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
}