適用于 Azure Functions 的計時器觸發程序

  • 發行項

本文說明如何在 Azure Functions 中使用定時器觸發程式。 定時器觸發程式可讓您依排程執行函式。

這是 Azure Functions 開發人員的參考資訊。 如果您不熟悉 Azure Functions，請從下列資源開始：

如需如何手動執行定時器觸發函式的資訊，請參閱 手動執行非 HTTP 觸發函式。

所有開發環境中都會自動提供此系結的支援。 您不需要手動安裝套件或註冊擴充功能。

定時器擴充套件的原始程式碼位於 azure-webjobs-sdk-extensions GitHub 存放庫中。

重要

本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。 如需 v4 模型運作方式的詳細資訊，請參閱 Azure Functions Node.js開發人員指南。 若要深入瞭解 v3 與 v4 之間的差異，請參閱 移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

範例

此範例顯示 C# 函式，該函式會在分鐘後每次有五個可分割的值時執行。 例如，當函式從 18：55：00 開始時，下一個執行是在 19：00：00。 物件 TimerInfo 會傳遞至函式。

您可以使用下列其中一種 C# 模式來建立 C# 函式：

  • 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。 隔離背景工作進程函式的延伸模組會使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
  • 同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。 進程內函式的延伸模組會使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

重要

支援將於 2026 年 11 月 10 日結束進程模型。 強烈建議您將 應用程式移轉至隔離的背景工作模型 ，以取得完整支援。

//<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));

下列範例函式會觸發並每隔五分鐘執行一次。 函 @TimerTrigger 式上的註釋會使用與 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);
}

下列範例示範使用系結的定時器觸發程式系結和函式程序代碼，其中代表定時器的實例會傳遞至 函式。 此函式會寫入一項記錄，指出此函式引動過程是否由遺失的排程項目所造成。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

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)

下列範例顯示定時器觸發 程式 TypeScript 函式。

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,
});

下列範例顯示定時器觸發 程式 JavaScript 函式。

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

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

以下是 function.json 檔案中的繫結資料：

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

以下是 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"

屬性

進程內 C# 連結庫使用來自 Microsoft.Azure.WebJobs.Extensions 的 TimerTriggerAttribute，而隔離的背景工作進程 C# 連結庫則使用來自 Microsoft.Azure.Functions.Worker.Extensions.Timer 的 TimerTriggerAttribute 來定義函式。 C# 文稿會改用 function.json組態檔。

Attribute 屬性 描述
[排程] CRON 運算式或 TimeSpan 值。 TimeSpan 只能用於 App Service 方案上執行的函式應用程式。 您可以將排程表示式放在應用程式設定中，並將此屬性設定為包裝在 % 符號中的應用程式設定名稱，如 %ScheduleAppSetting%。
RunOnStartup 如果為 true，當執行階段啟動時，會叫用函式。 例如，當函式應用程式因無活動而處於閒置狀態後再甦醒時、 當函式應用程式因為函式變更而重新啟動，以及函式應用程式相應放大時。 請小心使用。RunOnStartup 應該很少會設定為 true，特別是在生產環境中。
UseMonitor 設定為 true 或 false 以表示是否應該監視排程。 排程監視會使排程持續進行，以協助確保即使在函式應用程式執行個體重新啟動時，排程也能正確地持續運作。 如果未明確設定，則針對循環間隔大於或等於 1 分鐘的排程，預設值為 true。 若為每分鐘觸發超過一次的排程，預設值為 false。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，在上 schedule具有下列屬性：

屬性 說明
arg_name 代表函式程式碼中計時器物件的變數名稱。
schedule CRON 運算式或 TimeSpan 值。 TimeSpan 只能用於 App Service 方案上執行的函式應用程式。 您可以將排程運算式放在應用程式設定中，並將此屬性設定為以 % 符號包裝的應用程式設定名稱，如此範例所示："%ScheduleAppSetting%"。
run_on_startup 如果為 true，當執行階段啟動時，會叫用函式。 例如，當函式應用程式因無活動而處於閒置狀態後再甦醒時、 當函式應用程式因函式變更而重新啟動時，以及當函式應用程式相應放大時，執行階段便會啟動。請小心使用。runOnStartup 應該很少設定為 true，尤其是在生產環境中。
use_monitor 設定為 true 或 false 以表示是否應該監視排程。 排程監視會使排程持續進行，以協助確保即使在函式應用程式執行個體重新啟動時，排程也能正確地持續運作。 如果未明確設定，則針對循環間隔大於或等於 1 分鐘的排程，預設值為 true。 若為每分鐘觸發超過一次的排程，預設值為 false。

如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。

註釋

