Compartir a través de

Actualización de Jobs API 2.1 a 2.2

  • Artículo

En este artículo se detallan las actualizaciones y mejoras de la funcionalidad de la versión 2.2 de la API de trabajos. Incluye información que le ayudará a actualizar los clientes de API existentes para que funcionen con esta nueva versión. Estas actualizaciones incluyen la puesta en cola predeterminada de trabajos y una mejor compatibilidad con la paginación cuando las respuestas incluyen campos con más de 100 elementos. Dado que la versión 2.2 mejora la compatibilidad existente con la paginación de grandes conjuntos de resultados, Databricks recomienda usarlo para los scripts de API y los clientes, especialmente cuando las respuestas pueden incluir muchas tareas.

Para obtener información sobre los cambios entre las versiones 2.0 y 2.1 de la API, consulta Actualización desde Jobs API 2.0 a 2.1.

Además de los cambios incluidos en la versión 2.1 de la API de trabajos de Databricks, la versión 2.2 tiene las siguientes mejoras:

Los trabajos se ponen en cola de manera predeterminada

La puesta en cola de trabajos es una característica opcional que impide que se omitan trabajos cuando no hay recursos disponibles. La puesta en cola de trabajos se admite en las versiones 2.0, 2.1 y 2.2 de Jobs API, con las siguientes diferencias en el control predeterminado de la puesta en cola:

  • En el caso de los trabajos creados con jobs API 2.2, la puesta en cola está habilitada de forma predeterminada. Puedes desactivar la puesta en cola estableciendo el campo queue en false en cuerpos de solicitud al crear o actualizar un trabajo.
  • En el caso de los trabajos creados con las versiones 2.0 y 2.1 de Jobs API, la puesta en cola no está habilitada de manera predeterminada. Con estas versiones, debes habilitar la puesta en cola estableciendo el campo queue en true en cuerpos de solicitud al crear o actualizar un trabajo.

Puedes habilitar o deshabilitar la puesta en cola al crear un trabajo, actualizar parcialmente un trabajo o actualizar todas las configuraciones de trabajo.

Consulta Puesta en cola de trabajos.

Compatibilidad con la paginación de listas de ejecución de tareas y tareas largas

Para admitir trabajos con un gran número de tareas o ejecuciones de tareas, Jobs API 2.2 cambia el tamaño de los conjuntos de resultados que se devuelven para las siguientes solicitudes:

La API de trabajos 2.2 cambia la paginación de estas solicitudes de la siguiente manera:

  • Los campos que representan listas de elementos como tareas, parámetros, job_clusters o entornos se limitan a 100 elementos por respuesta. Si hay más de 100 valores disponibles, el cuerpo de la respuesta incluye un campo next_page_token que contiene un token para recuperar la siguiente página de resultados.
  • La paginación se agrega en las respuestas a las solicitudes de Get a single job y Get a single job run. La paginación de las respuestas a las solicitudes List job y List job runs se agregó con Jobs API 2.1.

A continuación se muestra un ejemplo del cuerpo de la respuesta de una solicitud Get a single job para un trabajo con más de 100 tareas. Para demostrar la funcionalidad de paginación basada en tokens, en este ejemplo se omiten la mayoría de los campos incluidos en el cuerpo de la respuesta:

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

Para recuperar el siguiente conjunto de resultados, establezca el parámetro de consulta page_token en la siguiente solicitud al valor devuelto en el campo next_page_token. Por ejemplo, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Si no hay más resultados disponibles, el campo next_page_token no se incluye en la respuesta.

En las secciones siguientes se proporcionan más detalles sobre las actualizaciones de cada una de las solicitudes de list y get.

Cambios en las solicitudes de List jobs y List job runs

Para las solicitudes de Mostrar trabajos y Mostrar ejecuciones de trabajos, se quita el parámetro has_more en el nivel raíz del objeto de respuesta. En su lugar, use la existencia del next_page_token para determinar si hay más resultados disponibles. De lo contrario, la funcionalidad para paginar los resultados permanece sin cambios.

Para evitar cuerpos de respuesta grandes, los arrays de nivel superior tasks y job_clusters para cada trabajo se omiten de las respuestas por defecto. Para incluir estas matrices para cada trabajo incluido en el cuerpo de respuesta de estas solicitudes, agregue el parámetro expand_tasks=true a la solicitud. Cuando se habilita expand_tasks, se devuelve un máximo de 100 elementos en las matrices tasks y job_clusters. Si cualquiera de estas matrices tiene más de 100 elementos, un campo has_more (no confundirse con el campo de nivel raíz has_more que se quita) dentro del objeto job se establece en true. Sin embargo, solo se puede acceder a los primeros 100 elementos. No se pueden recuperar tareas ni clústeres adicionales después de los primeros 100 con la solicitud Mostrar trabajos. Para obtener más elementos, usa las solicitudes que devuelven un único trabajo o una única ejecución de trabajo. Las actualizaciones que admiten la paginación de campos de respuesta grandes se describen en las secciones siguientes.

Obtención de un solo trabajo

En Jobs API 2.2, la solicitud de Obtener un trabajo único para recuperar detalles sobre un único trabajo ahora admite la paginación de los campos tasks y job_clusters cuando el tamaño de cualquiera de los campos supera los 100 elementos. Use el campo next_page_token en la raíz del objeto para determinar si hay más resultados disponibles. A continuación, el valor de este campo se usa como valor para el parámetro de consulta page_token en las solicitudes posteriores. Los campos de matriz con menos de 100 elementos de una página estarán vacíos en las páginas posteriores.

Obtención de una sola ejecución

En Jobs API 2.2, la solicitud Obtener una ejecución única para recuperar detalles sobre una sola ejecución ahora admite la paginación de los campos tasks y job_clusters cuando el tamaño de cualquiera de los campos supera los 100 elementos. Use el campo next_page_token en la raíz del objeto para determinar si hay más resultados disponibles. A continuación, el valor de este campo se usa como valor para el parámetro de consulta page_token en las solicitudes posteriores. Los campos de matriz con menos de 100 elementos de una página estarán vacíos en las páginas posteriores.

La API de trabajos 2.2 también agrega el parámetro de consulta only_latest a este punto de conexión para permitir que solo se muestren los intentos de ejecución más recientes en la matriz de tasks. Cuando el parámetro only_latest es true, las ejecuciones reemplazadas por un reintento o una reparación se omiten de la respuesta.

Cuando el run_id hace referencia a la ejecución de una tarea ForEach, un campo denominado iterations está presente en la respuesta. El campo iterations es una matriz que contiene detalles de todas las ejecuciones de la tarea anidada de la tarea ForEach y tiene las siguientes propiedades:

  • El esquema de cada objeto de la matriz iterations es el mismo que el de los objetos de la matriz tasks.
  • Si el parámetro de consulta only_latest se establece en true, solo se incluyen los intentos de ejecución más recientes en la matriz iterations.
  • La paginación se aplica a la matriz iterations en lugar de a la matriz tasks.
  • La matriz tasks sigue incluida en la respuesta e incluye la ejecución de la tarea ForEach.

Para obtener más información sobre la tarea ForEach, consulta la Documentación de la tarea ForEach.

Por ejemplo, consulte la siguiente respuesta para una tarea de ForEach con algunos campos omitidos:

{
  "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": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}