Apa itu referensi nilai dinamis?

Artikel
10/05/2024

Referensi nilai dinamis menjelaskan kumpulan variabel yang tersedia saat mengonfigurasi pekerjaan dan tugas. Gunakan referensi nilai dinamis untuk mengonfigurasi pernyataan kondisional untuk tugas atau meneruskan informasi sebagai parameter atau argumen.

Referensi nilai dinamis mencakup informasi seperti:

Nilai yang dikonfigurasi untuk pekerjaan, termasuk nama pekerjaan, nama tugas, dan jenis pemicu.
Metadata yang dihasilkan tentang pekerjaan, termasuk ID pekerjaan, ID eksekusi, dan waktu mulai eksekusi pekerjaan.
Informasi tentang berapa banyak upaya perbaikan yang telah dilakukan pekerjaan atau mencoba kembali tugas yang telah dijalankan.
Status hasil untuk tugas tertentu.
Nilai yang dikonfigurasi menggunakan parameter pekerjaan, parameter tugas, atau diatur menggunakan nilai tugas.

Menggunakan referensi nilai dinamis

Gunakan referensi nilai dinamis saat mengonfigurasi pekerjaan atau tugas. Anda tidak dapat langsung mereferensikan referensi nilai dinamis dari aset yang dikonfigurasi menggunakan tugas seperti notebook, kueri, atau JAR. Referensi nilai dinamis harus ditentukan menggunakan parameter atau bidang yang meneruskan konteks ke dalam tugas.

Referensi nilai dinamis menggunakan kurung kurawal ganda ({{ }}). Saat pekerjaan atau tugas berjalan, string literal menggantikan referensi nilai dinamis. Misalnya, jika Anda mengonfigurasi pasangan kunci-nilai berikut sebagai parameter tugas:

{"job_run_id": "job_{{job.run_id}}"}

Jika ID eksekusi Anda adalah 550315892394120, nilai untuk job_run_id dievaluasi ke job_550315892394120.

Catatan

Konten kurung kurawal ganda tidak dievaluasi sebagai ekspresi. Anda tidak dapat menjalankan operasi atau fungsi dalam kurung kurawal ganda.

Pengidentifikasi nilai yang disediakan pengguna mendukung karakter alfanumerik dan garis bawah. Kunci escape yang berisi karakter khusus dengan mengelilingi pengidentifikasi dengan backtick (` `).

Kesalahan sintaks, termasuk nilai referensi dinamis yang tidak ada dan kurung kurawal yang hilang, diabaikan secara diam-diam dan diperlakukan sebagai string harfiah. Pesan kesalahan ditampilkan jika Anda memberikan referensi yang tidak valid milik namespace layanan yang diketahui, misalnya, {{job.notebook_url}}.

Menggunakan referensi nilai dinamis di antarmuka pengguna pekerjaan

Bidang yang menerima referensi nilai dinamis menyediakan pintasan untuk menyisipkan referensi nilai dinamis yang tersedia. Klik { } untuk melihat daftar ini dan menyisipkannya ke bidang yang disediakan.

Catatan

UI tidak menyelesaikan kunci secara otomatis untuk mereferensikan nilai tugas.

Banyak bidang yang menerima referensi nilai dinamis memerlukan pemformatan tambahan untuk menggunakannya dengan benar. Lihat Mengonfigurasi parameter tugas.

Menggunakan referensi nilai dinamis dalam JSON pekerjaan

Gunakan {{ }} sintaks untuk menggunakan nilai dinamis dalam definisi JSON pekerjaan yang digunakan oleh Databricks CLI dan REST API.

Parameter pekerjaan dan tugas memiliki sintaks yang berbeda, dan sintaks parameter tugas bervariasi menurut jenis tugas.

Contoh berikut menunjukkan sintaks JSON parsial untuk mengonfigurasi parameter pekerjaan menggunakan referensi nilai dinamis:

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

Contoh berikut menunjukkan sintaks JSON parsial untuk mengonfigurasi parameter tugas buku catatan menggunakan referensi nilai dinamis:

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

Meninjau parameter untuk eksekusi pekerjaan

Setelah tugas selesai, Anda dapat melihat nilai parameter yang diselesaikan di bawah Parameter pada halaman detail eksekusi. Lihat Melihat detail pekerjaan dijalankan.

Referensi nilai yang didukung

Referensi nilai dinamis berikut ini didukung:

