Condividi tramite

Aggiornamento dall'API processi da 2.0 a 2.1

  • Articolo

È 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 definiti con una singola attività come formato a singola attività e processi definiti con più attività come formato multi-attività.

L'API dei processi 2.0 e 2.1 supporta ora la richiesta di aggiornamento . Usare la update richiesta 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 Processi definisce ora un TaskSettings oggetto per acquisire le impostazioni per ogni attività in un processo. Per i processi in formato multi-attività, il tasks campo , una matrice di strutture di TaskSettings dati, è incluso nell'oggetto JobSettings . Alcuni campi in precedenza fanno parte delle impostazioni delle JobSettings attività per i processi in formato multi-attività. JobSettings viene aggiornato anche per includere il format campo . Il format campo indica il formato del processo e è un STRING valore impostato su SINGLE_TASK o MULTI_TASK.

È necessario aggiornare i client API esistenti per queste modifiche a Job Impostazioni per i processi in formato multi-attività. Per altre informazioni sulle modifiche necessarie, vedere la guida 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 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 processi condivisi non viene terminato quando è inattiva, ma termina 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 JobCluster matrice 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 task campi. Le librerie non possono essere configurate in una configurazione del cluster di processi condivisi. Nell'esempio seguente il libraries campo 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 attività singola, la JobSettings struttura dei dati rimane invariata, ad eccezione dell'aggiunta del format campo. Non è inclusa alcuna TaskSettings matrice e le impostazioni dell'attività rimangono definite al livello superiore della struttura dei JobSettings dati. Non sarà necessario apportare modifiche ai client API esistenti per elaborare processi in formato 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:

Creare

Per creare un processo in formato singola attività tramite l'operazione 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 tasks campo 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 di invio

Per inviare un'unica esecuzione di un processo in formato singola attività con l'opzione Crea e attivare un'operazione di esecuzione una tantum (POST /runs/submit) nell'API Processi, non è necessario modificare i client esistenti.

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

Aggiornamento

Per aggiornare un processo in formato singola attività con l'operazione Parzialmente aggiornare 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 task impostazioni. Vedere Creare per un esempio JobSettings che specifica più attività.

Reimpostare

Per sovrascrivere le impostazioni di un processo in formato singola attività con sovrascrivi tutte le impostazioni per un'operazione di 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 JobSettings struttura di dati con una matrice di strutture di TaskSettings dati. Vedere Creare per un esempio JobSettings che specifica più attività.

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

Elenco

Per i processi in formato attività singola, non sono necessarie modifiche client per elaborare la risposta dall'operazione 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 Job struttura:

  • Analizzare il job_id campo per il processo in formato multi-attività.
  • Passare all'operazione job_id Ottenere un processo (GET /jobs/get) nell'API Processi per recuperare i dettagli del processo. Vedere Ottenere una risposta di esempio dalla Get chiamata API per un processo in formato multi-attività.

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 i processi in formato a singola attività, non sono necessarie modifiche client per elaborare la risposta dall'operazione Recupera un processo (GET /jobs/get) nell'API Processi.

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

Di seguito viene illustrata una risposta di esempio dalla Get chiamata API 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"
}

Esecuzione get

Per i processi in formato attività singola, non sono necessarie modifiche client per elaborare la risposta dall'operazione Get a job run (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 per run_id ogni attività.
  • Chiamare get the output for a run operation (GET /jobs/runs/get-output) con run_id per ottenere i dettagli sull'esecuzione per ogni 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 dall'oggetto Ottenere l'output per un'operazione di esecuzione (GET /jobs/runs/get-output) nell'API Processi.

Per i processi in formato multi-attività, la chiamata Runs get output a un'esecuzione padre 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 get the output for a run request .Call the Get the output for a run request.
  • Scorrere i campi figlio run_id nella risposta.
  • Usare i valori figlio run_id per chiamare Runs get output.

Elenco esecuzioni

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 vuota tasks . Passare all'operazione run_id Get a job run (GET /jobs/runs/get) per recuperare le attività. Di seguito viene illustrata una risposta di esempio dalla Runs list chiamata API 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
}