Menjadwalkan tugas dengan cron.yaml

Layanan Cron App Engine memungkinkan Anda mengonfigurasi tugas terjadwal secara berkala yang beroperasi pada waktu yang ditentukan atau interval teratur. Tugas ini umumnya dikenal sebagai cron job. Cron job ini dipicu secara otomatis oleh Layanan Cron App Engine. Misalnya, Anda dapat menggunakannya untuk mengirim email laporan setiap hari, memperbarui beberapa data yang di-cache setiap 10 menit, atau memperbarui beberapa informasi ringkasan satu kali setiap jam.

Cron job membuat permintaan GET HTTP terjadwal ke endpoint yang ditentukan dalam aplikasi yang sama tempat cron job dikonfigurasi. Pengendali untuk endpoint tersebut akan mengeksekusi logika saat dipanggil.

Layanan Cron App Engine tidak dapat digunakan untuk memanggil endpoint web di luar aplikasi host App Engine. Layanan ini tidak dapat digunakan untuk memanggil endpoint App Engine dari aplikasi lain selain aplikasi host.

Permintaan cron job tunduk pada batas yang sama dengan permintaan HTTP lainnya. Aplikasi gratis dapat memiliki hingga 20 tugas terjadwal. Aplikasi berbayar dapat memiliki hingga 250 tugas terjadwal.

Untuk men-deploy atau memperbarui jadwal, akun Anda memerlukan salah satu peran Identity and Access Management berikut:

Anda dapat menetapkan izin pada halaman IAM di konsol Google Cloud.

Tentang file konfigurasi cron

Untuk semua runtime kecuali Java, file cron.yaml dalam direktori utama aplikasi Anda (beserta app.yaml) akan mengonfigurasi tugas terjadwal untuk aplikasi Anda.

Untuk Java, file cron.yaml dalam direktori WEB-INF aplikasi Anda (beserta app.yaml) akan mengonfigurasi tugas terjadwal untuk aplikasi Anda.

Berikut adalah contoh file cron.yaml:

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

File cron.yaml menggunakan sintaksis YAML dan terdiri dari definisi untuk setiap tugas cron Anda. Definisi tugas harus memiliki url dan schedule. Anda juga dapat menentukan description, timezone, target, dan retry_parameters secara opsional:

url
Wajib diisi. URL di aplikasi yang Anda pilih menjadi tujuan saat layanan Cron mengirimkan permintaan tugas.
schedule
Wajib diisi. Menentukan jadwal kapan Anda ingin tugas dijalankan, lihat sintaksis di bawah ini.
description
Opsional. Mendeskripsikan cron job Anda, yang dapat dilihat dari dalam konsol Google Cloud.
timezone
Opsional. Nama zona waktu, atau "zoneinfo", yang ingin Anda gunakan untuk jadwal tugas. Jika Anda tidak menentukan zona waktu, jadwal akan menggunakan UTC, yang juga disebut sebagai GMT.
target
Opsional. Nama layanan tertentu di aplikasi Anda. Saat target ditentukan, layanan Cron akan menargetkan permintaan tugas ke layanan tersebut di aplikasi Anda. Permintaan tugas dirutekan ke versi di layanan tertentu yang dikonfigurasi untuk traffic. Pelajari cara permintaan dirutekan.

Pertimbangan penting untuk target:

  • Jika Anda mengaktifkan pemisahan traffic, permintaan tugas tidak akan dipisahkan di antara versi yang telah dikonfigurasi:
    • Pemisahan alamat IP: Permintaan tugas dari layanan Cron selalu dikirim dari alamat IP yang sama, sehingga akan dirutekan ke versi yang sama setiap saat.
    • Pemisahan cookie: Permintaan tugas tidak menyertakan cookie dengan permintaan, sehingga tidak dirutekan ke versi lainnya.
  • Jika Anda menggunakan file dispatch, tugas dapat dirutekan ulang saat URL yang sama juga dikonfigurasi di dispatch.yaml. Misalnya, jika URL /tasks/hello_service2 ditentukan di kedua file cron.yaml dan dispatch.yaml berikut, permintaan tugas akan dikirim ke service2, meskipun target: service1 ditentukan:

    cron.yaml: 

    cron:
