Gatilho de temporizador para o Azure FunctionsTimer trigger for Azure Functions

Este artigo explica como trabalhar com gatilhos de temporizador no Azure Functions.This article explains how to work with timer triggers in Azure Functions. Um gatilho de temporizador permite executar uma função em uma agenda.A timer trigger lets you run a function on a schedule.

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

Pacotes - Functions 1. xPackages - Functions 1.x

O gatilho de timer é fornecido no Microsoft.Azure.WebJobs.Extensions pacote 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 do pacote está no repositório GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

O suporte para essa associação é fornecido automaticamente em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Você não precisa instalar o pacote ou registrar a extensão manualmente.You don't have to manually install the package or register the extension.

Pacotes - Functions 2. xPackages - Functions 2.x

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

O suporte para essa associação é fornecido automaticamente em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Você não precisa instalar o pacote ou registrar a extensão manualmente.You don't have to manually install the package or register the extension.

ExemploExample

O exemplo a seguir mostra uma C# função que é executada cada vez que os minutos têm um valor divisível por cinco (por exemplo, se a função começar em 18:57:00, o próximo desempenho será em 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 objeto TimerInfo é 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

Em bibliotecas de classes do C#, utilize o atributo TimerTriggerAttribute.In C# class libraries, use the TimerTriggerAttribute.

O construtor do atributo usa a expressão CRON ou um TimeSpan.The attribute's constructor takes a CRON expression or a TimeSpan. Você poderá usar TimeSpan apenas se o aplicativo de função estiver em execução em um Plano do Serviço de Aplicativo.You can use TimeSpan only if the function app is running on an App Service plan. O exemplo a seguir 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 associação que você definir no arquivo function.json e o TimerTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DESCRIÇÃODescription
tipotype n/dn/a Deve ser definido como "timerTrigger".Must be set to "timerTrigger". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/dn/a Deve ser definido como "in".Must be set to "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/dn/a O nome da variável que representa o objeto de temporizador no código de função.The name of the variable that represents the timer object in function code.
scheduleschedule ScheduleExpressionScheduleExpression Um expressão CRON ou um valor TimeSpan.A CRON expression or a TimeSpan value. É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo.A TimeSpan can be used only for a function app that runs on an App Service Plan. Você pode colocar a expressão de agendamento em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo envolvido 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 será invocada quando o runtime for iniciado.If true, the function is invoked when the runtime starts. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade.For example, the runtime starts when the function app wakes up after going idle due to inactivity. Quando o aplicativo de funções é reiniciado devido a alterações de função e quando o aplicativo de funções é dimensionado horizontalmente. Portanto, o runOnStartup deve ser raramente, se já estiver definido como true, especialmente em 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 UseMonitorUseMonitor Definido como true ou false para indicar se o agendamento deve ser monitorado.Set to true or false to indicate whether the schedule should be monitored. Agendar o monitoramento persiste as ocorrências de agendamento para ajudar a garantir que o agendamento seja mantido corretamente mesmo quando instâncias do aplicativo de função forem reiniciadas.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 será true para agendas que têm um intervalo de recorrência maior 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 agendamentos que disparam mais de uma vez por minuto, o padrão é false.For schedules that trigger more than once per minute, the default is false.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Cuidado

Recomendamos a configuração runOnStartup para true em produção.We recommend against setting runOnStartup to true in production. Usar essa configuração faz com que código seja executado em momentos altamente imprevisíveis.Using this setting makes code execute at highly unpredictable times. Em determinadas configurações de produção, essas execuções extras podem resultar em custos significativamente mais altos para aplicativos hospedados em 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 runOnStartup habilitado, o gatilho é invocado sempre que seu aplicativo de funções é dimensionado.For example, with runOnStartup enabled the trigger is invoked whenever your function app is scaled. Verifique se você compreender totalmente o comportamento de produção de suas funções antes de habilitar runOnStartup em produção.Make sure you fully understand the production behavior of your functions before enabling runOnStartup in production.

UsoUsage

Quando uma função de gatilho de temporizador é invocada, um objeto de temporizador é passado para a função.When a timer trigger function is invoked, a timer object is passed into the function. O JSON a seguir é uma representação de exemplo do objeto timer.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 propriedade IsPastDue é true quando a invocação da função atual é posterior ao agendado.The IsPastDue property is true when the current function invocation is later than scheduled. Por exemplo, uma reinicialização do aplicativo de função pode causar a perda de uma invocação.For example, a function app restart might cause an invocation to be missed.

Expressões NCRONTABNCRONTAB expressions

Azure Functions usa a biblioteca NCronTab para interpretar as 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 ela inclui um sexto campo adicional no início a ser usado para a precisão de 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:

DigiteType ExemploExample Quando disparadoWhen triggered
Um valor específicoA specific value "0 5 * * * *""0 5 * * * *" em hh:05:00, em que hh é 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 * * *" em 5:mm: 00 diariamente, em que 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)
Um intervalo (- operador)A range (- operator) "5-7 * * * * *""5-7 * * * * *" em hh:mm:05, hh:mm:06 e hh:mm:07, em que hh é 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 * * * * *" em hh:mm:05, hh:mm:08 e hh:mm:10, em que hh é 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 * * * *" em hh:05:00, hh:10:00, hh:15:00 e assim por diante por meio de hh:55:00, em que hh é cada hora (12 vezes por hora)at hh:05:00, hh:10:00, hh:15:00, and so on through hh:55:00 where hh is every hour (12 times an hour)

