Memperbarui dari Jobs API 2.1 ke 2.2

Artikel ini merinci pembaruan dan penyempurnaan fungsionalitas di api Jobs versi 2.2. Ini termasuk informasi untuk membantu Anda memperbarui klien API yang ada untuk bekerja dengan versi baru ini. Pembaruan ini termasuk pengantrean pekerjaan secara default dan dukungan yang lebih baik untuk paginasi saat tanggapan menyertakan bidang dengan lebih dari 100 elemen. Karena versi 2.2 meningkatkan dukungan yang ada untuk paginasi kumpulan hasil besar, Databricks merekomendasikan penggunaannya untuk skrip API dan klien Anda, terutama ketika respons mungkin berisi banyak tugas.

Untuk mempelajari tentang perubahan antara api versi 2.0 dan 2.1, lihat Memperbarui dari Jobs API 2.0 ke 2.1.

Selain perubahan yang disertakan dalam versi 2.1 dari Lakeflow Jobs API, versi 2.2 memiliki penyempurnaan berikut:

Pekerjaan diantrekan secara default

Antrean pekerjaan adalah fitur opsional yang mencegah pekerjaan berjalan terlewati ketika sumber daya tidak tersedia untuk dilaksanakan. Antrean pekerjaan didukung dalam versi 2.0, 2.1, dan 2.2 dari Jobs API, dengan perbedaan berikut dalam penanganan antrean default:

  • Untuk pekerjaan yang dibuat dengan Jobs API 2.2, antrean diaktifkan secara default. Anda dapat menonaktifkan antrean dengan mengatur field queue ke false di badan permintaan saat membuat atau memperbarui pekerjaan.
  • Untuk pekerjaan yang dibuat dengan versi 2.0 dan 2.1 dari Jobs API, antrian tidak aktif secara default. Dengan versi-versi ini, Anda harus mengaktifkan antrean dengan mengatur field queue ke true dalam badan permintaan saat membuat atau memperbarui pekerjaan.

Anda dapat mengaktifkan atau menonaktifkan antrean saat membuat pekerjaan, memperbarui sebagian pekerjaan, atau memperbarui semua pengaturan pekerjaan.

Lihatantrean Pekerjaan .

Dukungan untuk pemangkasan daftar tugas panjang dan daftar pelaksanaan tugas

Untuk mendukung pekerjaan dengan sejumlah besar tugas yang berjalan, Jobs API 2.2 mengubah cara set hasil besar dikembalikan untuk permintaan berikut:

Jobs API 2.2 mengubah paginasi untuk permintaan ini sebagai berikut:

  • Bidang yang mewakili daftar elemen seperti tugas, parameter, job_clusters, atau lingkungan dibatasi hingga 100 elemen per respons. Jika tersedia lebih dari 100 nilai, isi respons menyertakan bidang next_page_token yang berisi token untuk mengambil halaman hasil berikutnya.
  • Pagination ditambahkan untuk respons terhadap permintaan Get a single job dan Get a single job run. Penomoran halaman untuk respons terhadap permintaan List job dan List job runs ditambahkan dengan Jobs API 2.1.

Berikut ini adalah contoh isi respons dari permintaan Get a single job untuk pekerjaan dengan lebih dari 100 tugas. Untuk menunjukkan fungsionalitas paging berbasis token, contoh ini menghilangkan sebagian besar bidang yang disertakan dalam isi respons:

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

Untuk mengambil kumpulan hasil berikutnya, atur parameter kueri page_token dalam permintaan berikutnya ke nilai yang dikembalikan di bidang next_page_token. Misalnya, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Jika tidak ada lagi hasil yang tersedia, bidang next_page_token tidak disertakan dalam respons.

Bagian berikut memberikan detail selengkapnya tentang pembaruan untuk setiap permintaan list dan get.

Perubahan pada permintaan List jobs dan List job runs

