Azure Functions 的計時器觸發程序Timer trigger for Azure Functions

本文說明如何在 Azure Functions 中使用計時器觸發程序。This article explains how to work with timer triggers in Azure Functions. 計時器觸發程序可讓您依照排程執行函式。A timer trigger lets you run a function on a schedule.

這是 Azure Functions 開發人員的參考資訊。This is reference information for Azure Functions developers. 如果您不熟悉 Azure Functions,請從下列資源開始︰If you're new to Azure Functions, start with the following resources:

範例Example

請參閱特定語言的範例:See the language-specific example:

C# 範例C# example

下列範例所示C# 函式執行每隔五分鐘:The following example shows a C# function that runs every five minutes:

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, TraceWriter log)
{
    log.Info($"C# Timer trigger function executed at: {DateTime.Now}");
}

C# 指令碼範例C# script example

下列範例示範 function.json 檔案中的計時器觸發程序繫結,以及使用此繫結的 C# 指令碼函式The following example shows a timer trigger binding in a function.json file and a C# script function that uses the binding. 此函式會寫入一項記錄,指出此函式引動過程是否由遺失的排程項目所造成。The function writes a log indicating whether this function invocation is due to a missed schedule occurrence.

以下是 function.json 檔案中的繫結資料:Here's the binding data in the function.json file:

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

以下是 C# 指令碼程式碼:Here's the C# script code:

public static void Run(TimerInfo myTimer, TraceWriter log)
{
    if(myTimer.IsPastDue)
    {
        log.Info("Timer is running late!");
    }
    log.Info($"C# Timer trigger function executed at: {DateTime.Now}" );  
}

F# 範例F# example

下列範例示範 function.json 檔案中的計時器觸發程序繫結,以及使用此繫結的 F# 指令碼函式The following example shows a timer trigger binding in a function.json file and a F# script function that uses the binding. 此函式會寫入一項記錄,指出此函式引動過程是否由遺失的排程項目所造成。The function writes a log indicating whether this function invocation is due to a missed schedule occurrence.

以下是 function.json 檔案中的繫結資料:Here's the binding data in the function.json file:

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

以下是 F# 指令碼程式碼:Here's the F# script code:

let Run(myTimer: TimerInfo, log: TraceWriter ) =
    if (myTimer.IsPastDue) then
        log.Info("F# function is running late.")
    let now = DateTime.Now.ToLongTimeString()
    log.Info(sprintf "F# function executed at %s!" now)

JavaScript 範例JavaScript example

下列範例示範 function.json 檔案中的計時器觸發程序繫結,以及使用此繫結的 JavaScript 函式The following example shows a timer trigger binding in a function.json file and a JavaScript function that uses the binding. 此函式會寫入一項記錄,指出此函式引動過程是否由遺失的排程項目所造成。The function writes a log indicating whether this function invocation is due to a missed schedule occurrence.

以下是 function.json 檔案中的繫結資料:Here's the binding data in the function.json file:

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

以下是 JavaScript 指令碼程式碼:Here's the JavaScript script code:

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

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

    context.done();
};

屬性Attributes

C# 類別庫,使用TimerTriggerAttribute,NuGet 封裝中已定義Microsoft.Azure.WebJobs.ExtensionsIn C# class libraries, use the TimerTriggerAttribute, defined in NuGet package Microsoft.Azure.WebJobs.Extensions.

該屬性的建構函式會採用 CRON 運算式,如下列範例所示:The attribute's constructor takes a CRON expression, as shown in the following example:

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, TraceWriter log)
{
   ...
}

如果您的函式應用程式在 App Service 方案 (非取用量方案) 上執行,您可以指定 TimeSpan 而不是 CRON 運算式。You can specify a TimeSpan instead of a CRON expression if your function app runs on an App Service plan (not a Consumption plan).

如需完整範例,請參閱C# 範例For a complete example, see C# example.

組態Configuration

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 TimerTrigger 屬性。The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

