작업 API 2.0에서 2.1로 업데이트
이제 Azure Databricks 작업을 사용하여 여러 개의 태스크를 오케스트레이션할 수 있습니다. 이 문서에서는 여러 작업으로 작업을 지원하는 작업 API의 변경 내용을 자세히 설명하며, 이 새로운 기능을 사용하도록 기존 API 클라이언트를 업데이트하는 데 도움이 되는 지침을 제공합니다.
Databricks는 특히 여러 태스크를 갖는 작업을 사용하는 경우 API 스크립트 및 클라이언트에서 작업 API 2.1을 사용할 것을 권장합니다.
이 문서에서는 단일 태스크로 정의된 작업을 단일 작업 형식으로, 여러 태스크를 다중 작업 형식으로 정의한 작업을 참조합니다.
작업 API 2.0 및 2.1은 이제 update 요청을 지원합니다. 기존 작업을 변경할 때 reset 요청 대신 update 요청을 사용하면 단일 태스크 형식 작업과 다중 태스크 형식 작업 간의 변경 사항을 최소화할 수 있습니다.
API 변경
작업 API는 이제 작업의 각 태스크의 설정을 캡처하는 TaskSettings 개체를 정의합니다. 다중 태스크 형식 작업의 경우 JobSettings 개체에 tasks 필드(TaskSettings 데이터 구조체로 구성된 배열)가 포함됩니다. 이전에 JobSettings의 일부였던 몇몇 필드가 이제 다중 태스크 형식 작업의 태스크 설정의 일부가 되었습니다. JobSettings는 format 필드를 포함하도록 업데이트되었습니다. format 필드는 작업의 형식을 나타내며, STRING 값이 SINGLE_TASK 또는 MULTI_TASK로 설정됩니다.
다중 태스크 형식 작업에 맞게 변경된 JobSettings를 사용하려면 기존 API 클라이언트를 업데이트해야 합니다. 필요한 변경 사항에 대해 자세히 알아보려면 API 클라이언트 가이드를 참조하세요.
작업 API 2.1은 다중 태스크 형식을 지원합니다. 모든 API 2.1 요청은 다중 태스크 형식을 준수해야 하며, 응답은 다중 태스크 형식으로 구성됩니다. 새로운 기능은 먼저 API 2.1에서 릴리스됩니다.
작업 API 2.0은 다중 태스크 형식 작업을 지원하는 추가 필드를 갖도록 업데이트되었습니다. 달리 명시된 경우를 제외하고, 이 문서의 예제에서는 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은 태스크 수준 클러스터 또는 하나 이상의 공유 작업 클러스터의 구성을 지원합니다.
- 태스크 수준 클러스터는 태스크가 시작될 때 생성 및 시작되고 태스크가 완료될 때 종료됩니다.
- 공유 작업 클러스터를 사용하면 동일한 작업에 속한 여러 태스크가 클러스터를 사용할 수 있습니다. 클러스터는 해당 클러스터를 사용하는 첫 번째 작업이 시작될 때 생성 및 시작되고 해당 클러스터를 사용하는 마지막 작업이 완료될 때 종료됩니다. 공유 작업 클러스터는 유휴 상태일 때 종료되지 않으며, 해당 클러스터를 사용하는 모든 작업이 완료된 후에만 종료됩니다. 하나의 클러스터를 공유하는 여러 개의 비종속 태스크가 동시에 시작될 수 있습니다. 공유 작업 클러스터가 실패하거나 모든 태스크가 완료되기 전에 종료되면 새 클러스터가 만들어집니다.
공유 작업 클러스터를 구성하려면 JobSettings 개체 내에 JobCluster 배열을 포함해야 합니다. 작업당 최대 100개의 클러스터를 지정할 수 있습니다. 다음은 두 개의 공유 클러스터로 구성된 작업에 대한 API 2.1 응답의 예입니다.
참고 항목
태스크가 라이브러리 종속성을 갖는 경우, task 필드 설정에서 라이브러리를 구성해야 합니다. 공유 작업 클러스터 구성에는 라이브러리를 구성할 수 없습니다. 다음 예제에서는 ingest_orders 태스크 구성의 libraries 필드가 라이브러리 종속성 사양을 보여 줍니다.
{
"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)을 사용하여 단일 태스크 형식 작업을 만들려면 기존 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업을 만들려면 JobSettings의 tasks 필드를 사용하여 각 태스크의 설정을 지정해야 합니다. 다음 예제에서는 두 개의 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)을 사용하여 단일 태스크 형식 작업의 일회성 실행을 제출하려면 기존 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 일회성 실행을 제출하려면 JobSettings의 tasks 필드를 사용하여 클러스터를 포함하는 각 태스크의 설정을 지정해야 합니다. runs submit 요청은 공유 작업 클러스터를 지원하지 않으므로 다중 태스크 형식 작업을 제출할 때는 태스크 수준에서 클러스터를 설정해야 합니다. 다중 태스크를 지정하는 JobSettings 예제를 보려면 만들기를 참조하세요.
업데이트
작업 API의 부분적으로 작업 업데이트 작업(POST /jobs/update)을 사용하여 단일 태스크 형식 작업을 업데이트하려면 기존 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 설정을 업데이트하려면 고유한 task_key 필드를 사용하여 새 task 설정을 식별해야 합니다. 다중 태스크를 지정하는 JobSettings 예제를 보려면 만들기를 참조하세요.
초기화
작업 API의 작업의 모든 설정 덮어쓰기 작업(POST /jobs/reset)을 사용하여 단일 태스크 형식 작업의 설정을 덮어쓰려면 기존 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 설정을 덮어쓰려면 TaskSettings 데이터 구조체로 구성된 배열을 사용하여 JobSettings 데이터 구조체를 지정해야 합니다. 다중 태스크를 지정하는 JobSettings 예제를 보려면 만들기를 참조하세요.
단일 태스크 형식에서 다중 태스크 형식으로 전환하지 않고 개별 필드를 변경하려면 업데이트를 사용합니다.
목록
단일 태스크 형식 작업의 경우, 작업 API의 모든 작업 나열 작업(GET /jobs/list)의 응답을 처리하려면 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 경우, 대부분의 설정이 작업 수준이 아닌 태스크 수준에서 정의됩니다. 클러스터 구성은 태스크 또는 작업 수준에서 설정할 수 있습니다. 클라이언트가 Job 구조체로 반환된 다중 태스크 형식 작업의 클러스터 또는 태스크 설정에 액세스하도록 수정하려면 다음을 수행합니다.
- 다중 태스크 형식 작업의
job_id필드를 구문 분석합니다. job_id를 작업 API의 작업 가져오기 작업(GET /jobs/get)으로 전달하여 작업 세부 정보를 찾아옵니다. 다중 태스크 형식 작업에 대한GetAPI 호출의 응답 예를 보려면 가져오기를 참조하세요.
다음 예제에서는 단일 태스크 및 다중 태스크 형식 작업을 포함하는 응답을 보여 줍니다. 이 예제는 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"
}
]
}
가져오기
단일 태스크 형식 작업의 경우, 작업 API의 작업 가져오기 작업(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"
}
실행 가져오기
단일 태스크 형식 작업의 경우, 작업 API의 작업 실행 가져오기 작업(GET /jobs/runs/get)의 응답을 처리하려면 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 응답은 TaskSettings로 구성된 배열을 포함합니다. 각 태스크의 실행 결과를 찾아오려면 다음을 수행합니다.
- 각 태스크를 반복 확인합니다.
- 각 태스크의
run_id를 구문 분석합니다. run_id와 함께 실행의 출력 가져오기 작업(GET /jobs/runs/get-output)을 호출하여 각 태스크의 실행에 대한 세부 정보를 가져옵니다. 다음은 이 요청의 응답 예입니다.
{
"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"
}
실행 출력 가져오기
단일 태스크 형식 작업의 경우, 작업 API의 실행에 대한 출력 가져오기 작업(GET /jobs/runs/get-output)의 응답을 처리하려면 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 경우, 실행 출력은 개별 태스크에 대해서만 제공되므로 부모에 대해 Runs get output을 호출하면 오류가 발생합니다. 다중 태스크 형식 작업의 출력 및 메타데이터를 가져오려면 다음을 수행합니다.
- 실행에 대한 출력 가져오기 요청을 호출합니다.
- 응답의 자식
run_id필드를 반복 확인합니다. - 자식
run_id값을 사용하여Runs get output을 호출합니다.
실행 나열
단일 태스크 형식 작업의 경우, 작업의 실행 나열하기 작업(GET /jobs/runs/list)의 응답을 처리하려면 클라이언트를 변경할 필요가 없습니다.
다중 태스크 형식 작업의 경우, 빈 tasks 배열이 반환됩니다. run_id를 작업 실행 가져오기 작업(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
}