Compartir a través de

Actualización de Jobs API 2.0 a 2.1

Ahora puede organizar varias tareas con trabajos de Azure Databricks. En este artículo se detallan los cambios realizados en la API de trabajos que admiten trabajos con varias tareas y tiene instrucciones para ayudarle a actualizar los clientes de API existentes para que funcionen con esta nueva característica.

Databricks recomienda Jobs API 2.1 para los scripts y clientes de API, especialmente cuando se usan trabajos con varias tareas.

En este artículo se hace referencia a los trabajos definidos con una sola tarea como formato de tarea única y trabajos definidos con varias tareas como formato de varias tareas.

La API de trabajos 2.0 y 2.1 ahora admiten la solicitud de actualización . Utiliza la solicitud update para cambiar un trabajo existente en lugar de la solicitud de restablecimiento, para minimizar los cambios entre los trabajos de formato de tarea única y de formato de varias tareas.

Cambios de API

La API de trabajos ahora define un TaskSettings objeto para capturar la configuración de cada tarea de un trabajo. En los trabajos de formato de múltiples tareas, el campo tasks, que es una matriz de estructuras de datos TaskSettings, está incluido en el objeto JobSettings. Algunos campos que anteriormente formaban parte de JobSettings ahora forman parte de la configuración de tareas para trabajos en formato de varias tareas. JobSettings también se actualiza para incluir el format campo. El format campo indica el formato del trabajo y es un STRING valor establecido en SINGLE_TASK o MULTI_TASK.

Debe actualizar los clientes de API existentes para estos cambios en JobSettings para trabajos en formato multitarea. Consulte la guía del cliente de API para obtener más información sobre los cambios necesarios.

Jobs API 2.1 admite el formato de varias tareas. Todas las solicitudes de API 2.1 deben cumplir este formato y las respuestas se estructuran en este formato.

Jobs API 2.0 se ha actualizado con un campo adicional para soportar trabajos en formato de tareas múltiples. Excepto donde se indique, los ejemplos de este documento usan api 2.0. Sin embargo, Databricks recomienda API 2.1 para los clientes y scripts de API nuevos y existentes.

Un documento JSON de ejemplo que representa una tarea de formato múltiple para API 2.0 y 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"
}

Jobs API 2.1 admite la configuración de clústeres de nivel de tarea o uno o varios clústeres de trabajos compartidos:

  • Un clúster de nivel de tarea se crea y se inicia cuando comienza una tarea, y finaliza al completarse la tarea.
  • Un clúster de trabajos compartidos permite que varias tareas del mismo trabajo usen el clúster. El clúster se crea e inicia cuando se inicia la primera tarea mediante el clúster y finaliza después de que se complete la última tarea mediante el clúster. Un clúster de trabajos compartidos no finaliza cuando está inactivo, pero finaliza solo después de que se completen todas las tareas que lo usan. Varias tareas no dependientes que comparten un clúster pueden iniciarse al mismo tiempo. Si se produce un error en un clúster de trabajos compartidos o se finaliza antes de que finalicen todas las tareas, se crea un nuevo clúster.

Para configurar clústeres de trabajos compartidos, incluya una JobCluster matriz en el JobSettings objeto . Puede especificar un máximo de 100 clústeres por trabajo. A continuación se muestra un ejemplo de una respuesta de API 2.1 para un trabajo configurado con dos clústeres compartidos:

Nota:

Si una tarea tiene dependencias de biblioteca, debe configurar las bibliotecas en la configuración del task campo; las bibliotecas no se pueden configurar en una configuración de clúster de trabajos compartidos. En el ejemplo siguiente, el libraries campo de la configuración de la ingest_orders tarea muestra la especificación de una dependencia de biblioteca.

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

En el caso de los trabajos de formato de tarea única, la JobSettings estructura de datos permanece sin cambios, excepto la adición del campo format. No se incluye ninguna TaskSettings matriz y la configuración de la tarea permanece definida en el nivel superior de la JobSettings estructura de datos. No tendrá que realizar cambios en los clientes de API existentes para procesar trabajos de formato de tarea única.

Un documento JSON de ejemplo que representa un trabajo de formato de tarea único para 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"
}

Guía del cliente de API

En esta sección se proporcionan instrucciones, ejemplos y cambios necesarios para las llamadas API afectadas por la nueva característica de formato de varias tareas.

En esta sección:

Crear

Para crear un trabajo de formato de tarea única mediante la operación Crear un nuevo trabajo (POST /jobs/create) en la API de trabajos, no es necesario cambiar los clientes existentes.

Para crear un trabajo en formato de varias tareas, use el campo tasks en JobSettings para especificar la configuración de cada tarea. En el ejemplo siguiente se crea un trabajo con dos tareas de cuaderno. Este ejemplo es para api 2.0 y 2.1:

Nota:

Se puede especificar un máximo de 100 tareas por trabajo.

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

Envío de ejecuciones