- description: "test dispatch vs target"
  url: /tasks/hello_service2
  schedule: every 1 mins
  target: service1

    dispatch.yaml:

    dispatch:
- url: '*/tasks/hello_service2'
  service: service2
retry_parameters
Opsional. Menentukan untuk menjalankan kembali tugas yang gagal, lihat sintaksis di bawah.

Menentukan cron job schedule

Cron job dijadwalkan pada interval berulang dan ditentukan menggunakan format seperti bahasa Inggris yang sederhana. Anda dapat menentukan jadwal agar tugas berjalan beberapa kali sehari, atau pada hari dan bulan tertentu.

Interval sub-harian

Gunakan interval sub-harian untuk menjalankan tugas beberapa kali sehari sesuai jadwal berulang. Anda dapat menentukan interval waktu berakhir atau interval waktu mulai:

  • Interval waktu berakhir: Menentukan waktu antara "waktu berakhir" tugas dan kapan tugas berikutnya dimulai, dengan "waktu berakhir" adalah waktu saat tugas selesai atau waktu habis Layanan Cron menjalankan tugas dalam jenis interval ini selama 24 jam, mulai dari satu interval setelah waktu pembuatan/pembaruan tugas, dan menunggu interval yang ditentukan di antara setiap tugas.

    Contoh: Untuk jadwal every 5 minutes, tugas dijalankan setiap hari menggunakan interval 5 menit. Jika satu instance tugas yang berjalan pada jadwal ini selesai pada pukul 02:01, tugas berikutnya akan menunggu 5 menit dan dimulai lagi pada pukul 02:06.

  • Interval waktu mulai: Menentukan interval waktu reguler bagi layanan Cron untuk memulai setiap tugas. Tidak seperti interval waktu berakhir, interval waktu mulai menjalankan setiap tugas secara terpisah dari kapan tugas sebelumnya selesai atau habis waktunya. Anda dapat menetapkan rentang waktu untuk menjalankan tugas, atau menjalankan tugas 24 jam sehari, mulai dari awal rentang waktu yang ditentukan.

    Karena waktu mulai tugas ini ketat, jika sebuah instance tugas berjalan lebih lama daripada interval waktu yang ditentukan, tugas tertentu dapat dilewati oleh layanan Cron. Setiap waktu mulai dalam interval dapat dilewati jika tugas sebelumnya belum selesai atau waktu habis .

    Contoh: Untuk jadwal every 5 minutes from 10:00 to 14:00, tugas pertama mulai berjalan pada 10:00, lalu setiap 5 menit setelahnya. Jika tugas pertama tersebut berjalan selama 7 menit, tugas 10:05 akan dilewati, sehingga layanan Cron tidak akan menjalankan instance lain dari tugas ini hingga 10:10.

Interval kustom

Anda dapat menggunakan interval kustom untuk menentukan jadwal yang memungkinkan tugas Anda dijalankan sekali per hari pada satu atau beberapa hari tertentu, dan dalam satu atau beberapa bulan tertentu. Tugas yang berjalan pada jadwal kustom berjalan sepanjang tahun, hanya pada waktu tertentu pada hari dan bulan tertentu.

Contoh: Untuk jadwal 1,2,3 of month 07:00, tugas berjalan satu kali pada pukul 07:00 pada tiga hari pertama setiap bulan.

Pertimbangan penting untuk schedule:

  • Anda harus memutuskan apakah ingin menggunakan interval sub-harian atau interval kustom. Anda tidak dapat mencampur dan menggunakan elemen dari berbagai jenis interval. Berikut adalah contoh definisi jadwal yang tidak valid: schedule: every 6 hours mon,wed,fri.
  • Hanya satu instance tugas yang dapat dijalankan pada satu waktu. Layanan Cron dirancang untuk memberikan pengiriman "setidaknya sekali"; yaitu, jika tugas dijadwalkan, App Engine akan mengirimkan permintaan tugas setidaknya satu kali. Dalam beberapa situasi yang jarang terjadi, beberapa instance dari pekerjaan yang sama dapat diminta. Oleh karena itu, pengendali permintaan Anda harus bersifat idempotent, dan kode Anda harus memastikan bahwa tidak ada efek samping yang berbahaya jika hal ini terjadi.

