Gatilho do temporizador para funções azureTimer trigger for Azure Functions

Este artigo explica como trabalhar com gatilhos temporizadores nas Funções Azure.This article explains how to work with timer triggers in Azure Functions. Um gatilho do temporizador permite-lhe executar uma função num horário.A timer trigger lets you run a function on a schedule.

Esta é uma informação de referência para desenvolvedores de Funções Azure.This is reference information for Azure Functions developers. Se for novo nas Funções Azure, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Pacotes - Funções 1.xPackages - Functions 1.x

O gatilho do temporizador é fornecido no pacote Microsoft.Azure.WebJobs.Extensions NuGet, versão 2.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 2.x. O código fonte para o pacote está no repositório GitHub-extensões azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

O apoio a esta encadernação é automaticamente prestado em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Não tem de instalar manualmente a embalagem ou registar a extensão.You don't have to manually install the package or register the extension.

Pacotes - Funções 2.x e superioresPackages - Functions 2.x and higher

O gatilho do temporizador é fornecido no pacote Microsoft.Azure.WebJobs.Extensions NuGet, versão 3.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 3.x. O código fonte para o pacote está no repositório GitHub-extensões azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

O apoio a esta encadernação é automaticamente prestado em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Não tem de instalar manualmente a embalagem ou registar a extensão.You don't have to manually install the package or register the extension.

ExemploExample

O exemplo seguinte mostra uma função C# que é executada cada vez que as atas têm um valor divisível por cinco (por exemplo, se a função começar às 18:57:00, a próxima performance será às 19:00:00).The following example shows a C# function that is executed each time the minutes have a value divisible by five (eg if the function starts at 18:57:00, the next performance will be at 19:00:00). O TimerInfo objeto é passado para a função.The TimerInfo object is passed into the function.

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

Atributos e anotaçõesAttributes and annotations

Nas bibliotecas da classe C#,utilize o TimerTriggerAttribute.In C# class libraries, use the TimerTriggerAttribute.

O construtor do atributo tem uma TimeSpanexpressão CRON ou um .The attribute's constructor takes a CRON expression or a TimeSpan. Só pode TimeSpan utilizar se a aplicação de funções estiver a funcionar num plano de Serviço de Aplicações.You can use TimeSpan only if the function app is running on an App Service plan. TimeSpannão é suportado para funções de Consumo ou Premium Elástico.TimeSpan is not supported for Consumption or Elastic Premium Functions.

O exemplo que se segue mostra uma expressão CRON:The following example shows a CRON expression:

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

ConfiguraçãoConfiguration

A tabela a seguir explica as propriedades de configuração de ligação que definiu no ficheiro função.json e no TimerTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

propriedade fun.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype n/dn/a Deve ser definido para "TimerTrigger".Must be set to "timerTrigger". Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.This property is set automatically when you create the trigger in the Azure portal.
direçãodirection n/dn/a Deve ser definido para "in".Must be set to "in". Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename n/dn/a O nome da variável que representa o objeto temporizador no código de função.The name of the variable that represents the timer object in function code.
agendaschedule Expressão de horárioScheduleExpression Uma expressão CRON ou um valor TimeSpan.A CRON expression or a TimeSpan value. A TimeSpan pode ser usado apenas para uma aplicação de função que funciona em um Plano de Serviço de Aplicações.A TimeSpan can be used only for a function app that runs on an App Service Plan. Pode colocar a expressão de horário numa definição de app e % definir esta propriedade para o nome de definição de aplicação envolto em sinais, como neste exemplo: "%ScheduleAppSetting%".You can put the schedule expression in an app setting and set this property to the app setting name wrapped in % signs, as in this example: "%ScheduleAppSetting%".
runOnStartuprunOnStartup RunOnStartupRunOnStartup Se true, a função for invocada quando o tempo de funcionamento começar.If true, the function is invoked when the runtime starts. Por exemplo, o tempo de execução começa quando a aplicação de funções acorda depois de ficar inativa devido à inatividade.For example, the runtime starts when the function app wakes up after going idle due to inactivity. quando a aplicação de função recomeçar devido a alterações de função, e quando a aplicação de função se esescala. Assim, runOnStartup raramente deve ser truedefinido para , especialmente na produção.when the function app restarts due to function changes, and when the function app scales out. So runOnStartup should rarely if ever be set to true, especially in production.
useMonitoruseMonitor Monitor de UtilizaçãoUseMonitor Definir true ou false indicar se o horário deve ser monitorizado.Set to true or false to indicate whether the schedule should be monitored. A monitorização do horário persiste em agendar ocorrências para ajudar a garantir que o horário seja mantido corretamente, mesmo quando as instâncias da aplicação de funções recomeçam.Schedule monitoring persists schedule occurrences to aid in ensuring the schedule is maintained correctly even when function app instances restart. Se não for definido explicitamente, o padrão é true para horários que tenham um intervalo de recorrência superior ou igual a 1 minuto.If not set explicitly, the default is true for schedules that have a recurrence interval greater than or equal to 1 minute. Para horários que disparam mais de falseuma vez por minuto, o padrão é .For schedules that trigger more than once per minute, the default is false.

