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

Статья
12/27/2024

Теперь можно оркестрировать несколько задач с помощью заданий Azure Databricks . В этой статье описаны изменения в API заданий , которые поддерживают задания с несколькими задачами и содержат рекомендации по update существующим клиентам API для работы с этой новой функцией.

Databricks рекомендует API заданий 2.1 для сценариев и клиентов API, особенно при использовании заданий с несколькими задачами.

В этой статье однозадочные задания определены как однозадачный формат, а многозадачные задания как многозадачный формат.

Jobs API версии 2.0 и 2.1 теперь поддерживает запрос update. Используйте запрос update, чтобы изменить существующее задание вместо запроса reset, чтобы свести к минимуму изменения между заданиями однофакторного формата и заданиями многофакторного формата.

Изменения API

API заданий теперь определяет объект TaskSettings для записи параметров для каждой задачи в задании. Для задач многозадачного формата поле tasks, представляющее собой массив структур данных TaskSettings, включается в объект JobSettings. Некоторые поля, ранее часть JobSettings, теперь являются частью параметров задачи для формата многоцелевых заданий. JobSettings также обновляется, чтобы включить поле format. Поле format указывает формат задания и является значением STRINGset для SINGLE_TASK или MULTI_TASK.

Необходимо update текущие клиенты API с учетом этих изменений в JobSettings для заданий многозадачного формата. Дополнительные сведения о необходимых изменениях см. в руководстве клиента API .

Jobs API 2.1 поддерживает формат многозадачности. Все запросы API 2.1 должны соответствовать этому формату, а ответы структурированы в этом формате.

API заданий 2.0 дополнен дополнительным полем для поддержки многозадачного формата. За исключением указанного в where, в примерах в этом документе используется API 2.0. Однако Databricks рекомендует API 2.1 для новых и существующих сценариев API и клиентов.

Пример документа JSON, представляющего задание многофакторного формата для API 2.0 и 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"
}

API заданий 2.1 поддерживает настройку кластеров уровня задач или одного или нескольких общих кластеров заданий:

Кластер уровня задач создается и запускается при начале задачи и завершает свою работу после ее завершения.
Общий кластер заданий позволяет нескольким задачам в одном задании использовать кластер. Кластер создается и запускается, когда первая задача с помощью кластера запускается и завершается после завершения последней задачи с помощью кластера. Общий кластер заданий не завершается при простое, но завершается только после завершения всех задач, использующих его. Несколько независимых задач совместного использования кластера могут запускаться одновременно. Если общий кластер заданий завершается сбоем или завершается до завершения всех задач, создается новый кластер.

Чтобы настроить кластеры общих заданий, включите массив JobCluster в объект JobSettings. Можно указать не более 100 кластеров на задание. Ниже приведен пример ответа API 2.1 для задания, настроенного с двумя общими кластерами:

Заметка

Если в задаче есть зависимости от библиотек, необходимо настроить библиотеки в параметрах поля task, так как библиотеки нельзя настроить в конфигурации общего кластера заданий. В следующем примере поле libraries в конфигурации задачи ingest_orders демонстрирует спецификацию зависимости библиотеки.

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

Для заданий форматирования с одной задачей структура данных JobSettings остается неизменной, за исключением добавления поля format. Нет TaskSettings массива, а параметры задач остаются на верхнем уровне структуры данных JobSettings. Вам не нужно вносить изменения в существующие клиенты API для обработки заданий однозаготочного формата.

Пример документа JSON, представляющего задание формата одной задачи для 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"
}

Руководство по клиенту API

В этом разделе даны рекомендации, примеры и необходимые изменения для вызовов API, связанных с новой функцией многозадачного формата.

Создать

Чтобы создать задание в формате одной задачи с помощью операции Создать новое задание (POST /jobs/create) в API для работы с заданиями, вам не нужно изменять существующих клиентов.

Чтобы создать задание многофакторного формата, используйте поле tasks в JobSettings, чтобы указать параметры для каждой задачи. В следующем примере создается задание с двумя задачами записной книжки. Этот пример предназначен для API 2.0 и 2.1:

Заметка

Можно указать не более 100 задач для каждого задания.

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

отправка запусков

