Bagikan melalui

Memperbarui dari Jobs API 2.0 ke 2.1

  • Artikel

Anda sekarang dapat mengorkestrasikan beberapa tugas dengan Azure Databricks tugas. Artikel ini merinci perubahan pada Jobs API yang mendukung pekerjaan dengan beberapa tugas dan memiliki panduan untuk membantu Anda dalam update klien API yang ada agar dapat bekerja dengan fitur baru ini.

Databricks merekomendasikan Jobs API 2.1 untuk skrip API dan klien Anda, terutama saat menggunakan pekerjaan dengan beberapa tugas.

Artikel ini mengacu pada pekerjaan yang ditentukan dengan satu tugas sebagai format tugas tunggal dan pekerjaan yang ditentukan dengan beberapa tugas sebagai format multi-tugas .

Jobs API 2.0 dan 2.1 sekarang mendukung permintaan update. Gunakan permintaan update untuk mengubah pekerjaan yang ada alih-alih permintaan reset untuk meminimalkan perubahan antara pekerjaan format tugas tunggal dan pekerjaan format multi-tugas.

Perubahan API

API Pekerjaan sekarang mendefinisikan objek TaskSettings untuk menangkap pengaturan untuk setiap tugas dalam suatu pekerjaan. Untuk pekerjaan dengan format multi-tugas, elemen tasks berupa array dari struktur data TaskSettings disertakan dalam objek JobSettings. Beberapa bidang yang sebelumnya menjadi bagian dari JobSettings sekarang menjadi bagian dari pengaturan tugas untuk pekerjaan format multitasking. JobSettings juga diperbarui untuk menyertakan bidang format. Bidang format menunjukkan format pekerjaan dan adalah nilai STRING dari set hingga SINGLE_TASK atau MULTI_TASK.

Anda perlu update klien API yang ada untuk perubahan ini pada JobSettings untuk tugas multi-format. Lihat panduan klien API untuk informasi selengkapnya tentang perubahan yang diperlukan.

Jobs API 2.1 mendukung format multi-tugas. Semua permintaan API 2.1 harus sesuai dengan format ini, dan respons disusun dalam format ini.

Jobs API 2.0 diperbarui dengan bidang tambahan untuk mendukung pekerjaan format multi-tugas. Kecuali where dicatat, contoh dalam dokumen ini menggunakan API 2.0. Namun, Databricks merekomendasikan API 2.1 untuk skrip API dan klien baru dan yang sudah ada.

Contoh dokumen JSON yang menggambarkan format pekerjaan beberapa tugas untuk API 2.0 dan 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"
}

Jobs API 2.1 mendukung konfigurasi kluster tingkat tugas atau satu atau beberapa kluster pekerjaan bersama:

  • Kluster tingkat tugas dibuat dan dimulai ketika tugas dimulai dan dihentikan saat tugas selesai.
  • Kluster pekerjaan bersama memungkinkan beberapa tugas dalam pekerjaan yang sama untuk menggunakan kluster. Kluster dibuat dan dimulai ketika tugas pertama menggunakan kluster dimulai dan dihentikan setelah tugas terakhir menggunakan kluster selesai. Kluster pekerjaan bersama tidak dihentikan saat diam tetapi berakhir hanya setelah semua tugas yang menggunakannya selesai. Beberapa tugas non-dependen yang berbagi kluster dapat dimulai pada saat yang sama. Jika kluster pekerjaan bersama gagal atau dihentikan sebelum semua tugas selesai, kluster baru dibuat.

Untuk mengonfigurasi kluster pekerjaan bersama, sertakan array JobCluster di objek JobSettings. Anda dapat menentukan maksimum 100 kluster per pekerjaan. Berikut ini adalah contoh respons API 2.1 untuk pekerjaan yang dikonfigurasi dengan dua kluster bersama:

Nota

Jika tugas memiliki dependensi pustaka, Anda harus mengonfigurasi pustaka di pengaturan bidang task; pustaka tidak dapat dikonfigurasi dalam konfigurasi kluster pekerjaan bersama. Dalam contoh berikut, bidang libraries dalam konfigurasi tugas ingest_orders menunjukkan spesifikasi dependensi pustaka.

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

Untuk pekerjaan format tugas tunggal, struktur data JobSettings tetap tidak berubah kecuali untuk penambahan bidang format. Tidak ada array TaskSettings yang disertakan, dan pengaturan tugas tetap ditentukan di tingkat atas struktur data JobSettings. Anda tidak perlu membuat perubahan pada klien API yang ada untuk memproses pekerjaan format tugas tunggal.

Contoh dokumen JSON yang mewakili pekerjaan format tugas tunggal untuk 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"
}

panduan klien API

Bagian ini menyediakan panduan, contoh, dan perubahan yang diperlukan untuk panggilan API yang terpengaruh oleh fitur format multi-tugas baru.

Di bagian ini:

Buat

Untuk membuat pekerjaan dengan format satu tugas melalui operasi Membuat pekerjaan baru (POST /jobs/create) di Jobs API, Anda tidak perlu mengubah klien yang sudah ada.

Untuk membuat pekerjaan format multi-tugas, gunakan bidang tasks di JobSettings untuk menentukan pengaturan untuk setiap tugas. Contoh berikut membuat proyek dengan dua tugas dalam buku catatan. Contoh ini untuk API 2.0 dan 2.1:

Nota