Referensi	Deskripsi
`{{job.id}}`	Pengidentifikasi unik yang ditetapkan untuk pekerjaan tersebut.
`{{job.name}}`	Nama pekerjaan pada saat pekerjaan dijalankan.
`{{job.run_id}}`	Pengidentifikasi unik yang ditetapkan untuk pekerjaan yang dijalankan.
`{{job.repair_count}}`	Jumlah upaya perbaikan pada pekerjaan yang dijalankan saat ini.
`{{job.start_time.<argument>}}`	Nilai berdasarkan waktu (dalam zona waktu UTC) yang dijalankan pekerjaan dimulai. Nilai yang dikembalikan didasarkan pada `argument` opsi . Lihat Opsi untuk nilai tanggal dan waktu.
`{{job.parameters.<name>}}`	Nilai parameter tingkat pekerjaan dengan kunci `<name>`.
`{{job.trigger.type}}`	Jenis pemicu pekerjaan yang dijalankan. Nilai yang mungkin adalah `periodic`, , `run_job_taskone_time`, `file_arrival`, `continuous`, dan `table`.
`{{job.trigger.file_arrival.location}}`	Jika pemicu kedatangan file dikonfigurasi untuk pekerjaan ini, nilai lokasi penyimpanan.
`{{job.trigger.time.<argument>}}`	Nilai berdasarkan waktu (dalam zona waktu UTC) yang dijalankan pekerjaan dipicu, dibulatkan ke menit terdekat untuk pekerjaan dengan jadwal cron. Nilai yang dikembalikan didasarkan pada `argument` opsi . Lihat Opsi untuk nilai tanggal dan waktu.
`{{task.name}}`	Nama tugas saat ini.
`{{task.run_id}}`	Pengidentifikasi unik dari eksekusi tugas saat ini.
`{{task.execution_count}}`	Berapa kali tugas saat ini dijalankan (termasuk percobaan ulang dan perbaikan).
`{{task.notebook_path}}`	Jalur buku catatan tugas buku catatan saat ini.
`{{tasks.<task_name>.run_id}}`	Pengidentifikasi unik yang ditetapkan ke tugas yang dijalankan untuk `<task_name>`.
`{{tasks.<task_name>.result_state}}`	Status hasil tugas `<task_name>`. Nilai yang mungkin adalah `success`, , `failed`, `canceledexcluded`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted`, dan `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	Kode kesalahan untuk tugas `<task_name>` jika terjadi kesalahan saat menjalankan tugas. Contoh nilai yang mungkin adalah `RunExecutionError`, , `ResourceNotFound`dan `UnauthorizedError`. Untuk tugas yang berhasil, ini mengevaluasi ke string kosong.
`{{tasks.<task_name>.execution_count}}`	Berapa kali tugas `<task_name>` dijalankan (termasuk percobaan ulang dan perbaikan).
`{{tasks.<task_name>.notebook_path}}`	Jalur ke buku catatan untuk tugas `<task_name>`buku catatan .
`{{tasks.<task_name>.values.<value_name>}}`	Nilai tugas dengan kunci `<value_name>` yang diatur oleh tugas `<task_name>`.
`{{workspace.id}}`	Pengidentifikasi unik yang ditetapkan ke ruang kerja.
`{{workspace.url}}`	URL ruang kerja.

Anda dapat mengatur referensi ini dengan tugas apa pun. Lihat Mengonfigurasi parameter tugas.

Anda juga dapat meneruskan parameter antar tugas dalam pekerjaan dengan nilai tugas. Lihat Menggunakan nilai tugas untuk meneruskan informasi antar tugas.

Opsi untuk nilai tanggal dan waktu

Gunakan argumen berikut untuk menentukan nilai pengembalian dari variabel parameter berbasis waktu. Semua nilai yang dikembalikan didasarkan pada tanda waktu dalam zona waktu UTC.

Argumen	Deskripsi
`iso_weekday`	Mengembalikan digit dari 1 hingga 7, yang mewakili hari dalam seminggu tanda waktu.
`is_weekday`	Mengembalikan `true` jika tanda waktu berada pada hari kerja.
`iso_date`	Mengembalikan tanggal dalam format ISO.
`iso_datetime`	Mengembalikan tanggal dan waktu dalam format ISO.
`year`	Mengembalikan bagian tahun dari tanda waktu.
`month`	Mengembalikan bagian bulan dari tanda waktu.
`day`	Mengembalikan bagian hari dari tanda waktu.
`hour`	Mengembalikan bagian jam dari tanda waktu.
`minute`	Mengembalikan bagian menit dari tanda waktu.
`second`	Mengembalikan bagian kedua dari tanda waktu.
`timestamp_ms`	Mengembalikan tanda waktu dalam milidetik.

Referensi nilai dinamis yang tidak digunakan lagi

Referensi nilai dinamis berikut tidak digunakan lagi. Referensi penggantian yang direkomendasikan disertakan dalam deskripsi setiap variabel.

Variabel	Deskripsi
`{{job_id}}`	Pengidentifikasi unik yang ditetapkan ke pekerjaan. Gunakan `job.id` sebagai gantinya.
`{{run_id}}`	Pengidentifikasi unik yang ditetapkan ke eksekusi tugas. Gunakan `task.run_id` sebagai gantinya.
`{{start_date}}`	Tanggal eksekusi tugas dimulai. Formatnya adalah yyyy-MM-dd dalam zona waktu UTC. Gunakan `job.start_time.<argument>` sebagai gantinya.
`{{start_time}}`	Stempel waktu dimulainya eksekusi setelah kluster dibuat dan siap. Formatnya adalah milidetik sejak zaman UNIX dalam zona waktu UTC, seperti yang dikembalikan oleh `System.currentTimeMillis()`. Gunakan `job.start_time.<format>` sebagai gantinya.
`{{task_retry_count}}`	Jumlah percobaan kembali yang telah dicoba untuk menjalankan tugas jika upaya pertama gagal. Nilainya adalah 0 untuk upaya pertama dan bertambah dengan setiap percobaan kembali. Gunakan `task.execution_count` sebagai gantinya.
`{{parent_run_id}}`	Pengidentifikasi unik yang ditetapkan ke eksekusi pekerjaan dengan beberapa tugas. Gunakan `job.run_id` sebagai gantinya.
`{{task_key}}`	Nama unik yang ditetapkan ke tugas yang merupakan bagian dari pekerjaan dengan beberapa tugas. Gunakan `task.name` sebagai gantinya.

Bagikan melalui