다음을 통해 공유

작업 API 2.0에서 2.1로 업데이트

  • 아티클

이제 Azure Databricks 작업여러 작업을 오케스트레이션할 수 있습니다. 이 문서에서는 여러 작업이 있는 작업을 지원하는 작업 API 변경 내용을 자세히 설명하며 기존 API 클라이언트가 이 새로운 기능을 사용할 수 update 데 도움이 되는 지침을 제공합니다.

Databricks는 특히 여러 작업이 있는 작업을 사용하는 경우 API 스크립트 및 클라이언트에 대해 작업 API 2.1을 권장합니다.

이 문서에서는 단일 작업으로 정의된 작업을 단일 작업 형식, 여러 태스크로 정의된 작업을 다중 작업 형식참조합니다.

작업 API 2.0 및 2.1은 이제 update 요청을 지원합니다. update 요청을 사용하여 reset 요청 대신 기존 작업을 변경하여 단일 작업 형식 작업과 다중 작업 형식 작업 간의 변경을 최소화합니다.

API 변경 사항

이제 작업 API는 작업의 각 작업에 대한 설정을 캡처하는 TaskSettings 개체를 정의합니다. 다중 작업 형식 작업의 경우 tasks 데이터 구조의 배열인 TaskSettings 필드가 JobSettings 개체에 포함됩니다. 이전에 JobSettings의 일부였던 필드는 이제 다중 작업 형식 작업의 설정에 포함됩니다. JobSettings가 format 필드를 포함하도록 업데이트됩니다. format 필드는 작업의 형식을 나타내며 STRING 값 set에서 SINGLE_TASK 또는 MULTI_TASK입니다.

기존 API 클라이언트를 다중 작업 형식 작업의 JobSettings 변경에 맞춰 update해야 합니다. 필요한 변경에 대한 자세한 내용은 API 클라이언트 가이드 참조하세요.

작업 API 2.1은 다중 작업 형식을 지원합니다. 모든 API 2.1 요청은 이 형식을 준수해야 하며 응답은 이 형식으로 구성됩니다.

작업 API 2.0은 다중 작업 형식 작업을 지원하기 위해 추가 필드로 업데이트됩니다. where 제외하면 이 문서의 예제에서는 API 2.0을 사용합니다. 그러나 Databricks는 신규 및 기존 API 스크립트 및 클라이언트에 API 2.1을 권장합니다.

API 2.0 및 2.1에 대한 다중 작업 형식 작업을 나타내는 예제 JSON 문서:

{
  "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 클라이언트를 변경할 필요가 없습니다.

API 2.0에 대한 단일 작업 형식 작업을 나타내는 예제 JSON 문서:

{
  "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 호출에 대한 지침, 예제 및 필수 변경 내용을 제공합니다.

이 섹션에서는 다음을 수행합니다.

만들기

작업 API의 새 작업 작업 만들기(POST /jobs/create)를 통해 단일 작업 형식의 작업을 생성하려면 기존 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식의 작업을 만들려면 tasks 필드를 JobSettings에서 사용하여 각 작업의 설정을 지정합니다. 다음 예제에서는 두 개의 Notebook 작업이 있는 작업을 만듭니다. 이 예제는 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
    }
  ]
}

실행 제출

작업 API에서 만들기 및 일회성 실행 작업(POST /runs/submit)을 사용하여 단일 작업 형식 작업의 일회성 실행을 제출하려면 기존 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식 작업의 일회성 실행을 제출하려면 tasksJobSettings 필드를 사용하여 클러스터를 포함한 각 작업에 대한 설정을 지정합니다. 다중 작업 형식의 작업을 제출할 때 클러스터는 작업 수준에서 반드시 set이어야 합니다. 이는 runs submit 요청이 공유 작업 클러스터를 지원하지 않기 때문입니다. 만들기을 참조하여 여러 작업을 지정하는 JobSettings 예제를 확인하세요.

Update

기존 클라이언트를 변경할 필요 없이, 작업 API에서와 같은 작업 작업을 통해 부분적으로 단일 작업 형식 작업을 수행할 수 있습니다.

다중 작업 형식 작업의 설정을 update 위해 고유한 task_key 필드를 사용하여 새 task 설정을 식별해야 합니다. 만들기을 참조하여 여러 작업을 지정하는 JobSettings 예제를 확인하세요.

Reset

작업 API에서 작업 작업()에 대한 모든 설정을 덮어쓰기 단일 작업 형식 작업의 설정을 덮어쓰려면 기존 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식 작업의 설정을 덮어쓰려면 JobSettings 데이터 구조의 배열로 구성된 TaskSettings 데이터 구조를 지정합니다. 만들기을 참조하여 여러 작업을 지정하는 JobSettings 예제를 확인하세요.

Update 사용하여 단일 작업에서 다중 작업 형식으로 전환하지 않고 개별 필드를 변경합니다.

List

단일 작업 형식 작업의 경우, 작업 API에서 모든 작업을 위한 List 작업 작업(GET /jobs/list)에 대한 응답을 처리하기 위해 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식의 경우, 대부분의 설정은 일 수준이 아니라 작업 수준에서 정의됩니다. 클러스터 구성은 태스크 또는 작업 수준에서 set일 수 있습니다. Job 구조에서 반환된 다중 작업 형식 작업에 대한 클러스터 또는 작업 설정에 액세스하도록 클라이언트를 수정하려면 다음을 수행합니다.

  • 다중 작업 형식 작업의 job_id 필드를 구문 분석합니다.
  • 작업 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

단일 작업 형식 업무의 경우, 작업 API에서 Get의 응답을 처리할 때 작업(GET /jobs/get)에 대해 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식 작업은 작업 설정을 포함하는 task 데이터 구조의 배열을 반환합니다. 작업 수준 세부 정보에 액세스해야 하는 경우 tasks 배열을 반복하고 필요한 필드를 추출하도록 클라이언트를 수정해야 합니다.

다음은 다중 작업 형식 작업에 대한 Get API 호출의 예제 응답을 보여줍니다. 이 예제는 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 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 출력

단일 작업 형식의 경우 Jobs API에서 실행 작업()의 출력에 대한 응답 처리를 위해 클라이언트를 변경할 필요가 없습니다.

멀티태스킹 형식 작업의 경우, 부모 실행에서 Runs get output을 호출하면, 실행 출력은 개별 작업에서만 가능하기 때문에 오류가 발생합니다. 다중 작업 형식 작업에 대한 출력 및 메타데이터를 get:

  • 실행 요청의 출력을 로 호출합니다.
  • 응답에서 자식 run_id 필드를 반복합니다.
  • 자식 run_idvalues을 사용해서 Runs get output를 호출합니다.

실행 list

단일 작업 형식 작업의 경우 작업 작업()에 대한 실행의 응답을 처리하기 위해 클라이언트를 변경할 필요가 없습니다.

다중 작업 형식 작업의 경우 빈 tasks 배열이 반환됩니다. run_id을(를) Get에 전달하여 작업(GET /jobs/runs/get)을 실행하고 태스크를 검색합니다. 다음은 다중 작업 형식 작업에 대한 Runs list API 호출의 예제 응답을 보여줍니다.

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