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

發行項
07/03/2024

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

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

Azure Functions 開發人員參考

建立您的第一個函式
C# 開發人員參考：

如需如何手動執行定時器觸發函式的資訊，請參閱手動執行非 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));

[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}");
}

下列範例函式會觸發並每隔五分鐘執行一次。函 @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)

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

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

以下是 Python 程式代碼，其中傳遞至函式的物件類型為 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)

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

模型 v4
模型 v3

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 函式。

模型 v4
模型 v3

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

以下是 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);   
};

以下是 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組態檔。

隔離式背景工作角色模型
內含式模型

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

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

裝飾項目

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

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

屬性	說明
`arg_name`	代表函式程式碼中計時器物件的變數名稱。
`schedule`	NCRONTAB 運算式或 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 程式設計模型。

模型 v4
模型 v3

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

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

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

屬性	描述
type	必須設定為「timerTrigger」。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為「in」。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中計時器物件的變數名稱。
schedule	NCRONTAB 運算式或 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	NCRONTAB 運算式或 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 * * *`	每隔 5 分鐘一次
`0 0 * * * *`	每小時開始時一次
`0 0 /2 * *`	每隔 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 運算式同時 支援五個字段 和 六個字段 格式。第六個字段位置是一個秒的值，放在表達式的開頭。如果CRON表達式無效，則 Azure 入口網站函式測試會顯示 404 錯誤，如果 Application Insights 已連接更多詳細數據，則會記錄在那裡。

NCRONTAB 時區

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

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

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

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

注意

在使用量方案中於 Linux 上執行時，目前不支援 WEBSITE_TIME_ZONE 和 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 方案上執行的函式應用程式。

不同於 NCRONTAB 運算式，值 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 觸發程式和系結

共用方式為

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

範例

屬性

裝飾項目

註釋

組態

使用方式

NCRONTAB 運算式

NCRONTAB 範例

NCRONTAB 時區

TimeSpan

向外延展

重試行為

手動叫用定時器觸發程式

疑難排解

下一步

意見反應

其他資源