Parameter penjadwalan merupakan mekanisme inti dalam DataWorks untuk manajemen tugas dan konfigurasi dinamis. Parameter ini memungkinkan Anda menggunakan placeholder variabel dalam kode dan menyuntikkan nilai dinamis selama penjadwalan. Pendekatan ini mengatasi tantangan pemeliharaan tanggal yang di-hardcode pada tugas periodik serta memisahkan konfigurasi dari kode melalui hierarki parameter empat tingkat: ruang kerja, alur kerja, konteks node, dan lokal-node. Pemisahan ini secara signifikan meningkatkan fleksibilitas, kemampuan pakai ulang, dan adaptabilitas tugas di berbagai lingkungan.
Artikel ini berfokus pada sumber penetapan dan sintaks ekspresi untuk parameter penjadwalan. Sebelum membaca artikel ini, pastikan Anda telah memahami metode konfigurasi dasar yang dijelaskan dalam Konfigurasikan dan gunakan parameter penjadwalan.
Sumber parameter penjadwalan
Selain menggunakan parameter yang didefinisikan secara lokal pada suatu node, Anda juga dapat menggunakan parameter konteks, alur kerja, dan ruang kerja. Sumber-sumber ini tercantum di bawah ini berdasarkan cakupannya, dari yang paling sempit hingga paling luas.
-
Definisi lokal-node (node saat ini)
Parameter yang didefinisikan di area Scheduling Parameters pada bagian Scheduling Configuration hanya berlaku untuk node saat ini. Parameter tersebut mendukung berbagai ekspresi parameter, sebagaimana dijelaskan lebih lanjut di bawah.
-
Parameter konteks (dilewatkan antar-node)
Gunakan parameter konteks untuk menerima nilai output dari node hulu. Pendekatan ini tidak hanya meneruskan nilai, tetapi juga menetapkan dependensi antar-node. Gunakan metode ini ketika nilai parameter harus ditentukan secara dinamis berdasarkan hasil tugas hulu. Anda dapat dengan cepat menambahkan parameter konteks dengan mengklik ikon
di area penetapan parameter. Untuk informasi lebih lanjut, lihat Konfigurasikan dan gunakan parameter konteks node.
-
Parameter alur kerja (dibagikan dalam satu alur kerja)
Parameter yang didefinisikan di tingkat alur kerja tersedia untuk semua node dalam alur kerja tersebut. Anda dapat mereferensikannya langsung menggunakan format
${workflow.Parameter name}. Aturan ekspresi parameter yang dijelaskan dalam artikel ini juga berlaku untuk parameter alur kerja.
-
Parameter ruang kerja (dibagikan dalam satu ruang kerja)
Parameter ruang kerja adalah parameter global yang didefinisikan di tingkat ruang kerja, sehingga tersedia untuk semua node dalam ruang kerja tersebut. Penggunaan paling umum adalah untuk membedakan konfigurasi antara lingkungan pengembangan dan produksi. Misalnya, Anda dapat mendefinisikan parameter bernama
db_namedengan nilaidb_devdi lingkungan pengembangan dandb_proddi lingkungan produksi. Saat menetapkan nilai parameter penjadwalan, Anda dapat langsung memilih Workspace Parameters. Untuk detailnya, lihat Gunakan parameter ruang kerja.
Ekspresi parameter
Parameter penjadwalan menetapkan logika penetapan dengan menentukan nama parameter dan nilai parameter. Nilai parameter mendukung berbagai bentuk, termasuk parameter waktu, parameter sistem bawaan, dan konstanta. Setelah parameter didefinisikan, Anda dapat mereferensikannya dalam kode menggunakan format ${nama parameter}.
-
Parameter waktu kustom: Seperti
${...}dan$[...], yang memungkinkan Anda mentransformasi nilai berdasarkan dua referensi waktu (business date dan scheduled time). Untuk detailnya, lihat Parameter waktu. -
Parameter sistem bawaan: Seperti $bizdate, $bizmonth, dan $jobid, yang dapat digunakan untuk mengambil business date, business month, ID alur kerja, dan lainnya. Nilainya tidak terbatas pada data terkait waktu. Untuk detailnya, lihat Parameter penjadwalan bawaan.
-
Konstanta: Seperti '
123','abc', dan sebagainya.
Karakter khusus yang didukung: · ~ ! @ # $ % ^ & * ( ) - = _ + dan spasi. Jika nilai parameter mengandung spasi, sertakan nilai tersebut dalam tanda petik tunggal, contohnya: 'xxx xxx'.
Di antara jenis-jenis tersebut, parameter waktu merupakan kasus penggunaan utama untuk parameter penjadwalan. Parameter ini digunakan untuk mengganti berbagai string waktu secara dinamis saat tugas dijalankan.
Parameter waktu
Konsep inti: Referensi waktu
Semua parameter waktu dinamis dalam DataWorks didasarkan pada dua referensi waktu inti berikut.
|
Konsep |
Definisi |
Nilai parameter |
Format kustom |
Presisi waktu |
|
Business date |
Umumnya merujuk pada hari sebelum tanggal jadwal eksekusi tugas. Dalam skenario komputasi batch T+1, ini merepresentasikan tanggal saat data bisnis dihasilkan. Misalnya, jika Anda menjalankan tugas hari ini untuk menghitung pendapatan hari sebelumnya, maka hari sebelumnya — tanggal transaksi terjadi — adalah business date. |
|
|
Tahun, bulan, hari |
|
Scheduled time |
Merujuk pada waktu yang dikonfigurasi di bagian Scheduling Settings suatu node melalui cron expression. Saat runtime tugas, nilai ini diganti dengan hari ketika instans tugas dijadwalkan berjalan. Nilainya presisi hingga detik dan tidak bergantung pada waktu eksekusi aktual. Waktu ini merepresentasikan waktu eksekusi yang diharapkan dari tugas, yang mungkin tidak persis sama dengan waktu mulai aktual. Waktu mulai aktual dipengaruhi oleh berbagai faktor. |
|
|
Tahun, bulan, hari, jam, menit, detik |
Rangkuman:
-
Business date ≈ kemarin (tanggal data) =
$bizdate=${yyyymmdd} -
Scheduled time ≈ hari ini (waktu tugas berjalan) =
$cyctime=$[yyyymmddhh24miss]
Tugas T+1 tipikal bekerja sebagai berikut: pada dini hari hari ini (scheduled time), sebuah tugas dipicu untuk memproses data kemarin (business date).
Berikut ini menunjukkan definisi parameter untuk $bizdate dan ${yyyymmdd}, $cyctime dan $[yyyymmddhh24miss], beserta hasil pratinjau mereka ketika business date adalah 2025-10-16.
|
|
|
Jika nilai kembali default dari parameter waktu dasar tidak memenuhi kebutuhan Anda, Anda dapat menyesuaikan parameter waktu dengan menggunakan ${...} dan $[...]. Parameter waktu kustom diturunkan dengan mentransformasi dua referensi waktu dasar tersebut. Metode berikut didukung:
Saat menetapkan nilai ke parameter penjadwalan menggunakan ekspresi kustom, pastikan untuk membedakan antara dua format kurung: {...} dan [...]. Kedua format tersebut menggunakan referensi waktu dasar yang berbeda dan menghasilkan nilai yang sama sekali berbeda. Kesalahan penggunaan dapat menyebabkan error data produksi.
Parameter waktu kustom
DataWorks mendukung penggunaan ${...} dan $[...] untuk mengambil business date dan scheduled time, secara berturut-turut. Jenis transformasi berikut memungkinkan Anda memodifikasi nilai waktu secara fleksibel sesuai kebutuhan bisnis. Contoh berikut mengasumsikan penjadwalan harian dengan scheduled time pukul 02:30:45 dan business date 20251031. Referensi waktu dasarnya adalah:
-
Business date: ${yyyymmdd}, misalnya, 20251031.
-
Scheduled time: $[yyyymmddhh24miss], misalnya, 20251101023045.
PentingScheduled time adalah waktu penjadwalan yang telah ditetapkan, yang bersifat tetap saat instans tugas dibuat. Jika instans tugas tertunda karena kendala sumber daya atau status node hulu, scheduled time tidak berubah mengikuti waktu eksekusi aktual instans tersebut.
${...} vs. $[...] perbedaan utama
Pertama, pahami perbedaan utama antara keduanya. ${...} dan $[...] berbeda secara mendasar dalam referensi waktu dan kemampuan perhitungannya. Menggabungkan kedua format ini dapat menyebabkan error data.
|
Dimensi |
|
|
|
Referensi waktu |
Business date (T-1) |
Scheduled time (T) |
|
Presisi waktu |
Hari (tahun, bulan, hari) |
Detik (tahun, bulan, hari, jam, menit, detik) |
|
Kemampuan perhitungan offset |
Mendukung perhitungan offset untuk tahun, bulan, minggu, dan hari. |
Mendukung perhitungan offset untuk hari, jam, dan menit. |
|
Batasan utama |
Tidak mendukung pemformatan atau perhitungan offset untuk satuan waktu yang lebih kecil seperti jam, menit, dan detik. |
Tidak mendukung penggunaan sintaks |
|
Setara default |
|
|
Pemformatan waktu
Gunakan tanda kurung kurawal ${...} atau tanda kurung siku $[...], dikombinasikan dengan yyyy, yy, mm, dan dd dalam kombinasi kustom untuk menghasilkan parameter waktu yang mengambil tanggal beberapa tahun, bulan, atau hari sebelum atau sesudah business date.
|
Kode |
Deskripsi |
|
|
||
|
Tugas |
Hasil |
Tugas |
Hasil |
||
|
|
Tahun 4 digit |
|
|
|
|
|
|
Bulan 2 digit |
|
|
|
|
|
|
Hari 2 digit |
|
|
|
|
|
|
Jam dalam format 24 jam |
Tidak didukung (presisi tingkat hari) |
- |
|
|
|
|
Jam dalam format 12 jam |
- |
|
|
|
|
|
Menit |
- |
|
|
|
|
|
Kedua |
- |
|
|
|
|
|
Tahun dan bulan |
|
|
|
|
|
|
Diformat dengan tanda hubung sebagai pembatas |
|
|
|
|
|
|
Diformat dengan tanda hubung, termasuk jam, menit, dan detik |
Tidak didukung (presisi tingkat hari) |
- |
Untuk metode yang didukung, lihat Penggabungan string: Metode 2. |
|
Perhitungan offset
Perhitungan offset merupakan inti dari parameter dinamis. Anda dapat menambahkan atau mengurangi nilai dari business date atau scheduled time untuk mengambil tanggal dan waktu N tahun, bulan, hari, jam, atau menit sebelum atau sesudah waktu dasar (jam dan menit hanya didukung untuk scheduled time). ${...} dan $[...] mendukung rentang berbeda karena presisi referensi waktu dasar yang berbeda.
-
${...}perhitungan offset-
Kemampuan inti: Mendukung offset bilangan bulat untuk tahun, bulan, minggu, dan hari.
PentingTidak mendukung perhitungan offset jam atau menit. Ekspresi seperti ${yyyy-mm-dd-1/24} tidak didukung.
-
Sintaks:
${<format waktu><±N>}, di mana N sesuai dengan satuan terkecil dalam format waktu tersebut. Misalnya, jika formatnya yyyymm, N dalam satuan bulan. Jika formatnya yyyymmdd, N dalam satuan hari.Date offset period
Offset unit
Syntax
Example
N years before/after
Year
${yyyy±N}atau${yy±N}Ambil tahun sebelumnya:
${yyyy-1}N months before/after
Month
${yyyymm±N}
Ambil bulan sebelumnya:
${yyyymm-1}N weeks before/after
Week
${yyyymmdd±7*N}
Ambil minggu sebelumnya:
${yyyymmdd-7*1}N days before/after
Day
${yyyymmdd±N}
Ambil hari sebelum kemarin:
${yyyymmdd-1}
-
-
$[...]perhitungan offset-
Kemampuan inti: Mendukung offset pecahan untuk hari, jam, dan menit.
Penting$[...]tidak dapat menggunakan format waktu$[yyyy-N]atau$[mm-N]untuk mengambil tanggal N tahun atau N bulan lalu. Untuk melakukan perhitungan offset tahun atau bulan, gunakan fungsiadd_months. -
Sintaks:
$[<format waktu><±N>], di mana N/24 digunakan untuk offset jam dan N/24/60 digunakan untuk offset menit. N adalah jumlah jam atau menit yang di-offset.Kebutuhan
Satuan offset
Sintaks
Contoh
N tahun sebelum/setelah
Tahun
$[add_months(yyyymmdd,12*N)](N tahun setelah)$[add_months(yyyymmdd,-12*N)](N tahun sebelum)Ambil tahun sebelumnya:
$[add_months(yyyymmdd,-12)]N bulan sebelum/setelah
Bulan
$[add_months(yyyymmdd,N)](N bulan setelah)$[add_months(yyyymmdd,-N)](N bulan sebelum)Ambil bulan sebelumnya:
$[add_months(yyyymmdd,-1)]N minggu sebelum/setelah
Minggu
$[yyyymmdd±7*N]Ambil minggu sebelumnya:
$[yyyymmdd±7*1]N hari sebelum/setelah
Hari
$[yyyymmdd±N]Ambil kemarin:
$[yyyymmdd-1]N jam sebelum/setelah
Jam
Anda dapat mengambil data waktu ini dengan metode berikut:
-
$[hh24miss±N/24],$[hh24±N/24] -
$[format waktu kustom±N/24]
Ambil jam sebelumnya menggunakan berbagai format waktu:
-
Ambil bulan:
$[mm-1/24]. -
Ambil tahun:
$[yyyy-1/24]. -
Ambil tahun dan bulan:
$[yyyymm-1/24]. -
Ambil tahun, bulan, dan hari:
$[yyyymmdd-1/24]. -
Ambil hari sebelumnya dan jam sebelumnya:
$[yyyymmdd-1-1/24]
N menit sebelum/setelah
Menit
Anda dapat mengambil data waktu ini dengan metode berikut:
-
$[hh24miss±N/24/60] -
$[yyyymmddhh24miss±N/24/60] -
$[mi±N/24/60] -
$[format waktu kustom±N/24/60]
Ambil 15 menit sebelum scheduled time menggunakan berbagai format waktu:
-
$[yyyy-15/24/60] -
$[yyyymm-15/24/60] -
$[yyyymmdd-15/24/60] -
$[hh24-15/24/60] -
$[mi-15/24/60]
Offset gabungan kompleks
Hari + Jam
$[yyyymmdd±N±M/24], di mana N adalah offset hari dan M adalah offset jam.Contoh: Ambil satu hari sebelum dan satu jam sebelum →
$[yyyymmdd-1-1/24]Catatan-
Saat melakukan perhitungan offset jam atau menit, mungkin terjadi perlintasan batas hari. Untuk informasi tentang cara parameter menangani perlintasan batas hari, lihat Tangani perlintasan batas hari pada parameter waktu.
-
Saat melakukan perhitungan offset bulan pada tanggal akhir bulan, jika bulan tujuan tidak memiliki hari yang sesuai, hasilnya secara otomatis disesuaikan ke hari terakhir bulan tersebut. Misalnya, jika tanggal saat ini adalah 2025-03-31 dan diterapkan offset mundur 1 bulan, hasilnya adalah 2025-02-28 karena Februari tidak memiliki tanggal 31.
-
-
Transformasi sekunder menggunakan fungsi engine
Ketika pemformatan dan offset bawaan dari parameter penjadwalan tidak dapat langsung menghasilkan nilai yang diinginkan (seperti hari terakhir bulan sebelumnya), Anda dapat menggunakan fungsi yang ada di compute engine node target atau menggunakan node penetapan untuk melakukan transformasi sekunder pada parameter waktu saat memanggilnya.
Untuk informasi lebih lanjut, lihat Lakukan transformasi sekunder menggunakan fungsi engine.
Penggabungan string
Gunakan metode ini untuk membuat string tanggal dengan pola yang tidak didukung oleh sintaks bawaan. Metode ini menggabungkan bagian tanggal yang dihasilkan oleh parameter penjadwalan dengan string konstanta tetap.
Contoh 1: Dapatkan secara dinamis hari pertama setiap bulan.
-
Skenario: Terlepas dari hari eksekusi tugas, Anda memerlukan string yang merepresentasikan hari pertama bulan berjalan dalam format
yyyymm01. -
Implementasi:
-
Ambil tahun dan bulan: Gunakan
${yyyymm}untuk mendapatkan tahun dan bulan dari business date saat ini (misalnya, jika business date adalah20231027, hasilnya adalah202310). -
Gabungkan konstanta: Gabungkan tahun dan bulan yang diekstrak dengan string
'01'. -
Pemanggilan parameter:
first_day_of_month=${yyyymm}01
-
-
Hasil: Saat tugas dijalankan,
${first_day_of_month}diganti dengan20231001.
Contoh 2: Dapatkan waktu dalam format yyyy-mm-dd hh24:mi:ss.
-
Skenario: Dapatkan string waktu dalam format
yyyy-mm-dd hh24:mi:ss, seperti2023-11-01 02:30:45. -
Implementasi:
-
Definisikan dua parameter:
datetime1dandatetime2, dan tetapkan sebagaidatetime1=$[yyyy-mm-dd]dandatetime2=$[hh24:mi:ss-1/24/60]. -
Gabungkan parameter: Gabungkan
datetime1dandatetime2dengan spasi. -
Pemanggilan parameter: pt=
${datetime1}${datetime2}.
-
-
Hasil: Saat tugas dijalankan,
${datetime1}${datetime2}diganti dengan2023-11-01 02:30:45.
Parameter penjadwalan bawaan
DataWorks mendukung parameter sistem bawaan berikut, yang dapat digunakan sebagai nilai parameter penjadwalan. Namun, pendekatan ini kurang fleksibel karena format waktunya tetap. Kami menyarankan Anda menggunakan parameter waktu kustom, yang mendukung transformasi fleksibel.
|
Parameter bawaan |
Definisi |
|
$bizdate |
Business date, dalam format Parameter ini banyak digunakan. Dalam penjadwalan harian, business date secara default adalah hari sebelum tanggal eksekusi tugas yang diharapkan. |
|
$cyctime |
Waktu penjadwalan tugas, dalam format |
|
$gmtdate |
Tanggal saat ini, dalam format Parameter ini secara default adalah tanggal saat ini. Saat Anda melakukan pengisian ulang data, tanggal input adalah |
|
$bizmonth |
Business month, dalam format
|
|
$jobid |
ID alur kerja tempat tugas tersebut berada. |
|
$nodeid |
ID node. |
|
$taskid |
ID instans yang dihasilkan oleh node. |
Lampiran
Penggantian parameter selama pengisian ulang data
Setelah tugas diajukan ke Operation Center, Anda dapat mengisi ulang data untuk menghasilkan dan menjalankan instans tugas historis secara batch dalam rentang tanggal tertentu untuk perbaikan data, pengisian ulang, atau analisis retrospektif.
-
Business date ($bizdate): Selama pengisian ulang data, business date yang Anda pilih konsisten dengan hasil penggantian $bizdate. Jika parameter penjadwalan menggunakan format kustom
${...}, waktu dasarnya adalah tanggal yang dipilih, yang kemudian ditransformasi sesuai ekspresi waktu yang ditentukan. -
Scheduled time ($cyctime): Selama pengisian ulang data, hasil penggantian $cyctime adalah
business date yang dipilih + 1hari.Misalnya, jika business date yang dipilih untuk pengisian ulang data adalah
20250315, maka selama pengisian ulang data, hasil penggantian parameter$cyctimeadalah20250316000000. Jika parameter penjadwalan menggunakan format$[...], waktu dasarnya adalah business date yang dipilih + 1, yang kemudian ditransformasi sesuai ekspresi waktu yang ditentukan.
Hubungan antara parameter penjadwalan, business date, scheduled time, dan waktu eksekusi aktual
|
Jenis hubungan |
Deskripsi dan contoh |
|
Hubungan antara parameter penjadwalan dan waktu eksekusi aktual. |
Nilai penggantian parameter penjadwalan ditentukan saat instans dibuat. Oleh karena itu, nilai penggantian tidak berubah mengikuti waktu eksekusi aktual instans tersebut. |
|
Hubungan antara parameter penjadwalan dan waktu terjadwal |
Saat parameter penjadwalan diatur ke Misalnya, jika node saat ini adalah node berjadwal per jam dengan rentang waktu jadwal
|
|
Hubungan antara parameter penjadwalan, business date, dan scheduled time. |
|
Catatan daylight saving time
DataWorks memastikan tugas berjalan dengan benar pada hari dimulai dan berakhirnya daylight saving time (DST). Untuk detail tentang cara produk menangani transisi DST, lihat Daylight saving time. Untuk menghindari kompleksitas tambahan akibat transisi DST pada eksekusi tugas Anda, kami menyarankan Anda meninjau dokumen ini jika wilayah Anda menerapkan DST.
Perbandingan nilai parameter kustom
Bagian ini menggunakan node ODPS SQL sebagai contoh. Dengan asumsi scheduled time tugas adalah 20 Juli 2025 pukul 10:30:00, tabel berikut menunjukkan konfigurasi nilai waktu untuk parameter ${…} dan $[…].
|
Nilai waktu |
Parameter ${…} |
$[…] parameter |
|
Ambil tahun: 2025 |
|
|
|
Ambil tahun: 25 |
|
|
|
Ambil tahun: 2024 |
|
|
|
Ambil bulan: 07 |
|
|
|
Ambil hari: 20 |
|
|
|
Ambil tanggal: 20 Juni 2025 |
Penting Pendekatan ini memerlukan pertimbangan jumlah hari tiap bulan dan tidak disarankan. Kami menyarankan Anda menggunakan format |
|
|
Ambil tanggal: 19 Juli 2025 |
|
|
|
Ambil tanggal: 20 Juli 2024 |
Penting Pendekatan ini memerlukan pertimbangan tahun kabisat dan tidak disarankan. Kami menyarankan Anda menggunakan format |
|
|
Ambil waktu: 10:30:00 |
Tidak didukung |
|
|
Ambil waktu: 2025-07-20 10:30:00 |
Tidak didukung |
|
|
Ambil waktu: 2025-07-20 10:29:00 |
Tidak didukung |
|
|
Ambil waktu: 2025-07-20 09:30:00 |
Tidak didukung |
|
|
Ambil waktu hari sebelumnya, presisi hingga detik, tanpa spasi antara tanggal dan waktu: 2025071910:30:00 |
Tidak didukung |
|
|
Ambil waktu hari sebelumnya, presisi hingga detik, dengan spasi antara tanggal dan waktu: 20250719 10:30:00 |
Tidak didukung |
|