Quando está a desenvolver-se localmente, as definições de aplicativos vão para o ficheiro local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Atenção

Recomendamos não configurar true runOnStartup para em produção.We recommend against setting runOnStartup to true in production. A utilização desta definição faz com que o código execute em momentos altamente imprevisíveis.Using this setting makes code execute at highly unpredictable times. Em determinadas configurações de produção, estas execuções extra podem resultar em custos significativamente mais elevados para aplicações alojadas nos planos de Consumo.In certain production settings, these extra executions can result in significantly higher costs for apps hosted in Consumption plans. Por exemplo, com o runOnStartup ativado o gatilho é invocado sempre que a sua aplicação de função é dimensionada.For example, with runOnStartup enabled the trigger is invoked whenever your function app is scaled. Certifique-se de que compreende completamente o comportamento de produção das suas funções antes de ativar a runOnStartup em produção.Make sure you fully understand the production behavior of your functions before enabling runOnStartup in production.

UtilizaçãoUsage

Quando uma função de gatilho do temporizador é invocada, um objeto temporizador é passado para a função.When a timer trigger function is invoked, a timer object is passed into the function. O seguinte JSON é uma representação exemplo do objeto temporizador.The following JSON is an example representation of the timer object.

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

A IsPastDue propriedade true é quando a invocação da função atual é mais tarde do que o previsto.The IsPastDue property is true when the current function invocation is later than scheduled. Por exemplo, um reinício de uma aplicação de função pode causar a falta de uma invocação.For example, a function app restart might cause an invocation to be missed.

Expressões NCRONTABNCRONTAB expressions

A Azure Functions utiliza a biblioteca NCronTab para interpretar expressões NCRONTAB.Azure Functions uses the NCronTab library to interpret NCRONTAB expressions. Uma expressão NCRONTAB é semelhante a uma expressão CRON, exceto que inclui um sexto campo adicional no início da utilização para a precisão do tempo em segundos:An NCRONTAB expression is similar to a CRON expression except that it includes an additional sixth field at the beginning to use for time precision in seconds:

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

Cada campo pode ter um dos seguintes tipos de valores:Each field can have one of the following types of values:

TipoType ExemploExample Quando desencadeadoWhen triggered
Um valor específicoA specific value "0 5 * * * *""0 5 * * * *" em hh:05:00 onde hh é a cada hora (uma vez por hora)at hh:05:00 where hh is every hour (once an hour)
Todos os*valores ()All values (*) "0 * 5 * * *""0 * 5 * * *" às 5:mm:00 todos os dias, onde mm é cada minuto da hora (60 vezes por dia)at 5:mm:00 every day, where mm is every minute of the hour (60 times a day)
Uma gama- (operador)A range (- operator) "5-7 * * * * *""5-7 * * * * *" hh:mm:05,hh:mm:06, e hh:mm:07 onde hh:mm é cada minuto de cada hora (3 vezes por minuto)at hh:mm:05,hh:mm:06, and hh:mm:07 where hh:mm is every minute of every hour (3 times a minute)
Um conjunto de, valores (operador)A set of values (, operator) "5,8,10 * * * * *""5,8,10 * * * * *" hh:mm:05,hh:mm:08, e hh:mm:10 onde hh:mm é cada minuto de cada hora (3 vezes por minuto)at hh:mm:05,hh:mm:08, and hh:mm:10 where hh:mm is every minute of every hour (3 times a minute)
Um valor/ de intervalo (operador)An interval value (/ operator) "0 */5 * * * *""0 */5 * * * *" hh:00:00, hh:05:00, hh:10:00, e assim por diante através de hh:55:00 onde hh é a cada hora (12 vezes por hora)at hh:00:00, hh:05:00, hh:10:00, and so on through hh:55:00 where hh is every hour (12 times an hour)

