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

Статья
12/27/2024

В этой статье описаны обновления и улучшения функциональности в API заданий версии 2.2. Она содержит сведения, которые помогут вам update существующих клиентов 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 в телах запросов при создании или update задании.
Для заданий, созданных с помощью API заданий 2.0 и 2.1, очередь не включена по умолчанию. В этих версиях необходимо включить очередь, задав поле queuetrue в телах запросов при создании или update задании.

Вы можете включить или отключить очередь при создании задания, частично update заданияили update всех параметров задания.

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

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

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

List задания: См. изменения для заданий List и запросов на выполнение заданий List.
List выполнение заданий. См. изменения в заданиях List и запросы на выполнение заданий List.
Get одно задание. См. Get одно задание.
Get одно задание выполняется. См. Get один запуск.

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

Поля, представляющие списки элементов, таких как задачи, parameters, job_clusters или среды, ограничены 100 элементами на ответ. Если доступно более 100 values, текст ответа содержит поле 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="
}

Чтобы получить следующий set результатов, set параметр запроса 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 и заданий List, при выполнении которых запускается запросов, удаляется параметр has_more на корневом уровне объекта ответа. Вместо этого используйте существование next_page_token, чтобы определить, доступны ли дополнительные результаты. В противном случае функциональность для разбивки результатов остается неизменной.

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

Get одно задание

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

Get один запуск

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

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

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

schema каждого объекта в массиве iterations такой же, как и у объектов в массиве tasks.
Если параметр запроса only_latest находится в диапазоне от set до 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`

Get одно задание

Get один запуск

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

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

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

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

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

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

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

Get одно задание

Get один запуск

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

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

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