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

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

  • Статья

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

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

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

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

Изменения API

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

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

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

API заданий 2.0 дополнен дополнительным полем для поддержки многозадачного формата. Кроме того, где указано, в примерах в этом документе используется 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, чтобы указать параметры для каждой задачи, включая кластеры. Кластеры должны быть заданы на уровне задачи при отправке задания многофакторного формата, так как запрос runs submit не поддерживает общие кластеры заданий. Пример с несколькими задачами см. в создании .

обновление

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

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

сброс

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

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

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

Список

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

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

  • Анализ поля job_id для задания многозадачного формата.
  • Передайте job_id в операцию «Получить работу» (GET /jobs/get) в API заданий, чтобы получить сведения о задании. См. чтобы получить в качестве примера ответа из вызова 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 /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 /jobs/runs/get) в API заданий.

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

  • Выполняет итерацию по каждой из задач.
  • Произведите разбор run_id для каждой задачи.
  • Вызовите , чтобы получить результаты выполнения операции (GET /jobs/runs/get-output) с использованием run_id и узнать детали выполнения для каждой задачи. Ниже приведен пример ответа из этого запроса:
{
  "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 /jobs/runs/get-output) в API заданий.

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

список запусков

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

Для заданий многозадачного формата возвращается пустой массив tasks. Передайте run_id в получить операцию выполнения задания (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
}