Memformat schedule

Untuk menentukan kapan tugas dijalankan, Anda harus menentukan elemen schedule menggunakan sintaksis berikut:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Pilih jenis interval untuk menentukan elemen schedule Anda:

Interval waktu berakhir
  • [TYPE]: Interval harian harus menyertakan awalan every.

    Contoh: schedule: every 12 hours

  • [INTERVAL_VALUE]: Nilai bilangan bulat dan satuan waktu yang sesuai. Nilai yang valid untuk satuan waktu:
    • minutes atau mins
    • hours
  • [INTERVAL_SCOPE]: Tidak berlaku. Untuk menetapkan waktu mulai atau rentang waktu tertentu yang Anda inginkan untuk menjalankan tugas, lihat sintaksis untukInterval waktu mulai atau Interval kustom ini.
Contoh interval waktu berakhir
Gunakan contoh berikut untuk membantu Anda memahami cara menentukan jadwal tugas yang menggunakan interval waktu berakhir:
  • Menunggu 5 menit setelah deployment untuk dijalankan pertama kalinya. Setelah setiap tugas berakhir, layanan Cron akan menunggu 5 menit sebelum menjalankan tugas berikutnya: 
    schedule: every 5 minutes
  • Menunggu 30 menit setelah deployment untuk dijalankan pertama kali. Setelah setiap tugas berakhir, layanan Cron akan menunggu 30 menit sebelum menjalankan tugas berikutnya: 
    schedule: every 30 mins
Interval waktu mulai
  • [TYPE]: Interval harian harus menyertakan awalan every.

    Contoh: schedule: every 12 hours

  • [INTERVAL_VALUE]: Nilai bilangan bulat dan satuan waktu yang sesuai. Nilai yang valid untuk satuan waktu:
    • minutes atau mins
    • hours
  • [INTERVAL_SCOPE] Menentukan klausa yang sesuai dengan [INTERVAL_VALUE]. Anda dapat menentukan rentang waktu kustom atau menggunakan opsi synchronized 24 jam.
    • Sertakan klausa from [HH:MM] to [HH:MM] untuk menentukan rentang dan waktu mulai spesifik untuk menjalankan tugas.

      Anda harus menentukan nilai waktu dalam format 24 jam, HH:MM, dengan:

      • HH adalah bilangan bulat dari 00 hingga 23.
      • MM adalah bilangan bulat dari 00 hingga 59.
    • Gunakan synchronized untuk menentukan rentang waktu 24 jam (from 00:00 to 23:59) yang dibagi merata dengan nilai [INTERVAL_VALUE].

      Penting: [INTERVAL_VALUE] harus membagi 24 menjadi bilangan bulat. Jika tidak, error akan terjadi. Nilai yang valid untuk [INTERVAL_VALUE] mencakup: 1, 2, 3, 4, 6, 8, 12, atau 24.

Contoh interval waktu mulai
Gunakan contoh berikut untuk membantu Anda memahami cara menentukan jadwal pekerjaan yang menggunakan interval waktu mulai:
  • Dijalankan setiap 5 menit dari pukul 10.00 hingga 14.00, setiap hari: 
    schedule: every 5 minutes from 10:00 to 14:00
  • Dijalankan sekali setiap jam mulai pukul 08.00 hingga 16.00, setiap hari: 
    schedule: every 1 hours from 08:00 to 16:00
  • Dijalankan sekali setiap dua jam, setiap hari mulai pukul 00.00: 
    schedule: every 2 hours synchronized
Interval kustom
  • [TYPE]: Interval kustom dapat menyertakan awalan every untuk menentukan interval berulang, atau Anda dapat menentukan daftar hari tertentu dalam sebulan:
    • Untuk menentukan interval berulang, Anda dapat menggunakan awalan every.

      Contoh: 

      schedule: every day 00:00