Para especificar meses ou dias, você pode usar valores numéricos, nomes ou abreviações de nomes:To specify months or days you can use numeric values, names, or abbreviations of names:

  • Por dias, os valores numéricos são 0 a 6, onde 0 começa com o domingo.For days, the numeric values are 0 to 6 where 0 starts with Sunday.
  • Nomes estão em inglês.Names are in English. Por exemplo, Monday, January.For example: Monday, January.
  • Os nomes não diferenciam maiúsculas de minúsculas.Names are case-insensitive.
  • Os nomes podem ser abreviados.Names can be abbreviated. Três letras é o comprimento de abreviação recomendada.Three letters is the recommended abbreviation length. Por exemplo, Mon, Jan.For example: Mon, Jan.

Exemplos de NCRONTABNCRONTAB examples

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

ExemploExample Quando disparadoWhen triggered
"0 */5 * * * *" uma vez a cada cinco minutosonce every five minutes
"0 0 * * * *" uma vez a 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 entre 9h e 17honce every hour from 9 AM to 5 PM
"0 30 9 * * *" às 9h30 todos os diasat 9:30 AM every day
"0 30 9 * * 1-5" às 9h30 todo dia útilat 9:30 AM every weekday
"0 30 9 * Jan Mon" em 9H30 toda segunda-feira em janeiroat 9:30 AM every Monday in January

NCRONTAB fuso horárioNCRONTAB time zones

Os números em uma expressão CRON se referem a uma hora e uma 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 5 no campo hour se refere a 5h, não cada cinco horas.For example, a 5 in the hour field refers to 5:00 AM, not every 5 hours.

O fuso horário padrão usado com as expressões CRON é a Hora Universal Coordenada (UTC).The default time zone used with the CRON expressions is Coordinated Universal Time (UTC). Para que a expressão CRON se baseie em outro fuso horário, crie uma configuração de aplicativo para o aplicativo de funções denominada WEBSITE_TIME_ZONE.To have your CRON expression based on another time zone, create an app setting for your function app named WEBSITE_TIME_ZONE. Defina o valor para o nome do fuso horário desejado, conforme mostrado no Índice de fuso horário da Microsoft.Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

Por exemplo, a Hora padrão da costa leste dos EUA é UTC-05:00.For example, Eastern Standard Time is UTC-05:00. Para que o gatilho do temporizador seja acionado às 10:00 AM EST todos os dias, use a seguinte expressão NCRONTAB que conta para 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 criar uma configuração de aplicativo para seu aplicativo de funções denominada WEBSITE_TIME_ZONE e definir o valor como Horário padrão da costa leste dos EUA.Or create an app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. Em seguida, usa a seguinte expressão NCRONTAB:Then uses the following NCRONTAB expression:

"0 0 10 * * *"

Quando você usa WEBSITE_TIME_ZONE, o horário é ajustado para as alterações de hora 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

É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo.A TimeSpan can be used only for a function app that runs on an App Service Plan.

Ao contrário de uma expressão CRON, um valor TimeSpan 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 é concluída após a execução por mais tempo do que o intervalo especificado, o temporizador imediatamente chama 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 cadeia de caracteres, o formato TimeSpan é hh:mm:ss quando hh é menor que 24.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 superior, o formato é dd:hh:mm.When the first two digits are 24 or greater, the format is dd:hh:mm. Estes são alguns exemplos:Here are some examples:

ExemploExample Quando disparadoWhen triggered
"01:00:00""01:00:00" a cada horaevery hour
"00:01:00""00:01:00" a cada minutoevery minute
"24:00:00""24:00:00" a cada 24 horasevery 24 hours
"1,00:00:00""1.00:00:00" Todos os diasevery day

EscalabilidadeScale-out

Se um aplicativo de funções se expandir para várias instâncias, apenas uma única instância de uma função disparada por temporizador será 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.

Armazenamento de compartilhamento de aplicativos de funçãoFunction apps sharing Storage

Se você estiver compartilhando contas de armazenamento entre aplicativos de funções que não são implantados no serviço de aplicativo, talvez seja necessário atribuir explicitamente a ID do host a cada aplicativo.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 do FunctionsFunctions version ConfiguraçãoSetting
2. x2.x AzureFunctionsWebHost__hostid variável de ambienteAzureFunctionsWebHost__hostid environment variable
1.x1.x id no host. JSONid in host.json

Você pode omitir o valor de identificação ou definir manualmente cada aplicativo de função que identifica a configuraçã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 de temporizador usa um bloqueio de armazenamento para garantir que haja apenas uma instância de temporizador quando um aplicativo de funções é dimensionado para 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 dois aplicativos de funções compartilharem a mesma configuração de identificação e cada um usar um gatilho de temporizador, apenas um temporizador será executado.If two function apps share the same identifying configuration and each uses a timer trigger, only one timer runs.

Tentar comportamento novamenteRetry behavior

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

Solucionando problemasTroubleshooting

Para obter informações sobre o que fazer quando o gatilho de timer não funcionar conforme o esperado, confira Investigar e relatar problemas com funções disparadas de timer não acionadas.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.

Próximas etapasNext steps