Обновление с API заданий 2.1 до версии 2.2

Статья
01/23/2025

В этой статье описаны обновления и улучшения функциональности в API заданий версии 2.2. Она содержит сведения, помогающие обновить существующие клиенты API для работы с этой новой версией. Эти обновления включают установку заданий в очередь по умолчанию и улучшенную поддержку постраничного отображения в случаях, когда ответы содержат поля с более чем 100 элементами. Так как версия 2.2 улучшает существующую поддержку разбиения на страницы больших результирующих наборов, Databricks рекомендует использовать его для сценариев API и клиентов, особенно если ответы могут включать множество задач.

Сведения об изменениях между версиями 2.0 и 2.1 API см. в статье обновление API заданий 2.0 до версии 2.1.

Помимо изменений, включенных в API заданий Databricks версии 2.1, в версии 2.2 есть следующие улучшения:

Задания по умолчанию помещаются в очередь

Очередь заданий — это необязательная функция, которая предотвращает пропускание заданий, когда ресурсы недоступны для выполнения. Поддержка очереди заданий осуществляется в версиях Jobs API 2.0, 2.1 и 2.2, с со следующими различиями в обработке очередности по умолчанию:

Для заданий, созданных с помощью API заданий 2.2, очередь включена по умолчанию. Вы можете отключить постановку в очередь, установив поле queue в false в теле запроса при создании или обновлении задачи.
Для заданий, созданных с помощью API заданий 2.0 и 2.1, очередь не включена по умолчанию. В этих версиях необходимо включить режим очереди, установив значение поля queue на true в телах запросов при создании или обновлении задания.

При создании задания можно управлять очередностью, включая или отключая её, а также частично обновить заданиеили обновить все параметры задания.

См. очереди заданий.

Поддержка разбиения по страницам длинных списков задач и выполнений задач

Для поддержки заданий с большим количеством задач или запусков задач API заданий 2.2 изменяет то, как возвращаются большие наборы результатов для следующих запросов:

Список заданий: см. Изменения в запросах на список заданий и выполнение заданий.
Список запусков заданий: см. Изменения в запросах на создание списка заданий и запусков заданий.
Получить одну работу: см. Получить одну работу.
Получение одного выполнения задания: см. получение одного выполнения.

API заданий 2.2 изменяет разбивку на страницы для этих запросов следующим образом:

Поля, представляющие списки элементов, таких как задачи, параметры, job_clusters или среды, ограничены 100 элементами на ответ. Если доступно более 100 значений, текст ответа содержит поле next_page_token, содержащее маркер для получения следующей страницы результатов.
Разбивка на страницы добавляется для ответов на запросы Get a single job и Get a single job run. Разбиение на страницы для ответов на запросы List job и List job runs было добавлено в API Jobs 2.1.

Ниже приведен пример текста ответа из запроса Get a single job задания с более чем 100 задачами. Чтобы продемонстрировать функциональность разбиения на страницах на основе маркеров, в этом примере большинство полей, включенных в текст ответа, не учитываются:

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

Чтобы получить следующий набор результатов, задайте параметр запроса page_token в следующем запросе на значение, возвращаемое в поле next_page_token. Например, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Если нет дополнительных результатов, поле next_page_token не включается в ответ.

В следующих разделах содержатся дополнительные сведения об обновлениях для каждого из запросов list и get.

Изменения запросов и `List jobsList job runs`

Для запросов List jobs и List job runs, параметр has_more на корневом уровне объекта ответа удален. Вместо этого используйте существование next_page_token, чтобы определить, доступны ли дополнительные результаты. В противном случае функциональность для разбивки результатов остается неизменной.

Чтобы избежать крупных объемов данных в ответе, массивы верхнего уровня tasks и job_clusters для каждого задания по умолчанию не включаются в ответы. Чтобы включить эти массивы для каждого задания, включенного в текст ответа для этих запросов, добавьте параметр expand_tasks=true в запрос. Если expand_tasks включен, в массивах tasks и job_clusters возвращаются не более 100 элементов. Если любой из этих массивов содержит более 100 элементов, поле has_more (не путать с полем has_more корневого уровня, которое удаляется), в объекте job задано значение true. Однако доступны только первые 100 элементов. Вы не можете получить дополнительные задачи или кластеры после первых ста с помощью запроса List jobs. Чтобы получить больше элементов, используйте запросы, которые возвращают одну задачу или один запуск задачи. Обновления, поддерживающие разбивку на страницы больших полей ответа, рассматриваются в следующих разделах.

Получить одну работу

В версии API Jobs 2.2 запрос "Получить одно задание" на извлечение данных об одном задании теперь поддерживает пагинацию для полей tasks и job_clusters, если размер какого-либо из полей превышает 100 элементов. Используйте поле next_page_token в корне объекта, чтобы определить, доступны ли дополнительные результаты. Затем значение этого поля используется в качестве значения для параметра запроса page_token в последующих запросах. Поля массива с менее чем 100 элементами на одной странице будут пустыми на последующих страницах.

Получить один запуск

В API Jobs 2.2 запрос для получения сведений об одном запуске теперь поддерживает пагинацию полей tasks и job_clusters, когда размер любого из полей превышает 100 элементов. Используйте поле next_page_token в корне объекта, чтобы определить, доступны ли дополнительные результаты. Затем значение этого поля используется в качестве значения для параметра запроса page_token в последующих запросах. Поля массива с менее чем 100 элементами на одной странице будут пустыми на последующих страницах.

API заданий 2.2 также добавляет параметр запроса only_latest в эту конечную точку, чтобы отображать только последние попытки запуска в массиве tasks. Если параметр only_latesttrue, любые запуски, заменяемые повторными попытками или восстановлением, исключены из ответа.

Если run_id ссылается на выполнение задачи ForEach, в ответе присутствует поле с именем iterations. Поле iterations — это массив, содержащий сведения обо всех запусках вложенной задачи ForEach и имеет следующие свойства:

Схема каждого объекта в массиве iterations совпадает с схемой объектов в массиве tasks.
Если для параметра запроса only_latest задано значение true, в массив iterations включены только последние попытки выполнения.
Разбивка на страницы применяется к массиву iterations вместо массива tasks.
Массив tasks по-прежнему включен в ответ, а также включает выполнение задачи ForEach.

Дополнительные сведения о задаче ForEach см. в документации по задаче ForEach .

Например, см. следующий ответ для задачи ForEach с некоторыми полями, опущенными:

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

Поделиться через

Обновление с API заданий 2.1 до версии 2.2

Задания по умолчанию помещаются в очередь

Поддержка разбиения по страницам длинных списков задач и выполнений задач

Изменения запросов и `List jobsList job runs`

Получить одну работу

Получить один запуск

Обратная связь

Дополнительные ресурсы

Поделиться через

Обновление с API заданий 2.1 до версии 2.2

Задания по умолчанию помещаются в очередь

Поддержка разбиения по страницам длинных списков задач и выполнений задач

Изменения запросов и List jobsList job runs

Получить одну работу

Получить один запуск

Обратная связь

Дополнительные ресурсы

Изменения запросов и `List jobsList job runs`