schedule: every monday 09:00

    • Untuk menentukan hari tertentu, Anda harus menggunakan bilangan ordinal. Nilai yang valid adalah dari hari pertama setiap bulan, hingga jumlah hari maksimum di bulan tersebut, misalnya:
      • 1st atau first
      • 2nd atau second
      • 3rd atau third
      • Dan hingga: 31st atau thirtyfirst

      Contoh: 

      schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00

  • [INTERVAL_VALUE]: Interval kustom mencakup daftar hari tertentu saat Anda ingin tugas dijalankan. Daftar harus ditentukan dalam daftar yang dipisahkan koma dan dapat menyertakan salah satu nilai berikut:
    • Nilai bilangan bulat dari hari dalam sebulan hingga maksimum 31 hari, misalnya:
      • 1
      • 2
      • 3
      • Dan hingga: 31
    • Nama hari dalam campuran salah satu nilai panjang atau singkat berikut:
      • monday atau mon
      • tuesday atau tue
      • wednesday atau wed
      • thursday atau thu
      • friday atau fri
      • saturday atau sat
      • sunday atau sun
      • Gunakan day untuk menentukan semua hari dalam seminggu.

    Contoh: 

    schedule: 2nd monday,thu
schedule: 1,8,15,22 of month 09:00
schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [INTERVAL_SCOPE]: Menentukan klausa yang sesuai dengan [INTERVAL_VALUE] yang ditentukan. Interval kustom dapat menyertakan klausa of [MONTH], yang menentukan satu bulan dalam satu tahun, atau daftar beberapa bulan yang dipisahkan koma. Anda juga harus menentukan waktu spesifik kapan Anda ingin tugas dijalankan, misalnya: of [MONTH] [HH:MM].

    Secara default, jika klausa of dikecualikan, interval kustom akan dijalankan setiap bulan.

    • [MONTH]: Anda harus menentukan bulan dalam daftar yang dipisahkan koma dan dapat menyertakan campuran nilai panjang atau singkat berikut:
      • january atau jan
      • february atau feb
      • march atau mar
      • april atau apr
      • may
      • june atau jun
      • july atau jul
      • august atau aug
      • september atau sep
      • october atau oct
      • november atau nov
      • december atau dec
      • Gunakan month untuk menentukan semua bulan dalam setahun.
    • [HH:MM]: Anda harus menentukan nilai waktu dalam format 24 jam, HH:MM, dengan:
      • HH adalah bilangan bulat dari 00 hingga 23.
      • MM adalah bilangan bulat dari 00 hingga 59.

      • Contoh: 

      schedule: 1st monday of sep,oct,nov 09:00
schedule: 1 of jan,april,july,oct 00:00

Contoh interval kustom
Gunakan contoh berikut untuk membantu Anda memahami cara menentukan jadwal tugas yang menggunakan interval kustom:
  • Dijalankan setiap hari pada pukul 00.00: 
    schedule: every day 00:00
  • Dijalankan setiap hari Senin pada pukul 09.00: 
    schedule: every monday 09:00
  • Dijalankan satu kali pada hari Rabu kedua di bulan Maret pada pukul 17.00: 
    schedule: 2nd wednesday of march 17:00
  • Dijalankan enam kali pada bulan Mei. Selama dua minggu pertama, program ini dijalankan satu kali setiap hari Senin, Rabu, dan Jumat pada pukul 10.00: 
    schedule: 1st,second mon,wed,fri of may 10:00
  • Dijalankan seminggu sekali. Setiap tujuh hari mulai hari pertama setiap bulan, proses ini dijalankan sekali pada pukul 09.00: 
    schedule: 1,8,15,22 of month 09:00
  • Dijalankan setiap dua minggu. Pada hari Senin pertama dan ketiga setiap bulan, operasi ini dijalankan satu kali pada pukul 04.00: 
    schedule: 1st,third monday of month 04:00
  • Dijalankan tiga kali setiap tahun. Pada hari Senin pertama bulan September, Oktober, dan November, operasi ini dijalankan satu kali pada pukul 09.00: 
    schedule: 1st monday of sep,oct,nov 09:00
  • Dijalankan satu kali setiap empat bulan. Pada hari pertama bulan Januari, April, Juli, dan Oktober, tugas berjalan satu kali pada pukul 00.00: 
    schedule: 1 of jan,april,july,oct 00:00