function.json 屬性function.json property 屬性內容Attribute property 說明Description
typetype n/an/a 必須設定為 "timerTrigger"。Must be set to "timerTrigger". 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a 必須設定為 "in"。Must be set to "in". 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。This property is set automatically when you create the trigger in the Azure portal.
namename n/an/a 代表函式程式碼中計時器物件的變數名稱。The name of the variable that represents the timer object in function code.
scheduleschedule ScheduleExpressionScheduleExpression 在取用量方案中,您可以使用 CRON 運算式來定義排程。On the Consumption plan, you can define schedules with a CRON expression. 如果您使用 App Service 方案,也可以使用 TimeSpan 字串。If you're using an App Service Plan, you can also use a TimeSpan string. 下列各節說明 CRON 運算式。The following sections explain CRON expressions. 您可以將排程運算式放在應用程式設定中,並將此屬性設定為以 % 符號包裝的值,如此範例所示:"%NameOfAppSettingWithCRONExpression%"。You can put the schedule expression in an app setting and set this property to a value wrapped in % signs, as in this example: "%NameOfAppSettingWithCRONExpression%".

當您要在本機開發時,應用程式設定會進入 local.settings.json 檔案When you're developing locally, app settings go into the local.settings.json file.

CRON 格式CRON format

Azure Functions 計時器觸發程序的 CRON 運算式包含下列六個欄位:A CRON expression for the Azure Functions timer trigger includes these six fields:

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

注意

您在線上找到的許多 CRON 運算式會省略 {second} 欄位。Many of the CRON expressions you find online omit the {second} field. 如果您複製其中一個運算式,請新增遺漏的 {second} 欄位。If you copy from one of them, add the missing {second} field.

CRON 時區CRON time zones

CRON 運算式使用的預設時區是國際標準時間 (UTC)。The default time zone used with the CRON expressions is Coordinated Universal Time (UTC). 若要讓 CRON 運算式以另一個時區為基礎,請為名為 WEBSITE_TIME_ZONE 的函式應用程式建立新的應用程式設定。To have your CRON expression based on another time zone, create a new app setting for your function app named WEBSITE_TIME_ZONE. 將值設定為所需的時區名稱,如 Microsoft 時區索引中所示。Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

例如,美加東部標準時間是 UTC-05:00。For example, Eastern Standard Time is UTC-05:00. 若要讓計時器觸發程序在每天上午 10:00 (美加東部標準時間) 觸發,您可以使用說明 UTC 時區的下列 CRON 運算式︰To have your timer trigger fire at 10:00 AM EST every day, use the following CRON expression that accounts for UTC time zone:

"schedule": "0 0 15 * * *",

或者,您可以為名為 WEBSITE_TIME_ZONE 的函式應用程式新增新的應用程式設定,並將值設為美加東部標準時間Alternatively, you could add a new app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. 那麼,下列 CRON 運算式即可用於 EST 上午 10:00:Then the following CRON expression could be used for 10:00 AM EST:

"schedule": "0 0 10 * * *",

CRON 範例CRON examples

以下是您可以在 Azure Functions 中使用於計時器觸發程序的一些 CRON 運算式範例。Here are some examples of CRON expressions you can use for the timer trigger in Azure Functions.

若要每隔 5 分鐘觸發一次︰To trigger once every five minutes:

"schedule": "0 */5 * * * *"

若要在每小時開始時觸發一次︰To trigger once at the top of every hour:

"schedule": "0 0 * * * *",

若要每隔 2 小時觸發一次:To trigger once every two hours:

"schedule": "0 0 */2 * * *",

若要在上午 9 點到下午 5 點之間每隔一小時觸發一次:To trigger once every hour from 9 AM to 5 PM:

"schedule": "0 0 9-17 * * *",

若要在每天上午 9:30 觸發一次:To trigger At 9:30 AM every day:

"schedule": "0 30 9 * * *",

若要在每個工作天上午 9:30 觸發一次:To trigger At 9:30 AM every weekday:

"schedule": "0 30 9 * * 1-5",

使用量Usage

叫用計時器觸發程序函式時,計時器物件會傳遞至函式。When a timer trigger function is invoked, the timer object is passed into the function. 下列 JSON 是計時器物件的範例表示法。The following JSON is an example representation of the timer object.

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

向外延展Scale-out

計時器觸發程序支援多個執行個體向外延展。特定計時器函式的單一執行個體會對所有執行個體執行。The timer trigger supports multi-instance scale-out. A single instance of a particular timer function is run across all instances.

後續步驟Next steps