本文介绍如何在 Azure Functions 中使用计时器触发器。 计时器触发器可以按计划运行函数。
此参考信息面向 Azure Functions 开发人员。 Azure Functions 的新手请从以下资源入手:
- 创建第一个函数:C#、JavaScriptJava 或 Python。
- Azure Functions 开发人员参考。
- 特定语言参考:C#、C# 脚本、F#、Java、JavaScript 或 Python。
- Azure Functions 触发器和绑定概念。
- 在本地对 Azure Functions 进行编码和测试。
若要了解如何手动运行计时器触发的函数,请参阅手动运行非 HTTP 触发的函数。
包 - Functions 2.x 及更高版本
Microsoft.Azure.WebJobs.Extensions NuGet 包 3.x 版中提供了计时器触发器。 azure-webjobs-sdk-extensions GitHub 存储库中提供了此包的源代码。
在所有开发环境中自动提供对该绑定的支持。 无需手动安装包或注册扩展。
包 - Functions 1.x
Microsoft.Azure.WebJobs.Extensions NuGet 包 2.x 版中提供了计时器触发器。 azure-webjobs-sdk-extensions GitHub 存储库中提供了此包的源代码。
在所有开发环境中自动提供对该绑定的支持。 无需手动安装包或注册扩展。
示例
C#
以下示例显示了一个 C# 函数,每当分钟的值可被 5 整除时,就执行该函数(例如,如果函数起始于 18:57:00,则下一次执行函数的时间为 19:00:00)。 TimerInfo 对象将传递到函数中。
[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}");
}
C# 脚本
以下示例演示 function.json 文件中的一个计时器触发器绑定以及使用该绑定的 C# 脚本函数。 该函数将写入日志信息,指示调用此函数是由于错过了计划发生时间。 TimerInfo 对象将传递到函数中。
下面是 function.json 文件中的绑定数据:
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
C# 脚本代码如下所示:
public static void Run(TimerInfo myTimer, ILogger log)
{
if (myTimer.IsPastDue)
{
log.LogInformation("Timer is running late!");
}
log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}" );
}
Java
以下示例函数的触发和执行间隔为 5 分钟。 函数上的 @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);
}
JavaScript
以下示例演示 function.json 文件中的一个计时器触发器绑定以及使用该绑定的 JavaScript 函数。 该函数将写入日志信息,指示调用此函数是由于错过了计划发生时间。 计时器对象将传递到函数中。
下面是 function.json 文件中的绑定数据:
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
JavaScript 代码如下所示:
module.exports = 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);
context.done();
};
PowerShell
下面的示例演示如何在 PowerShell中配置计时器触发器的 function.js 和 run.ps1 文件。
{
"bindings": [
{
"name": "Timer",
"type": "timerTrigger",
"direction": "in",
"schedule": "0 */5 * * * *"
}
]
}
# Input bindings are passed in via param block.
param($Timer)
# 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 ($Timer.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"
计时器对象的实例将作为第一个参数传递给函数。
Python
以下示例使用计时器触发器绑定,其配置在 function.json 文件中进行了描述。 使用绑定的实际 Python 函数在 init.py 文件中进行了描述。 传入函数的对象的类型为 azure.functions.TimerRequest 对象。 函数逻辑将写入日志,以指示当前调用是由于错过了计划发生时间。
下面是 function.json 文件中的绑定数据:
{
"name": "mytimer",
"type": "timerTrigger",
"direction": "in",
"schedule": "0 */5 * * * *"
}
下面是 Python 代码:
import datetime
import logging
import azure.functions as func
def main(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)
特性和注释
C#
在 C# 类库中,使用 TimerTriggerAttribute。
该特性的构造函数采用 CRON 表达式或 TimeSpan: 仅当函数应用在应用服务计划中运行时才能使用 TimeSpan。 消耗计划或弹性高级函数不支持 TimeSpan。
以下示例显示了一个 CRON 表达式:
[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}");
}
C# 脚本
C# 脚本不支持特性。
Java
函数上的 @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);
}
JavaScript
JavaScript 不支持特性。
PowerShell
PowerShell 不支持特性。
Python
Python 不支持特性。
配置
下表解释了在 function.json 文件和 TimerTrigger 特性中设置的绑定配置属性。
| function.json 属性 | Attribute 属性 | 说明 |
|---|---|---|
| type | 不适用 | 必须设置为“timerTrigger”。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| direction | 不适用 | 必须设置为“in”。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| name | 不适用 | 在函数代码中表示计时器对象的变量的名称。 |
| schedule | ScheduleExpression | CRON 表达式或 TimeSpan 值。 只能对在应用服务计划中运行的函数应用使用 TimeSpan。 可以将计划表达式放在应用设置中并将此属性设置为用 % 符号括起的应用设置名称,例如此示例中的“%ScheduleAppSetting%”。 |
| runOnStartup | RunOnStartup | 如果为 true,则在运行时启动时调用此函数。 例如,当函数应用从由于无活动而进入的空闲状态醒来后,运行时会启动。 当函数应用由于函数更改而重新启动时,以及当函数应用横向扩展时。因此 runOnStartup 应该很少设置为 true,特别是在生产中。 |
| useMonitor | UseMonitor | 设置为 true 或 false 以指示是否应当监视计划。 计划监视在各次计划发生后会持续存在,以帮助确保即使在函数应用实例重新启动的情况下也能正确维护计划。 如果未显式设置,则对于重复周期间隔大于或等于 1 分钟的计划,默认值为 true。 对于每分钟触发多次的计划,默认值为 false。 |
在本地进行开发时,应用设置将取 local.settings.json 文件的值。
Caution: 在生产中不建议将 runOnStartup 设置为
true。 使用此设置会使代码在非常不可预测的时间执行。 在某些生产设置中,这些额外执行可能会导致消耗计划中托管的应用产生明显更高的成本。 例如,启用 runOnStartup 后,只要缩放函数应用,就会调用触发器。 在生产中启用 runOnStartup 之前,请确保完全了解函数的生产行为。
使用情况
调用计时器触发器函数时,计时器对象将传递到函数中。 以下 JSON 是计时器对象的示例表示形式。
{
"schedule":{
},
"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}
每个字段可以具有下列类型之一的值:
| 类型 | 示例 | 何时触发 |
|---|---|---|
| 一个具体值 | <nobr>0 5 * * * *</nobr> |
每小时的第一天的每小时一次 |
所有值 (*) |
<nobr>0 * 5 * * *</nobr> |
每分钟的时间(从小时5开始) |
一个范围(- 运算符) |
<nobr>5-7 * * * * *</nobr> |
每隔一小时的每分钟在每分钟的第5到7秒的三倍 |
一组值(, 运算符) |
<nobr>5,8,10 * * * * *</nobr> |
每隔一小时的每分钟在每分钟的第5、8和10秒内运行三次 |
一个间隔值(/ 运算符) |
<nobr>0 */5 * * * *</nobr> |
每小时12次,每隔5分钟的第二个小时,每隔一小时 |
若要指定月份或天,可以使用数字值、名称或名称的缩写:
- 对于天,数字值为 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 |
在一月份每星期一的上午 9:30 |
Note: NCRONTAB 表达式需要 六个字段 格式。 第六个字段位置是秒的值,该值置于表达式的开头。 Azure 不支持五字段 cron 表达式。
NCRONTAB 时区
CRON 表达式中的数字指的是时间和日期,而不是时间跨度。 例如,hour 字段中的 5 指的是 5:00 AM,而不是每 5 小时。
CRON 表达式使用的默认时区为协调世界时 (UTC)。 若要让 CRON 表达式基于其他时区,请为你的函数应用创建一个名为 WEBSITE_TIME_ZONE 的应用设置。
此设置的值取决于运行函数应用的操作系统和计划。
| 操作系统 | 计划 | 值 |
|---|---|---|
| Windows | All | 将值设置为所需时区的名称,由 Windows 命令给定的每个对中的第二行给定 tzutil.exe /L |
| Linux | 高级专用 | 将值设置为所需时区的名称,如 tz 数据库中所示。 |
Note: Linux 消耗计划目前不支持
WEBSITE_TIME_ZONE。
例如,美国东部时间 (由 Eastern Standard Time (Windows) 或 (Linux 表示, America/New_York) # A5 目前在标准时间04:00 和在夏令时期间使用 utc-05:00。 若要使计时器触发器每天凌晨10:00 触发,请创建名为的函数应用的应用设置 WEBSITE_TIME_ZONE ,将此值设置为 Eastern Standard Time (Windows) 或 America/New_York (Linux) ,然后使用以下 NCRONTAB 表达式:
"0 0 10 * * *"
当使用 WEBSITE_TIME_ZONE 时间时,将针对特定时区中的时间更改(包括夏令时和标准时间更改)进行调整。
TimeSpan
只能对在应用服务计划中运行的函数应用使用 TimeSpan。
与 CRON 表达式不同,TimeSpan 值指定各次函数调用之间的时间间隔。 如果函数的运行时间超出了指定的时间间隔,则在函数完成时,计时器会立即再次调用该函数。
以字符串表示,当 hh 小于 24 时,TimeSpan 格式为 hh:mm:ss。 当前两个数字是 24 或更大的数字时,格式为 dd:hh:mm。 下面是一些示例:
| 示例 | 何时触发 |
|---|---|
| "01:00:00" | 每小时 |
| "00:01:00" | 每分钟 |
| "24:00:00" | 每 24 天 |
| "1.00:00:00" | 每天 |
横向扩展
如果函数应用横向扩展到多个实例,则在所有实例中只会运行由计时器触发的函数的单个实例。 如果有未完成的调用仍在运行,它将不会再次触发。
共享同一存储的函数应用
如果要在未部署到应用服务的函数应用之间共享存储帐户,则可能需要为每个应用显式分配主机 ID。
| Functions 版本 | 设置 |
|---|---|
| 2.x(及更高版本) | AzureFunctionsWebHost__hostid 环境变量 |
| 1.x | host.json 中的 id |
可以省略标识值,也可以手动将每个函数应用的标识配置设置为不同的值。
计时器触发器使用存储锁来确保当函数应用横向扩展到多个实例时将只有一个计时器实例。 如果两个函数应用共享相同的标识配置,并且每个函数应用都使用一个计时器触发器,则只有一个计时器运行。
重试行为
与队列触发器不同,计时器触发器在函数失败后不会重试。 函数失败时,在计划的下次时间到来前,不会再次调用该函数。
故障排除
有关在计时器触发器未按预期工作的情况下应采取的措施,请参阅调查和报告有关计时器触发功能未触发的问题。
后续步骤
历史资料。此文对应 2022-08-12 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 craigshoemaker)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体、发布器占位标签和导航标记。
