Referensi cron.xml untuk Alat Berbasis App Engine SDK

Gunakan file cron.yaml untuk menentukan tugas terjadwal untuk aplikasi Anda.

Untuk mempelajari lebih lanjut cara menjadwalkan tugas, termasuk cara menguji, men-deploy, atau menghapus tugas Cron, lihat Menjadwalkan Tugas dengan Cron.

Contoh

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

Sintaksis

File cron.yaml harus berada di direktori root aplikasi Anda bersama app.yaml : cron.yaml mengonfigurasi tugas terjadwal untuk aplikasi Java 8 Anda.

Penentuan cron job

Elemen Deskripsi
description Opsional. Deskripsi ini dapat dilihat di Konsol Google Cloud dan antarmuka admin server pengembangan.
retry_parameters Opsional. Jika pengendali permintaan cron job menampilkan kode status HTTP yang tidak berada dalam rentang 200–299 (inklusif), App Engine akan menganggap tugas tersebut gagal. Secara default, tugas yang gagal tidak akan dicoba ulang. Agar tugas yang gagal dicoba ulang, Anda dapat menyertakan blok retry-parameter dalam file konfigurasi.

Lihat bagian Percobaan ulang cron untuk informasi selengkapnya.

schedule Wajib. Menentukan jadwal cron job dijalankan, lihat sintaksis di bawah.
target

String target ditambahkan ke nama host aplikasi Anda. Ini biasanya adalah nama layanan. Cron job akan dirutekan ke versi layanan bernama yang dikonfigurasi untuk traffic.

Jika nama layanan yang ditentukan untuk target tidak ditemukan, permintaan Cron akan dirutekan ke layanan default, atau ke versi aplikasi Anda yang dikonfigurasi untuk menerima traffic. Untuk mengetahui informasi selengkapnya tentang pemilihan rute, lihat Cara Permintaan Dirutekan.

timezone timezone harus berupa nama zona waktu zoneinfo standar. Jika Anda tidak menentukan zona waktu, tugas akan dijalankan dalam UTC (disebut juga GMT).
url Wajib. Kolom url hanyalah URL dalam aplikasi Anda. Jika elemen url berisi karakter XML khusus &, <, >, ', atau ", Anda harus meng-escape karakter tersebut.

Menentukan schedule cron job

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 00:00, dan menunggu selama durasi waktu 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 00:00.

    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</schedule>.
  • 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]</schedule>

Pilih jenis interval untuk menentukan elemen schedule Anda:

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

    Contoh: <schedule>every 12 hours</schedule>

  • [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:
  • Mulai dijalankan setiap hari pada pukul 00.00 dan menunggu 5 menit di antara setiap tugas. Setelah setiap tugas berakhir, layanan Cron akan menunggu 5 menit sebelum menjalankan tugas berikutnya: 
    <schedule>every 5 minutes</schedule>
  • Mulai dijalankan setiap hari pada pukul 00.00 dan menunggu selama 30 menit di antara setiap tugas. Setelah setiap tugas berakhir, layanan Cron akan menunggu 30 menit sebelum menjalankan tugas berikutnya: 
    <schedule>every 30 mins</schedule>
Interval waktu mulai
  • [TYPE]: Interval harian harus menyertakan awalan every.

    Contoh: <schedule>every 12 hours</schedule>

  • [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</schedule>
  • Dijalankan sekali setiap jam mulai pukul 08.00 hingga 16.00, setiap hari: 
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • Dijalankan sekali setiap dua jam, setiap hari mulai pukul 00.00: 
    <schedule>every 2 hours synchronized</schedule>
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>
<schedule>every monday 09:00</schedule>

    • 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>
<schedule>2nd,third wednesday of month 09:00</schedule>

  • [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>
<schedule>1,8,15,22 of month 09:00</schedule>
<schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [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>
<schedule>1 of jan,april,july,oct 00:00</schedule>

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</schedule>
  • Dijalankan setiap hari Senin pada pukul 09.00: 
    <schedule>every monday 09:00</schedule>
  • Dijalankan satu kali pada hari Rabu kedua di bulan Maret pada pukul 17.00: 
    <schedule>2nd wednesday of march 17:00</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • Dijalankan satu kali setiap empat bulan. Pada hari pertama Januari, April, Juli, dan Oktober, tugas dijalankan satu kali pada pukul 00.00: 
    <schedule>1 of jan,april,july,oct 00:00</schedule>

Percobaan ulang cron

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

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

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

Sintaksis percobaan ulang cron

Parameter percobaan ulang dijelaskan dalam tabel di bawah.

Elemen Deskripsi
job_retry_limit Jumlah maksimum upaya percobaan ulang untuk sebuah cron job yang gagal tidak lebih dari 5 kali. Jika ditentukan dengan job_age_limit, App Engine akan mencoba ulang cron job tersebut hingga kedua batas tercapai. Jika dihilangkan dari parameter, batas ini akan ditetapkan ke nilai default-nya, yaitu 5.
job_age_limit Batas waktu untuk mencoba kembali 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 ditentukan dengan job_retry_limit, App Engine akan mencoba ulang cron job tersebut hingga kedua batas tercapai.
min_backoff_seconds Jumlah minimum detik untuk menunggu sebelum mencoba ulang cron job yang 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.

Permintaan cron

Header permintaan

Permintaan dari Layanan Cron akan berisi header HTTP:

X-Appengine-Cron: true

Header ini dan header lainnya ditetapkan secara internal oleh App Engine. Header tersebut akan dihapus dari permintaan jika header dikirimkan oleh klien. Namun, administrator aplikasi lama yang telah login mendapatkan pengecualian; mereka diizinkan menetapkan header permintaan untuk tujuan pengujian.

Alamat IP asal

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.

Waktu tunggu permintaan

Waktu tunggu permintaan cron bergantung pada jenis penskalaan yang dikonfigurasi untuk aplikasi Anda:

Penskalaan otomatis
Waktu tunggu permintaan 10 menit.
Penskalaan dasar dan penskalaan manual
Waktu tunggu permintaan 24 jam.

Untuk informasi selengkapnya, lihat Cara instance dikelola.

Batas

Aplikasi gratis dapat memiliki hingga 20 tugas terjadwal. Aplikasi berbayar dapat memiliki hingga 250 tugas terjadwal.

Dukungan cron di server pengembangan

Server pengembangan tidak otomatis menjalankan cron job. Anda dapat menggunakan antarmuka tugas cron atau terjadwal di desktop lokal untuk memicu URL tugas dengan curl atau alat serupa.

Men-deploy cron job

Anda dapat menggunakan gcloud CLI untuk men-deploy cron job ke App Engine.

Untuk men-deploy cron job yang ditentukan dalam file konfigurasi cron.yaml, jalankan perintah berikut:

gcloud

    gcloud app deploy cron.yaml

Maven

    mvn appengine:deployCron cron.yaml

Gradle

    gradle appengineDeployCron cron.yaml

IDE

Jika menggunakan IntelliJ atau Eclipse, Anda dapat memilih file konfigurasi tertentu yang akan di-deploy menggunakan formulir deployment.

Menghapus semua cron job

Untuk menghapus semua cron job:

  1. Edit konten cron.yaml untuk:

    cron:

  2. Deploy file cron.yaml ke App Engine.

Dukungan cron di Konsol Google Cloud

Halaman Task queue di Konsol Google Cloud memiliki tab yang menampilkan tugas yang sedang menjalankan cron job.

Anda juga dapat membuka halaman Logs untuk mengetahui kapan cron job ditambahkan atau dihapus.