Pemicu timer untuk Azure Functions

  • Artikel
  • 12 menit untuk membaca

Artikel ini menjelaskan cara bekerja dengan pemicu timer di Azure Functions. Pemicu timer memungkinkan Anda menjalankan fungsi sesuai jadwal.

Ini adalah informasi referensi untuk pengembang Azure Functions. Jika Anda baru menggunakan Azure Functions, mulailah dengan sumber daya berikut ini:

Untuk informasi tentang cara menjalankan fungsi yang dipicu timer secara manual, lihat Menjalankan fungsi yang dipicu oleh HTTP secara manual.

Dukungan untuk pengikatan data ini secara otomatis disediakan di semua lingkungan pengembangan. Anda tidak perlu memasang paket secara manual atau mendaftarkan ekstensi.

Kode sumber untuk paket ekstensi timer tersebut berada di repositori GitHub azure-webjobs-sdk-extensions.

Contoh

Contoh ini menunjukkan fungsi C# yang dijalankan pada menit yang memiliki nilai kelipatan lima. Misalnya, ketika fungsi dimulai pada pukul 18:55:00, eksekusi berikutnya adalah pada pukul 19:00:00. Objek TimerInfo diteruskan ke fungsi.

Fungsi C# dapat dibuat menggunakan salah satu mode C# berikut:

  • Pustaka kelas dalam proses: fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions.
  • Pustaka kelas proses terisolasi: fungsi C# yang dikompilasi yang berjalan dalam proses yang terisolasi dari runtime. Proses terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada .NET 5.0.
  • Skrip C#: digunakan terutama saat membuat fungsi C# di portal Microsoft Azure.
[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
}

Contoh fungsi berikut memicu dan mengeksekusi setiap lima menit. @TimerTriggerAnotasi pada fungsi menentukan jadwal menggunakan format string yang sama dengan ekspresi CRON.

@FunctionName("keepAlive")
public void keepAlive(
  @TimerTrigger(name = "keepAliveTrigger", schedule = "0 */5 * * * *") String timerInfo,
      ExecutionContext context
 ) {
     // timeInfo is a JSON string, you can deserialize it to an object using your favorite JSON library
     context.getLogger().info("Timer is triggered: " + timerInfo);
}

Contoh berikut menunjukkan pengikatan pemicu timer dalam file function.json dan kode fungsi yang menggunakan pengikatan, di mana instans yang mewakili timer diteruskan ke fungsi. Fungsi ini menulis log yang menunjukkan apakah pemanggilan fungsi ini disebabkan oleh kemunculan jadwal yang terlewat.

Berikut data pengikatan dalam file function.json:

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

Berikut kode JavaScript:

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.isPastDue)
    {
        context.log('Node is running late!');
    }
    context.log('Node timer trigger function ran!', timeStamp);   
};

Berikut ini adalah kode fungsi timer dalam file run.ps1:

# Input bindings are passed in via param block.
param($myTimer)

# Get the current universal time in the default string format.
$currentUTCtime = (Get-Date).ToUniversalTime()

# The 'IsPastDue' property is 'true' when the current function invocation is later than scheduled.
if ($myTimer.IsPastDue) {
    Write-Host "PowerShell timer is running late!"
}

# Write an information log with the current time.
Write-Host "PowerShell timer trigger function ran! TIME: $currentUTCtime"

Berikut adalah kode Python, di mana objek yang diteruskan ke fungsi berjenis objek azure.functions.TimerRequest.

import datetime
import logging

import azure.functions as func