Para especificar meses ou dias pode utilizar valores numéricos, nomes ou abreviaturas de nomes:To specify months or days you can use numeric values, names, or abbreviations of names:

  • Durante dias, os valores numéricos são de 0 a 6 onde 0 começa com domingo.For days, the numeric values are 0 to 6 where 0 starts with Sunday.
  • Os nomes estão em inglês.Names are in English. Por exemplo: Monday, January.For example: Monday, January.
  • Os nomes são insensíveis aos casos.Names are case-insensitive.
  • Os nomes podem ser abreviados.Names can be abbreviated. Três letras é o comprimento recomendado de abreviatura.Three letters is the recommended abbreviation length. Por exemplo: Mon, Jan.For example: Mon, Jan.

Exemplos ncrontabNCRONTAB examples

Aqui estão alguns exemplos de expressões NCRONTAB que pode usar para o gatilho do temporizador nas Funções Azure.Here are some examples of NCRONTAB expressions you can use for the timer trigger in Azure Functions.

ExemploExample Quando desencadeadoWhen triggered
"0 */5 * * * *" uma vez a cada cinco minutosonce every five minutes
"0 0 * * * *" uma vez no topo de cada horaonce at the top of every hour
"0 0 */2 * * *" uma vez a cada duas horasonce every two hours
"0 0 9-17 * * *" uma vez a cada hora das 9:00 às 17:00once every hour from 9 AM to 5 PM
"0 30 9 * * *" às 9:30 da manhã todos os diasat 9:30 AM every day
"0 30 9 * * 1-5" às 9:30 da manhã todos os dias da semanaat 9:30 AM every weekday
"0 30 9 * Jan Mon" às 9:30 am todas as segundas-feiras em janeiroat 9:30 AM every Monday in January

Fusos horários NCRONTABNCRONTAB time zones

Os números numa expressão CRON referem-se a uma data e data, não a um período de tempo.The numbers in a CRON expression refer to a time and date, not a time span. Por exemplo, um hour 5 no campo refere-se às 5:00 da manhã, não a cada 5 horas.For example, a 5 in the hour field refers to 5:00 AM, not every 5 hours.

O fuso horário predefinido utilizado com as expressões CRON é o Tempo Universal Coordenado (UTC).The default time zone used with the CRON expressions is Coordinated Universal Time (UTC). Para ter a expressão CRON baseada noutro fuso horário, WEBSITE_TIME_ZONEcrie uma definição de aplicação para a sua aplicação de função chamada .To have your CRON expression based on another time zone, create an app setting for your function app named WEBSITE_TIME_ZONE. Detete o valor para o nome do fuso horário desejado, como mostrado no Índice de Fuso Horárioda Microsoft .Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

Nota

WEBSITE_TIME_ZONEnão é atualmente apoiado no plano de consumo linux.WEBSITE_TIME_ZONE is not currently supported on the Linux Consumption plan.

Por exemplo, o Horário Padrão Oriental é UTC-05:00.For example, Eastern Standard Time is UTC-05:00. Para que o seu temporizador dispare às 10:00 EST todos os dias, use a seguinte expressão NCRONTAB que explica o fuso horário UTC:To have your timer trigger fire at 10:00 AM EST every day, use the following NCRONTAB expression that accounts for UTC time zone:

"0 0 15 * * *"