函 @TimerTrigger 式上的註解會 schedule 使用與 CRON 運算式相同的字串格式來定義 。 註解支援下列設定：

組態

僅適用於 Python v1 程式設計模型。

下表說明您可以在傳遞至 app.timer() 方法的物件options上設定的屬性。

屬性 說明
schedule CRON 運算式或 TimeSpan 值。 TimeSpan 只能用於 App Service 方案上執行的函式應用程式。 您可以將排程運算式放在應用程式設定中，並將此屬性設定為以 % 符號包裝的應用程式設定名稱，如此範例所示："%ScheduleAppSetting%"。
runOnStartup 如果為 true，當執行階段啟動時，會叫用函式。 例如，當函式應用程式因無活動而處於閒置狀態後再甦醒時、 當函式應用程式因函式變更而重新啟動時，以及當函式應用程式相應放大時，執行階段便會啟動。請小心使用。runOnStartup 應該很少設定為 true，尤其是在生產環境中。
useMonitor 設定為 true 或 false 以表示是否應該監視排程。 排程監視會使排程持續進行，以協助確保即使在函式應用程式執行個體重新啟動時，排程也能正確地持續運作。 如果未明確設定，則針對循環間隔大於或等於 1 分鐘的排程，預設值為 true。 若為每分鐘觸發超過一次的排程，預設值為 false。

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性 描述
type 必須設定為 「timerTrigger」。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction 必須設定為 「in」。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name 代表函式程式碼中計時器物件的變數名稱。
schedule CRON 運算式或 TimeSpan 值。 TimeSpan 只能用於 App Service 方案上執行的函式應用程式。 您可以將排程運算式放在應用程式設定中，並將此屬性設定為以 % 符號包裝的應用程式設定名稱，如此範例所示："%ScheduleAppSetting%"。
runOnStartup 如果為 true，當執行階段啟動時，會叫用函式。 例如，當函式應用程式因無活動而處於閒置狀態後再甦醒時、 當函式應用程式因函式變更而重新啟動時，以及當函式應用程式相應放大時，執行階段便會啟動。請小心使用。runOnStartup 應該很少設定為 true，尤其是在生產環境中。
useMonitor 設定為 true 或 false 以表示是否應該監視排程。 排程監視會使排程持續進行，以協助確保即使在函式應用程式執行個體重新啟動時，排程也能正確地持續運作。 如果未明確設定，則針對循環間隔大於或等於 1 分鐘的排程，預設值為 true。 若為每分鐘觸發超過一次的排程，預設值為 false。

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

警告

請勿在生產環境中將 runOnStartup 設定為 true 。 使用此設定可讓程式代碼在高度無法預測的時間執行。 在某些生產設定中，這些額外的執行可能會導致在取用方案中裝載的應用程式成本大幅提高。 例如，只要 啟用 runOnStartup ，每當調整函式應用程式時，就會叫用觸發程式。 在生產環境中啟用 runOnStartup 之前，請確定您完全瞭解函式的生產行為。

如需完整範例， 請參閱範例一節 。

使用方式

叫用定時器觸發程式函式時，定時器對象會傳遞至函式。 下列 JSON 是定時器物件的範例表示法。

{
    "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
}

屬性 isPastDue 是在 true 目前的函式調用晚於排程時。 例如，函式應用程式重新啟動可能會導致叫用遺失。

NCRONTAB 運算式

Azure Functions 會 使用 NCronTab 連結庫來解譯 NCRONTAB 表達式。 NCRONTAB 運算式類似於 CRON 運算式，不同之處在於它包含開頭的額外第六個字段，以秒為單位的時間精確度：

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

每個欄位都可以有下列其中一種值：

類型 範例 觸發時
特定值 0 5 * * * * 每天每小時一次，每小時 5 分鐘
所有值 （*） 0 * 5 * * * 在一小時內的每一分鐘，在5小時
範圍 （- 運算子） 5-7 * * * * * 每分鐘三次 - 每天每小時每分鐘 5 到 7 秒
一組值 （, 運算子） 5,8,10 * * * * * 每分鐘三次 - 每天每小時 5、8 和 10 秒
間隔值 （/ 運算子） 0 */5 * * * * 每小時 12 次 - 每天每 5 分鐘的第二秒 0

若要指定月份或天數，您可以使用數值、名稱或名稱縮寫：

  • 天數內，數值為 0 到 6，其中 0 從星期日開始。
  • 名稱是英文。 例如：Monday、January。
  • 名稱不區分大小寫。
  • 名稱可以縮寫。 三個字母是建議的縮寫長度。 例如：Mon、Jan。

NCRONTAB 範例

以下是一些可用於 Azure Functions 中定時器觸發程式的 NCRONTAB 運算式範例。