def main(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()

    if mytimer.past_due:
        logging.info('The timer is past due!')

    logging.info('Python timer trigger function ran at %s', utc_timestamp)

Atribut

Pustaka C# dalam proses dan proses terisolasi keduanya menggunakan atribut TimerTriggerAttribute untuk menentukan fungsi.

Sebagai gantinya, skrip C# menggunakan file konfigurasi function.json.

Properti atribut Deskripsi
Jadwal Ekspresi CRON atau nilai TimeSpan. TimeSpan hanya dapat digunakan untuk aplikasi fungsi yang berjalan pada Paket Layanan Aplikasi. Anda dapat menempatkan ekspresi jadwal dalam pengaturan aplikasi dan mengatur properti ini menjadi nama pengaturan aplikasi yang dibungkus dengan tanda %, sebagai %ScheduleAppSetting%.
RunOnStartup Jika true, fungsi dipanggil ketika runtime dimulai. Misalnya, runtime dimulai saat aplikasi fungsi bangun setelah menganggur karena tidak aktif. ketika aplikasi fungsi dimulai ulang karena perubahan fungsi, dan saat peluasan skala aplikasi fungsi. Gunakan dengan hati-hati. RunOnStartup jarang diatur ke true, terutama dalam produksi.
useMonitor Atur true ke false atau untuk menunjukkan apakah jadwal harus dipantau. Pemantauan jadwal tetap terjadi jadwal untuk membantu memastikan jadwal dipertahankan dengan benar bahkan ketika instans aplikasi fungsi dimulai ulang. Jika tidak diatur secara eksplisit, defaultnya true adalah untuk jadwal yang memiliki interval pengulangan lebih besar dari atau sama dengan 1 menit. Untuk jadwal yang memicu lebih dari sekali per menit, defaultnya adalah false.

Anotasi

Anotasi @TimerTrigger pada fungsi menentukan schedule menggunakan format string yang sama dengan ekspresi CRON. Anotasi tersebut mendukung pengaturan berikut:

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json Deskripsi
jenis Harus diatur ke "timerTrigger". Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
petunjuk Harus diatur ke "in". Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
nama Nama variabel yang mewakili objek timer dalam kode fungsi.
jadwal Ekspresi CRON atau nilai TimeSpan. TimeSpan hanya dapat digunakan untuk aplikasi fungsi yang berjalan pada Paket Layanan Aplikasi. Anda dapat meletakkan ekspresi jadwal dalam pengaturan aplikasi dan mengatur properti ini ke nama pengaturan aplikasi yang dibungkus dalam % tanda, seperti dalam contoh ini: "%ScheduleAppSetting%".
runOnStartup Jika true, fungsi dipanggil ketika runtime dimulai. Misalnya, runtime dimulai saat aplikasi fungsi bangun setelah menganggur karena tidak aktif. ketika aplikasi fungsi dimulai ulang karena perubahan fungsi, dan saat peluasan skala aplikasi fungsi. Gunakan dengan hati-hati. runOnStartup jarang diatur ke true, terutama dalam produksi.
useMonitor Atur true ke false atau untuk menunjukkan apakah jadwal harus dipantau. Pemantauan jadwal tetap terjadi jadwal untuk membantu memastikan jadwal dipertahankan dengan benar bahkan ketika instans aplikasi fungsi dimulai ulang. Jika tidak diatur secara eksplisit, defaultnya true adalah untuk jadwal yang memiliki interval pengulangan lebih besar dari atau sama dengan 1 menit. Untuk jadwal yang memicu lebih dari sekali per menit, defaultnya adalah false.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Perhatian

Jangan atur runOnStartup ke true dalam produksi. Menggunakan pengaturan ini membuat eksekusi kode pada waktu yang sangat tidak dapat diprediksi. Dalam pengaturan produksi tertentu, eksekusi ekstra ini dapat dikenakan biaya yang jauh lebih tinggi untuk aplikasi yang dihosting dalam paket Pemakaian. Misalnya, dengan runOnStartup diaktifkan pemicu dipanggil setiap kali aplikasi fungsi Anda diskalakan. Pastikan Anda sepenuhnya memahami perilaku produksi fungsi Anda sebelum mengaktifkan runOnStartup dalam produksi.

Lihat Bagian contoh untuk contoh lengkapnya.

Penggunaan

Ketika fungsi pemicu timer dipanggil, objek timer diteruskan ke fungsi. JSON berikut adalah contoh representasi objek timer.

{
    "Schedule":{
        "AdjustForDST": true
    },
    "ScheduleStatus": {
        "Last":"2016-10-04T10:15:00+00:00",
        "LastUpdated":"2016-10-04T10:16:00+00:00",
        "Next":"2016-10-04T10:20:00+00:00"
    },
    "IsPastDue":false
}

Properti isPastDue adalah true ketika pemanggilan fungsi saat ini lebih lambat dari yang dijadwalkan. Misalnya, restart aplikasi fungsi dapat menyebabkan pemanggilan terlewatkan.

Ekspresi NCRONTAB

Azure Functions menggunakan pustaka NCronTab untuk menginterpretasikan ekspresi NCRONTAB. Ekspresi NCRONTAB mirip dengan ekspresi CRON kecuali bahwa ekspresi tersebut menyertakan bidang keenam tambahan di awal untuk digunakan untuk presisi waktu dalam detik:

{second} {minute} {hour} {day} {month} {day-of-week}

Setiap bidang dapat memiliki salah satu dari jenis nilai berikut:

Jenis Contoh Saat dipicu
Nilai tertentu 0 5 * * * * Sekali setiap jam dalam sehari pada menit 5 setiap jam
Semua nilai (*) 0 * 5 * * * Pada setiap menit dalam satu jam, dimulai pada jam 5
Rentang (operator -) 5-7 * * * * * Tiga kali semenit - pada detik 5 hingga 7 selama setiap menit setiap jam setiap hari
Satu set nilai (operator ,) 5,8,10 * * * * * Tiga kali semenit - pada detik 5, 8, dan 10 selama setiap menit setiap jam setiap hari
Nilai interval (operator /) 0 */5 * * * * 12 kali per jam - pada 0 kedua setiap menit ke-5 setiap jam setiap hari

Untuk menentukan bulan atau hari, Anda dapat menggunakan nilai numerik, nama, atau singkatan nama:

  • Selama berhari-hari, nilai numerik adalah 0 hingga 6 dengan 0 dimulai dengan Hari Minggu.
  • Nama dalam bahasa Inggris. Misalnya: Monday, January.
  • Nama tidak peka huruf besar/kecil.
  • Nama dapat disingkat. Tiga huruf adalah panjang singkatan yang disarankan. Misalnya: Mon, Jan.

Contoh NCRONTAB

Berikut adalah beberapa contoh ekspresi NCRONTAB yang dapat Anda gunakan untuk pemicu timer di Azure Functions.

Contoh Saat dipicu
0 */5 * * * * sekali setiap lima menit
0 0 * * * * sekali di atas setiap jam
0 0 */2 * * * setiap dua jam sekali
0 0 9-17 * * * sekali setiap jam dari jam 9 pagi sampai jam 5 sore
0 30 9 * * * pada 09:30 setiap hari
0 30 9 * * 1-5 pada 09:30 setiap hari kerja
0 30 9 * Jan Mon jam 09:30 setiap hari Senin di bulan Januari

Catatan

Ekspresi NCRONTAB mendukung format lima bidang dan enam bidang. Posisi bidang keenam adalah nilai untuk detik yang ditempatkan di awal ekspresi.

Zona waktu NCRONTAB

Angka dalam ekspresi CRON merujuk ke waktu dan tanggal, bukan rentang waktu. Misalnya, 5 di bidang hour mengacu pada pukul 05.00, tidak setiap 5 jam.

Zona waktu yang digunakan dengan ekspresi CRON adalah Waktu Universal Terkoordinasi (UTC). Agar ekspresi CRON Anda berjalan berdasarkan zona waktu lain, buat setelan aplikasi untuk aplikasi fungsi Anda yang bernama WEBSITE_TIME_ZONE.

Nilai pengaturan ini bergantung pada sistem operasi dan rencana tempat aplikasi fungsi Anda berjalan.

Sistem operasi Paket Nilai
Windows Semua Atur nilai ke nama zona waktu yang diinginkan seperti yang diberikan oleh baris kedua dari setiap pasangan yang diberikan oleh perintah Windows tzutil.exe /L
Linux Premium
Khusus		 Atur nilai ke nama zona waktu yang diinginkan seperti yang ditunjukkan dalam tz database.

Catatan

WEBSITE_TIME_ZONE saat ini tidak didukung pada paket Konsumsi Linux.

Misalnya, Waktu Timur di AS (diwakili oleh Eastern Standard Time (Windows) atau America/New_York (Linux)) saat ini menggunakan UTC-05:00 selama waktu standar dan UTC-04:00 selama siang hari. Untuk memiliki fire pemicu timer pada pukul 10.00 Waktu Timur setiap hari, buat pengaturan aplikasi untuk aplikasi fungsi Anda bernama WEBSITE_TIME_ZONE, atur nilai ke Eastern Standard Time (Windows) atau America/New_York (Linux), lalu gunakan ekspresi NCRONTAB berikut:

"0 0 10 * * *"

Saat Anda menggunakan WEBSITE_TIME_ZONE waktu disesuaikan untuk perubahan waktu dalam zona waktu tertentu, termasuk waktu musim panas dan perubahan waktu standar.

TimeSpan

TimeSpan hanya dapat digunakan untuk aplikasi fungsi yang berjalan pada Paket Layanan Aplikasi.

Tidak seperti ekspresi CRON, TimeSpan nilai menentukan interval waktu di antara setiap pemanggilan fungsi. Ketika fungsi selesai setelah berjalan lebih lama dari interval yang ditentukan, timer segera memanggil fungsi lagi.

Dinyatakan sebagai string, TimeSpan formatnya adalah hh:mm:ss ketika hh kurang dari 24. Ketika dua digit pertama adalah 24 atau lebih besar, formatnya adalah dd:hh:mm. Berikut adalah beberapa contohnya:

Contoh Saat dipicu
"01:00:00" Setiap jam
"00:01:00" Setiap menit
"25:00:00:00" Setiap 25 hari
"1.00:00:00" Setiap hari

Peluasan skala

Jika aplikasi fungsi diskalakan ke beberapa instans, hanya satu instans fungsi yang dipicu timer yang dijalankan di semua instans. Ini tidak akan memicu lagi jika ada pemanggilan yang luar biasa masih berjalan.

Aplikasi fungsi berbagi Penyimpanan

Jika Anda berbagi akun penyimpanan di seluruh aplikasi fungsi yang tidak digunakan ke layanan aplikasi, Anda mungkin perlu secara eksplisit menetapkan ID host untuk setiap aplikasi.

Versi Azure Functions Pengaturan
2.x (dan lebih tinggi) AzureFunctionsWebHost__hostid Variabel lingkungan
1.x iddalam host.json

Anda dapat menghilangkan nilai identifikasi atau mengatur konfigurasi identifikasi setiap aplikasi secara manual ke nilai yang berbeda.

Pemicu timer menggunakan kunci penyimpanan untuk memastikan bahwa hanya akan ada satu instans timer ketika aplikasi fungsi diskalakan ke beberapa instans. Jika dua aplikasi fungsi memiliki konfigurasi identifikasi yang sama dan masing-masing menggunakan pemicu timer, hanya satu timer yang berjalan.

Perilaku percobaan kembali

Tidak seperti pemicu antrean, pemicu timer tidak mencoba lagi setelah fungsi gagal. Ketika fungsi gagal, fungsi tidak dipanggil lagi sampai waktu berikutnya pada jadwal.

Memanggil pemicu timer secara manual

Pemicu timer untuk Azure Functions menyediakan webhook HTTP yang dapat dipanggil untuk memicu fungsi secara manual. Ini bisa sangat berguna dalam skenario berikut.

  • Pengujian integrasi
  • Pertukaran slot sebagai bagian dari tes asap atau aktivitas pemanasan
  • Penyebaran awal fungsi untuk segera mengisi singgahan atau tabel pencarian dalam database

Silakan merujuk untuk menjalankan fungsi yang dipicu non HTTP secara manual untuk detail tentang cara memanggil fungsi yang dipicu timer secara manual.

Pemecahan Masalah

Untuk informasi tentang apa yang harus dilakukan ketika pemicu timer tidak berfungsi seperti yang diharapkan, lihat Menyelidiki dan melaporkan masalah dengan fungsi yang dipicu timer tidak menembak.

Langkah berikutnya

Masuk ke mulai cepat yang menggunakan pemicu timer

Pelajari selengkapnya tentang pemicu dan pengikatan fungsi Azure