Menentukan percobaan ulang

Jika pengendali permintaan cron job menampilkan kode status yang tidak berada dalam rentang 200–299 (inklusif), App Engine menganggap tugas tersebut gagal. Secara default, tugas yang gagal tidak akan dicoba ulang. Percobaan ulang pada tugas yang gagal dapat dilakukan dengan menyertakan blok retry_parameters dalam file konfigurasi Anda.

Berikut adalah contoh file cron.yaml yang berisi satu cron job yang dikonfigurasi untuk mencoba ulang hingga lima kali dengan backoff awal 2,5 detik yang digandakan setiap kali percobaan ulang dilakukan.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    job_retry_limit: 5
    min_backoff_seconds: 2.5
    max_doublings: 5

Sintaksis percobaan ulang cron

Parameter percobaan ulang dijelaskan dalam tabel di bawah.

Elemen Deskripsi
job_retry_limit Bilangan bulat yang menunjukkan jumlah maksimum upaya percobaan ulang untuk cron job yang gagal. Nilai minimum adalah 0, dan nilai maksimum adalah 5. Jika Anda juga menentukan job_age_limit, App Engine akan melakukan percobaan ulang cron job hingga kedua batas tercapai. Nilai default untuk job_retry_limit adalah 0.
job_age_limit Batas waktu untuk percobaan ulang cron job yang gagal, diukur dari saat cron job pertama kali dijalankan. Nilainya adalah angka yang diikuti oleh satuan waktu, dengan satuan s untuk detik, m untuk menit, h untuk jam, atau d untuk hari. Misalnya, nilai 5d menentukan batas lima hari setelah upaya eksekusi pertama cron job. Jika Anda juga menentukan job_retry_limit, App Engine melakukan percobaan ulang cron job hingga kedua batas tercapai.
min_backoff_seconds Jumlah detik minimum untuk menunggu sebelum melakukan percobaan ulang setelah cron job gagal.
max_backoff_seconds Jumlah detik maksimum untuk menunggu sebelum melakukan percobaan ulang setelah cron job gagal.
max_doublings Frekuensi maksimum untuk penggandaan interval antar-percobaan ulang cron job yang gagal sebelum peningkatan ini menjadi konstan. Konstantanya adalah 2**(max_doublings - 1) * min_backoff.

Memvalidasi permintaan cron

Anda mungkin ingin memvalidasi bahwa permintaan ke URL cron berasal dari App Engine dan bukan dari sumber lain. Anda dapat melakukannya dengan memvalidasi header HTTP dan alamat IP sumber untuk permintaan tersebut:

  • Permintaan dari Layanan Cron akan berisi header HTTP berikut:

    "X-Appengine-Cron": "true"

    Header ini dan header lainnya ditetapkan secara internal oleh App Engine. Jika klien mengirim header ini, header tersebut akan dihapus dari permintaan.

  • App Engine mengeluarkan permintaan Cron dari alamat IP 0.1.0.2. Untuk Cron job yang dibuat dengan versi gcloud yang lebih lama (lebih lama dari 326.0.0), permintaan Cron akan berasal dari 0.1.0.1.

Untuk runtime Java, di Jetty atau Tomcat, Anda dapat melakukan validasi ini dalam filter.

Waktu tunggu permintaan

Waktu tunggu permintaan cron adalah 60 menit.

Untuk mengetahui informasi selengkapnya tentang waktu tunggu permintaan per lingkungan dan jenis penskalaan, lihat Memilih lingkungan App Engine.

Mengupload cron job

Untuk mengupload cron job, Anda harus menentukan cron.yaml sebagai parameter ke perintah gcloud berikut:

gcloud app deploy cron.yaml

Menghapus cron job

Untuk menghapus semua cron job, ubah file cron.yaml agar hanya berisi:

cron:

Dukungan cron di konsol Google Cloud

Anda dapat memeriksa cron job terjadwal di halaman Cron job pada konsol Google Cloud.

Anda juga dapat membuka halaman Log untuk melihat kapan cron job ditambahkan atau dihapus.