Para enviar una ejecución única de un trabajo de formato de tarea única con la operación Crear y activar una ejecución única (POST /runs/submit) en la API de Jobs, no es necesario cambiar los clientes existentes.

Para enviar una ejecución única de un trabajo en formato de múltiples tareas, use el campo tasks en JobSettings para especificar la configuración de cada tarea, incluidos los clústeres. Al enviar un trabajo en formato de varias tareas, los clústeres deben establecerse a nivel de tarea, ya que la solicitud runs submit no admite clústeres de trabajos compartidos. Consulte Crear para obtener un ejemplo JobSettings que especifique varias tareas.

Actualizar

Para actualizar un trabajo de formato de tarea única con la operación Parcialmente actualizar un trabajo (POST /jobs/update) en la API de Jobs, no es necesario cambiar los clientes existentes.

Para actualizar la configuración de un trabajo con formato multitarea, debe usar el campo único task_key para identificar los nuevos ajustes task. Consulte Crear para obtener un ejemplo JobSettings que especifique varias tareas.

Reiniciar

Para sobrescribir la configuración de un trabajo de formato de tarea única con la operación Sobrescribir toda la configuración para un trabajo (POST /jobs/reset) en la API de Jobs, no es necesario cambiar los clientes existentes.

Para sobrescribir la configuración de un trabajo de formato de varias tareas, especifique una estructura de datos JobSettings con una matriz de estructuras de datos TaskSettings. Consulte Crear para obtener un ejemplo JobSettings que especifique varias tareas.

Use Update para cambiar campos individuales sin cambiar de una tarea a formato de varias tareas.

Lista

En el caso de los trabajos de formato de tarea única, no se requiere ningún cambio de cliente para procesar la respuesta de la operación Enumerar todos los trabajos (GET /jobs/list) en la API de trabajos.

En el caso de los trabajos de formato de múltiples tareas, la mayoría de las configuraciones se definen a nivel de tarea y no a nivel de trabajo. La configuración del clúster se puede establecer en el nivel de tarea o trabajo. Para modificar la configuración de los clientes para que accedan a los ajustes de clúster o de tarea de un trabajo en formato multitarea devuelto en la estructura Job.

  • Analice el campo job_id para el trabajo de formato multitarea.
  • job_id Pase a la operación Obtener un trabajo (GET /jobs/get) en la API de trabajos para recuperar los detalles del trabajo. Consulte Get para un ejemplo de respuesta de la llamada a la API para un trabajo de formato de múltiples tareas.

En el ejemplo siguiente se muestra una respuesta que contiene trabajos de formato de tarea única y de varias tareas. Este ejemplo es para la 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"
    }
  ]
}

Obtener

En el caso de los trabajos de formato de tarea única, no se requiere ningún cambio de cliente para procesar la respuesta de la operación Obtener un trabajo (GET /jobs/get) en la API de trabajos.

Los trabajos en formato multitarea devuelven una matriz de estructuras de datos task que contienen la configuración de la tarea. Si necesita acceso a los detalles del nivel de tarea, debe modificar los clientes para recorrer en iteración la tasks matriz y extraer los campos necesarios.

A continuación se muestra un ejemplo de respuesta de la llamada a la API Get para un trabajo en formato de múltiples tareas. Este ejemplo es para api 2.0 y 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"
}

Ejecuciones obtenidas

En el caso de los trabajos en formato de tarea única, no se requieren cambios de cliente para procesar la respuesta de la operación Obtener la ejecución de un trabajo (GET /jobs/runs/get) en la API de trabajos.

La respuesta para una ejecución de trabajo en formato multitarea contiene una matriz de TaskSettings. Para recuperar los resultados de ejecución de cada tarea:

  • Recorrer en iteración cada una de las tareas.
  • Analice el objeto run_id para cada tarea.
  • Llame a la operación para obtener la salida de una ejecución Get the output for a run (GET /jobs/runs/get-output) con el run_id para obtener detalles sobre la ejecución de cada tarea. A continuación se muestra una respuesta de ejemplo de esta solicitud:
{
  "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"
}

Las ejecuciones generan la salida

Para trabajos de formato de tarea única, no se requiere ningún cambio en el cliente para procesar la respuesta de la operación Obtener la salida para una ejecución (GET /jobs/runs/get-output) en la API de trabajos.

En el caso de los trabajos con formato de varias tareas, llamar a Runs get output en una ejecución primaria produce un error, ya que la salida de ejecución solo está disponible para tareas individuales. Para obtener la salida y los metadatos de un trabajo en formato multitarea:

Lista de ejecuciones

En el caso de los trabajos en formato de una sola tarea, no se requiere ningún cambio de cliente para procesar la respuesta de la operación List runs for a job (GET /jobs/runs/list).

En el caso de los trabajos con formato para múltiples tareas, se devuelve una matriz vacía tasks. run_id Pasa a la operación ejecutar el trabajo (GET /jobs/runs/get) para recuperar las tareas. A continuación se muestra una respuesta de ejemplo de la Runs list llamada API para un trabajo en formato multitarea:

{
  "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
}
  • Last updated on