範例 觸發時
0 */5 * * * * 每五分鐘一次
0 0 * * * * 每小時頂端一次
0 0 */2 * * * 每兩小時一次
0 0 9-17 * * * 每小時一次，從上午 9 點到下午 5 點
0 30 9 * * * 每天上午 9：30
0 30 9 * * 1-5 每天上午 9：30
0 30 9 * Jan Mon 1 月每星期一上午 9：30

注意

NCRONTAB 運算式同時 支援五個字段 和 六個字段 格式。 第六個字段位置是一個秒的值，放在表達式的開頭。

NCRONTAB 時區

CRON 運算式中的數位是指時間和日期，而不是時間範圍。 例如，欄位中的 5 hour 是指上午 5：00，而不是每 5 小時一次。

CRON 運算式使用的預設時區是國際標準時間 (UTC)。 若要讓CRON運算式以另一個時區為基礎，請為名為 WEBSITE_TIME_ZONE的函式應用程式建立應用程式設定。

此設定的值取決於函數應用程式執行所在的作業系統和方案。

作業系統 計畫 值
Windows 全部 將值設定為所需時區的名稱，如 Windows 命令所指定之每個配對的第二行所指定 tzutil.exe /L
Linux 進階
專用		 將值設定為所需時區的名稱，如 tz 資料庫中所示。

注意

WEBSITE_TIME_ZONE 在取用方案中在 Linux 上執行 時，目前不支援 和 TZ 。 在此情況下，設定 WEBSITE_TIME_ZONE 或 TZ 可以建立 SSL 相關問題，並導致計量停止為您的應用程式運作。

例如，美國東部時間（以 Eastern Standard Time （Windows） 或 America/New_York （Linux） 代表）目前在標準時間使用 UTC-05：00，在日光節約時間使用 UTC-04：00。 若要每天上午 10：00 引發定時器觸發程式，請為名為 WEBSITE_TIME_ZONE的函式應用程式建立應用程式設定、將值設定為 Eastern Standard Time （Windows） 或 America/New_York （Linux），然後使用下列 NCRONTAB 表達式：

"0 0 10 * * *"

當您使用 WEBSITE_TIME_ZONE 時間時，會針對特定時區的時間變更進行調整，包括日光節約時間和標準時間的變更。

TimeSpan

TimeSpan 只能用於 App Service 方案上執行的函式應用程式。

不同於 CRON 運算式，值 TimeSpan 會指定每個函式調用之間的時間間隔。 當函式在運行時間超過指定的間隔之後完成時，定時器會立即再次叫用函式。

以字串表示，TimeSpan格式為hh:mm:sshh小於 24 時。 目前兩個數位是 24 或更大時，格式為 dd:hh:mm。 以下列出一些範例：

範例 觸發時
"01:00:00" 每小時
"00:01:00" 每分鐘
"25:00:00:00" 每 25 天
"1.00:00:00" 每天

向外延展

如果函式應用程式向外延展至多個實例，則所有實例只會執行定時器觸發函式的單一實例。 如果有未完成的叫用仍在執行，則不會再次予以觸發。

函式應用程式共用 儲存體

如果您要跨未部署到 App Service 的函式應用程式共用記憶體帳戶，您可能需要明確地將主機標識碼指派給每個應用程式。

Functions 版本 設定
2.x （和更新版本） AzureFunctionsWebHost__hostid 環境變數
1.x id in host.json

您可以省略識別值，或手動將每個函式應用程式的識別組態設定設為不同的值。

定時器觸發程式會使用記憶體鎖定來確保當函式應用程式向外延展至多個實例時，只有一個定時器實例。 如果兩個函式應用程式共用相同的識別組態，且每個應用程式都使用定時器觸發程式，則只會執行一個定時器。

重試行為

不同於佇列觸發程式，定時器觸發程式不會在函式失敗之後重試。 當函式失敗時，直到下次排程時，才會再次呼叫它。

手動叫用定時器觸發程式

Azure Functions 的定時器觸發程式提供 HTTP Webhook，可叫用以手動觸發函式。 在下列案例中，這非常有用。

  • 整合測試
  • 位置交換作為煙霧測試或熱身活動的一部分
  • 函式的初始部署，以立即填入資料庫中的快取或查閱數據表

如需如何手動叫用定時器觸發函式的詳細資訊，請參閱手動執行非 HTTP 觸發函式。

疑難排解

如需定時器觸發程式未如預期般運作時該怎麼辦的資訊，請參閱 調查並報告定時器觸發函式未引發的問題。

下一步

移至使用定時器觸發程式的快速入門

深入瞭解 Azure Functions 觸發程式和系結