Чтобы отправить выполнение однократного задания однозадачного формата с помощью операции Create and trigger a one-time run (POST /runs/submit) в Jobs API, вам не нужно изменять существующих клиентов.

Чтобы отправить однократное выполнение задания многофакторного формата, используйте поле tasks в JobSettings, чтобы указать параметры для каждой задачи, включая кластеры. Кластеры должны быть set на уровне задачи при отправке задания многозадачного формата, так как запрос runs submit не поддерживает общие кластеры для заданий. Пример с несколькими задачами см. в создании .

Update

Чтобы update однозадачный формат задания с Частично update операцию задания (POST /jobs/update) в API заданий, вам не нужно изменять существующих клиентов.

Чтобы update параметры задания многофакторного формата, необходимо использовать уникальное поле task_key для определения новых параметров task. Пример с несколькими задачами см. в создании .

Reset

Чтобы перезаписать параметры задания в формате одной задачи с помощью операции Перезаписать все параметры для задания (POST /jobs/reset) в API задач, вам не нужно изменять существующих клиентов.

Чтобы перезаписать параметры задания многофункционального формата, укажите структуру данных JobSettings в массиве из структур данных TaskSettings. Пример с несколькими задачами см. в создании .

Используйте Update для изменения отдельных полей без переключения из одной задачи в формат с несколькими задачами.

List

Для заданий в формате с одной задачей изменения на стороне клиента не требуются для обработки ответа на List всех заданий операции (GET /jobs/list) в API заданий.

Для заданий многофакторного формата большинство параметров определяются на уровне задачи, а не на уровне задания. Конфигурация кластера может быть set на уровне задачи или задания. Чтобы модифицировать клиентов для доступа к настройкам кластера или задачи в задании многозадачного формата, возвращаемого в структуре Job:

Анализ поля job_id для задания многозадачного формата.
Передайте job_id в Get операцию задания (GET /jobs/get) в API заданий, чтобы получить детали задания. См. Get для примера ответа из вызова API Get для задания многозадачного формата.

В следующем примере показан ответ, содержащий задания однофакторного и многофакторного формата. Этот пример предназначен для 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

Для заданий одно-задачного формата изменения со стороны клиента не требуются для обработки ответа от операции Get задания (GET /jobs/get) в API заданий.

Задания многофакторного формата возвращают массив структур данных task, содержащих параметры задачи. Если требуется доступ к сведениям о уровне задач, необходимо изменить клиентские программы, чтобы выполнить итерацию по массиву tasks и извлечь необходимые поля.

Ниже приведён пример ответа вызова API Get для задания с многофункциональным форматом. Этот пример предназначен для API 2.0 и 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"
}

запускается get

Для заданий с одним форматом задач изменения клиента не требуются для обработки ответа от Get выполнения задания операции (GET /jobs/runs/get) в API заданий.

Ответ на выполнение задания многозадачного формата содержит массив TaskSettings. Чтобы получить результаты выполнения для каждой задачи, выполните следующую команду:

Выполняет итерацию по каждой из задач.
Произведите разбор run_id для каждой задачи.
Выведите Get как выходные данные для операции выполнения (GET /jobs/runs/get-output) с подробностями от run_id до get о выполнении каждой задачи. Ниже приведен пример ответа из этого запроса:

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

выполняется выходные данные get

Для заданий в формате одной задачи изменения клиента не требуются для обработки ответа от Get результатов выполнения операции (GET /jobs/runs/get-output) в API заданий.

Для заданий многофакторного формата вызов Runs get output в родительском запуске приводит к ошибке, так как выходные данные запуска доступны только для отдельных задач. Чтобы get выходные данные и метаданные для задания многофакторного формата:

Назовите Get результатом для выполнения запроса.
Перебирайте по дочерним полям run_id в ответе.
Используйте дочерний run_idvalues для вызова Runs get output.

запускается list

Для одноформатных заданий не требуется изменений на стороне клиента для обработки ответа от List в рамках операции задания (GET /jobs/runs/list).

Для заданий многозадачного формата возвращается пустой массив tasks. Передайте run_idGet выполнение задания операции (GET /jobs/runs/get) для получения задач. Ниже показан пример ответа на вызов API Runs list для задания в многозадачном формате:

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

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