Ou crie uma definição WEBSITE_TIME_ZONE de aplicação para a sua aplicação de função nomeada e defina o valor para o Tempo Padrão Oriental.Or create an app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. Em seguida, utiliza a seguinte expressão NCRONTAB:Then uses the following NCRONTAB expression:

"0 0 10 * * *"

Quando utilizar WEBSITE_TIME_ZONE, o tempo é ajustado para alterações de tempo no fuso horário específico, como o horário de verão.When you use WEBSITE_TIME_ZONE, the time is adjusted for time changes in the specific timezone, such as daylight savings time.

TimeSpanTimeSpan

A TimeSpan pode ser usado apenas para uma aplicação de função que funciona em um Plano de Serviço de Aplicações.A TimeSpan can be used only for a function app that runs on an App Service Plan.

Ao contrário de TimeSpan uma expressão CRON, um valor especifica o intervalo de tempo entre cada invocação de função.Unlike a CRON expression, a TimeSpan value specifies the time interval between each function invocation. Quando uma função completa após o tempo de execução mais longo do que o intervalo especificado, o temporizador invoca imediatamente a função novamente.When a function completes after running longer than the specified interval, the timer immediately invokes the function again.

Expresso como uma TimeSpan corda, hh:mm:ss hh o formato é quando tem menos de 24 anos.Expressed as a string, the TimeSpan format is hh:mm:ss when hh is less than 24. Quando os dois primeiros dígitos são 24 ou mais, o formato é dd:hh:mm.When the first two digits are 24 or greater, the format is dd:hh:mm. Eis alguns exemplos:Here are some examples:

ExemploExample Quando desencadeadoWhen triggered
"01:00:00""01:00:00" a cada horaevery hour
"00:01:00""00:01:00" cada minutoevery minute
"24:00:00""24:00:00" a cada 24 diasevery 24 days
"1.00:00:00""1.00:00:00" Todos os diasevery day

AumentarScale-out

Se uma aplicação de função se dimensionar para várias instâncias, apenas uma instância de uma função acionada pelo temporizador é executada em todas as instâncias.If a function app scales out to multiple instances, only a single instance of a timer-triggered function is run across all instances.

Aplicativos de função que partilham armazenamentoFunction apps sharing Storage

Se estiver a partilhar contas de armazenamento através de aplicações de funções que não estejam implementadas para o serviço de aplicações, poderá ter de atribuir explicitamente o ID do anfitrião a cada aplicação.If you are sharing storage accounts across function apps that are not deployed to app service, you might need to explicitly assign host ID to each app.

Versão funçõesFunctions version DefiniçãoSetting
2.x (e superior)2.x (and higher) AzureFunctionsWebHost__hostidvariável ambienteAzureFunctionsWebHost__hostid environment variable
1.x1.x idem host.jsonid in host.json

Pode omitir o valor de identificação ou definir manualmente a configuração de identificação de cada aplicação de função para um valor diferente.You can omit the identifying value or manually set each function app's identifying configuration to a different value.

O gatilho do temporizador utiliza um bloqueio de armazenamento para garantir que só existe uma instância temporizador quando uma aplicação de função se baseia em várias instâncias.The timer trigger uses a storage lock to ensure that there is only one timer instance when a function app scales out to multiple instances. Se duas aplicações de função partilharem a mesma configuração de identificação e cada uma usar um gatilho temporizador, apenas um temporizador corre.If two function apps share the same identifying configuration and each uses a timer trigger, only one timer runs.

Comportamento de retryRetry behavior

Ao contrário do gatilho da fila, o gatilho do temporizador não se retenta depois de uma função falhar.Unlike the queue trigger, the timer trigger doesn't retry after a function fails. Quando uma função falha, não é chamada novamente até à próxima vez na agenda.When a function fails, it isn't called again until the next time on the schedule.

Resolução de problemasTroubleshooting

Para obter informações sobre o que fazer quando o gatilho do temporizador não funciona como esperado, consulte questões de investigação e reporte com funções acionadas pelo temporizador que não disparam.For information about what to do when the timer trigger doesn't work as expected, see Investigating and reporting issues with timer triggered functions not firing.

Passos seguintesNext steps