Actualizar Jobs API 2.0 a 2.1

  • Artículo

Ahora puede organizar varias tareas con trabajo de Azure Databricks. En este artículo se detallan los cambios en Jobs API para permitir trabajos con varias tareas y se proporcionan 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 clientes y scripts 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 a los trabajos definidos con varias tareas como formato de varias tareas.

Jobs API 2.0 y 2.1 ahora admiten la solicitud update. Use la solicitud update para cambiar un trabajo existente en lugar de la solicitud reset para minimizar los cambios entre los trabajos de formato de tarea única y los trabajos con formato de varias tareas.

Cambios de API

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

Debe actualizar los clientes de API existentes con estos cambios en JobSettings para los trabajos con formato de varias tareas. Consulte la guía del cliente de API para 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 ajustarse al formato de varias tareas y las respuestas se estructuran en este mismo formato. Primero se lanzan nuevas características de API 2.1.

Jobs API 2.0 se actualiza con un campo adicional para admitir trabajos en formato de varias tareas. Excepto donde se indica, en los ejemplos de este documento se usa API 2.0. Sin embargo, Databricks recomienda API 2.1 para clientes y scripts de API nuevos y existentes.

Documento JSON de ejemplo que representa un trabajo en formato de varias tareas 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:

  • Se crea e inicia un clúster de nivel de tarea cuando se inicia una tarea y finaliza cuando se completa 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 y finaliza la primera tarea que usa el clúster después de que se complete la última tarea con el clúster. Un clúster de trabajos compartidos no finaliza cuando está inactivo, sino que lo hace una vez completadas todas las tareas que lo usan. Varias tareas no dependientes que comparten un clúster se pueden iniciar al mismo tiempo. Si se produce un error en un clúster de trabajos compartidos o este termina antes de que finalicen todas las tareas, se crea un nuevo clúster.

Para configurar clústeres de trabajos compartidos, incluya una matriz JobCluster en el objeto JobSettings. Puede especificar hasta 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 campo task; las bibliotecas no se pueden configurar en una configuración de clúster de trabajos compartidos. En el ejemplo siguiente, el campo libraries de la configuración de la tarea ingest_orders 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 en formato de tarea única, la estructura de datos JobSettings permanece sin cambios, excepto por la adición del campo format. No se incluye ninguna matriz TaskSettings y la configuración de la tarea permanece definida en el nivel superior de la estructura de datos JobSettings. Para procesar trabajos en formato de tarea única, no tendrá que realizar cambios en los clientes de API existentes.

Documento JSON de ejemplo que representa un trabajo en formato de tarea única 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:

Create

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

Para crear un trabajo en formato de varias tareas, use el campo tasks de 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 puntual de un trabajo en formato de tarea única con la operación Create and trigger a one-time run (Crear y desencadenar una ejecución puntual) (POST /runs/submit) de Jobs API, no es necesario cambiar los clientes existentes.

Para enviar una ejecución puntual de un trabajo en formato de varias tareas, use el campo tasks de JobSettings para especificar la configuración de cada tarea, incluidos los clústeres. Los clústeres deben establecerse en el nivel de tarea al enviar un trabajo en formato de varias tareas porque la solicitud runs submit no admite clústeres de trabajos compartidos. Consulte Create para ver un ejemplo de JobSettings que especifica varias tareas.

Actualización

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

Para actualizar la configuración de un trabajo en formato de varias tareas, debe usar el campo único task_key para identificar la nueva configuración de task. Consulte Create para ver un ejemplo de JobSettings que especifica varias tareas.

Reset

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

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

Use Update para cambiar campos individuales sin pasar del formato de tarea única al formato de varias tareas.

List

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

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

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

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

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

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

A continuación, se muestra una respuesta de ejemplo de la llamada API Get de un trabajo en formato de varias 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"
}

Runs get

En el caso de los trabajos en formato de tarea única, no se requiere ningún cambio del cliente para procesar la respuesta de la operación Get a job run (Obtener una ejecución de trabajo) (GET /jobs/runs/get) de Jobs API.

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

  • Recorra en iteración cada una de las tareas.
  • Analice el valor de run_id de cada tarea.
  • Llame a la operación Get the output for a run (Obtener la salida de una ejecución) (GET /jobs/runs/get-output) con 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"
}

Runs get output

En el caso de los trabajos en formato de tarea única, no se requiere ningún cambio de cliente para procesar la respuesta de la operación Get the output for a run (Obtener la salida de una ejecución) (GET /jobs/runs/get-output) de Jobs API.

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

  • Llame a la solicitud Get the output for a run (Obtener la salida de una ejecución).
  • Recorra en iteración los campos run_id secundarios de la respuesta.
  • Use los valores de run_id secundarios para llamar a Runs get output.

Runs list

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

En el caso de los trabajos en formato de varias tareas, se devuelve una matriz tasks vacía. Pase run_id a la operación Get a job run (Obtener una ejecución de trabajo) (GET /jobs/runs/get) para recuperar las tareas. A continuación, se muestra una respuesta de ejemplo de la llamada API Runs list de un trabajo en formato de varias tareas:

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