Untuk permintaan pekerjaan Daftar dan Daftar jalannya pekerjaan , parameter has_more di tingkat akar dari objek respons telah dihapus. Sebagai gantinya, gunakan keberadaan next_page_token untuk menentukan apakah lebih banyak hasil tersedia. Jika tidak, fungsionalitas untuk mengatur halaman hasil tidak mengalami perubahan.

Untuk mencegah ukuran respons yang besar, array tasks dan job_clusters tingkat atas untuk setiap pekerjaan tidak disertakan dalam respons secara bawaan. Untuk menyertakan array ini untuk setiap pekerjaan yang disertakan dalam isi respons untuk permintaan ini, tambahkan parameter expand_tasks=true ke permintaan. Saat expand_tasks diaktifkan, maksimum 100 elemen dikembalikan dalam array tasks dan job_clusters. Jika salah satu array ini memiliki lebih dari 100 elemen, bidang has_more (tidak bingung dengan bidang has_more tingkat akar yang dihapus) di dalam objek job diatur ke true. Namun, hanya 100 elemen pertama yang dapat diakses. Anda tidak dapat mengambil tugas atau kluster tambahan setelah 100 pertama dengan permintaan Daftar pekerjaan. Untuk mengambil lebih banyak elemen, gunakan permintaan yang mengembalikan satu pekerjaan atau satu pelaksanaan pekerjaan. Pembaruan yang mendukung pemartisikan bidang respons besar dibahas di bagian berikut.

Mendapatkan satu pekerjaan

Dalam Jobs API 2.2, permintaan Get a single job untuk mengambil detail tentang satu pekerjaan sekarang mendukung paginasi pada bidang tasks dan job_clusters ketika ukuran salah satu bidang melebihi 100 elemen. Gunakan bidang next_page_token di akar objek untuk menentukan apakah ada lebih banyak hasil yang tersedia. Nilai bidang ini kemudian digunakan sebagai nilai untuk parameter kueri page_token dalam permintaan berikutnya. Bidang array dengan kurang dari 100 elemen dalam satu halaman akan kosong di halaman berikutnya.

Dapatkan satu eksekusi

Di Jobs API 2.2, permintaan untuk mendapatkan satu eksekusi agar mengambil detail tentang satu eksekusi sekarang memungkinkan pemartislaman bidang tasks dan job_clusters saat ukuran salah satu bidang melebihi 100 elemen. Gunakan bidang next_page_token di akar objek untuk menentukan apakah ada lebih banyak hasil yang tersedia. Nilai bidang ini kemudian digunakan sebagai nilai untuk parameter kueri page_token dalam permintaan berikutnya. Bidang array dengan kurang dari 100 elemen dalam satu halaman akan kosong pada halaman berikutnya.

Jobs API 2.2 juga menambahkan parameter kueri only_latest ke titik akhir ini untuk memungkinkan hanya menampilkan upaya eksekusi terbaru dalam array tasks. Ketika parameter only_latest adalah true, setiap eksekusi yang diatur ulang atau diperbaiki dihilangkan dari respons.

Saat run_id merujuk pada pelaksanaan tugas ForEach, sebuah bidang bernama iterations terdapat dalam hasil respons. Bidang iterations adalah array yang berisi detail untuk semua tugas tertanam dari tugas ForEach dan memiliki unsur berikut:

  • Skema setiap objek dalam array iterations sama dengan objek dalam array tasks.
  • Jika parameter query only_latest disetel ke true, hanya percobaan eksekusi terbaru yang disertakan dalam array iterations.
  • Penomoran halaman diterapkan ke array iterations alih-alih array tasks.
  • Array tasks masih disertakan dalam respons dan mencakup pelaksanaan tugas ForEach.

Untuk mempelajari selengkapnya tentang tugas ForEach, lihat dokumentasi tugas ForEach .

Misalnya, lihat respons berikut untuk tugas ForEach dengan beberapa bidang yang dihilangkan:

{
  "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": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}
  • Last updated on