Maksimal 100 tugas dapat ditentukan per pekerjaan.

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

Runs mengirimkan

Untuk mengirimkan eksekusi satu kali untuk pekerjaan format tugas tunggal dengan operasi "Membuat dan memicu eksekusi satu kali" (POST /runs/submit) dalam API Jobs, Anda tidak perlu mengubah klien yang ada.

Untuk mengirimkan pelaksanaan satu kali dari tugas format multi-tugas, gunakan bidang tasks di JobSettings untuk menentukan setelan setiap tugas, termasuk kluster. Kluster harus set pada tingkat tugas saat mengirimkan pekerjaan format multi-tugas karena permintaan runs submit tidak mendukung kluster pekerjaan bersama. Lihat Buat untuk contoh JobSettings menentukan berbagai tugas.

Update

Untuk update pekerjaan format tugas tunggal dengan Sebagian update operasi pekerjaan (POST /jobs/update) di JOBS API, Anda tidak perlu mengubah klien yang ada.

Untuk update pengaturan pekerjaan format multi-tugas, Anda harus menggunakan bidang task_key unik untuk mengidentifikasi pengaturan task baru. Lihat Buat untuk contoh JobSettings menentukan berbagai tugas.

Reset

Untuk menimpa pengaturan dari pekerjaan dengan format tugas tunggal menggunakan operasi Timpa semua pengaturan untuk pekerjaan (POST /jobs/reset) di Jobs API, Anda tidak perlu mengubah klien yang sudah ada.

Untuk menggantikan pengaturan pekerjaan format multi-tugas, tentukan struktur data JobSettings, dengan array struktur data TaskSettings. Lihat Buat untuk contoh JobSettings menentukan berbagai tugas.

Gunakan Update untuk mengubah bidang individual tanpa beralih dari format tugas tunggal ke multi-tugas.

List

Untuk pekerjaan format tugas tunggal, tidak ada perubahan klien yang diperlukan untuk memproses respons dari List semua pekerjaan operasi (GET /jobs/list) di Jobs API.

Untuk pekerjaan format multi-tugas, sebagian besar pengaturan ditentukan pada tingkat tugas dan bukan tingkat pekerjaan. Konfigurasi kluster mungkin set pada tingkat tugas atau pekerjaan. Untuk mengatur klien agar dapat mengakses pengaturan kluster atau tugas untuk pekerjaan dengan format multi-tugas yang dikembalikan dalam struktur Job:

  • Uraikan bidang job_id untuk pekerjaan format multi-tugas.
  • Teruskan job_id ke Get operasi pekerjaan (GET /jobs/get) di Jobs API untuk mengambil detail pekerjaan. Lihat Get untuk contoh respons dari panggilan API Get dalam pekerjaan dengan format multi-tugas.

Contoh berikut menunjukkan respons yang berisi tugas tunggal dan tugas multi-tugas. Contoh ini untuk 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

Untuk pekerjaan dengan format tugas tunggal, tidak ada perubahan klien yang diperlukan untuk memproses respons dari hasil operasi Get pada pekerjaan (GET /jobs/get) di Jobs API.

Pekerjaan format multi-tugas mengembalikan array struktur data task yang berisi pengaturan tugas. Jika Anda memerlukan akses ke detail tingkat tugas, Anda perlu memodifikasi klien Anda untuk melakukan iterasi melalui array tasks dan mengekstrak bidang yang diperlukan.

Berikut adalah contoh respons dari API call Get untuk pekerjaan dengan format multi-tugas. Contoh ini untuk API 2.0 dan 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"
}

Menjalankan get

Untuk pekerjaan dengan format tugas tunggal, tidak ada perubahan klien yang diperlukan untuk memproses respons dari operasi pekerjaan Get yang dijalankan (GET /jobs/runs/get) di Jobs API.

Respons untuk pekerjaan berformat multi-tugas yang dijalankan berisi array TaskSettings. Untuk mengambil hasil pelaksanaan untuk setiap tugas:

  • Lakukan iterasi dari setiap tugas.
  • Uraikan run_id untuk setiap tugas.
  • Panggil Get sebagai output dari operasi pelaksanaan (GET /jobs/runs/get-output) dengan run_id ke get detail tentang pelaksanaan untuk setiap tugas. Berikut ini adalah contoh respons dari permintaan ini:
{
  "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"
}

Menjalankan output get

Untuk pekerjaan dengan format tugas tunggal, tidak diperlukan perubahan pada klien untuk memproses tanggapan dari Get keluaran untuk operasi menjalankan (GET /jobs/runs/get-output) di JOBS API.

Untuk pekerjaan format multi-tugas, memanggil Runs get output pada eksekusi induk menghasilkan kesalahan karena output eksekusi hanya tersedia untuk tugas individual. Untuk get keluaran dan metadata dari pekerjaan berformat multi-tugas:

Menjalankan list

Untuk pekerjaan dengan format tugas tunggal, tidak perlu ada perubahan pada klien yang diperlukan untuk memproses respons dari List yang dijalankan untuk operasi pekerjaan (GET /jobs/runs/list).

Untuk pekerjaan dengan format multi-tugas, array tasks kosong akan dikembalikan. Teruskan run_id ke Get operasi eksekusi pekerjaan (GET /jobs/runs/get) untuk mengambil tugas. Berikut ini menunjukkan contoh respons dari panggilan API Runs list untuk pekerjaan format multi-tugas:

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