Share via

Pemicu timer untuk Azure Functions

  • Artikel

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.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

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 dengan menggunakan salah satu mode C# berikut:

  • Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi LTS dan non-LTS .NET dan .NET Framework. Ekstensi untuk fungsi proses pekerja yang terisolasi menggunakan Microsoft.Azure.Functions.Worker.Extensions.* namespace layanan.
  • Model dalam proses: Fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions. Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Ekstensi untuk fungsi dalam proses menggunakan Microsoft.Azure.WebJobs.Extensions.* namespace layanan.

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

//<docsnippet_fixed_delay_retry_example>
[Function(nameof(TimerFunction))]
[FixedDelayRetry(5, "00:00:10")]
public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo,
    FunctionContext context)
{
    var logger = context.GetLogger(nameof(TimerFunction));

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 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. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

import datetime
import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="mytimer")
@app.timer_trigger(schedule="0 */5 * * * *", 
              arg_name="mytimer",
              run_on_startup=True) 
def test_function(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.utcnow().replace(
        tzinfo=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)

Contoh berikut menunjukkan fungsi TypeScript pemicu timer.

import { app, InvocationContext, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<void> {
    context.log('Timer function processed request.');
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: timerTrigger1,
});

Contoh berikut menunjukkan fungsi JavaScript pemicu timer.

const { app } = require('@azure/functions');

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: (myTimer, context) => {
        context.log('Timer function processed request.');
    },
});

Berikut data pengikatan dalam file function.json:

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

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"

Atribut

Pustaka C# dalam proses menggunakan TimerTriggerAttribute dari Microsoft.Azure.WebJobs.Extensions sedangkan pustaka C# proses pekerja yang terisolasi menggunakan TimerTriggerAttribute dari Microsoft.Azure.Functions.Worker.Extensions.Timer 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.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada schedule:

Properti Deskripsi
arg_name Nama variabel yang mewakili objek timer dalam kode fungsi.
schedule 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%".
run_on_startup 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.
use_monitor 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.

Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .

Anotasi

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

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke app.timer() metode .

Properti Deskripsi
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.

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.
arah 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
}

{
    "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, selama 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 dan TZ saat ini tidak didukung saat berjalan di Linux dalam paket Konsumsi. Dalam hal ini, mengatur WEBSITE_TIME_ZONE atau TZ dapat membuat masalah terkait SSL dan menyebabkan metrik berhenti berfungsi untuk aplikasi Anda.

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 contoh:

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