Gatilho de temporizador para o Azure Functions
Este artigo explica como trabalhar com gatilhos de temporizador no Azure Functions. Um gatilho de temporizador permite executar uma função em uma agenda.
Essas são as informações de referência para desenvolvedores do Azure Functions. Se for novo no Azure Functions, comece com os seguintes recursos:
Referências para desenvolvedores C#:
Para obter informações sobre como executar manualmente uma função acionada por temporizador, consulte Executar manualmente uma função não acionada por HTTP.
O suporte para essa associação é fornecido automaticamente em todos os ambientes de desenvolvimento. Você não precisa instalar o pacote ou registrar a extensão manualmente.
O código-fonte do pacote de extensão do temporizador está no repositório GitHub azure-webjobs-sdk-extensions.
Importante
Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como funciona o modelo v4, consulte o Guia do desenvolvedor do Node.js para o Azure Functions. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.
O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.
O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.
Este artigo dá suporte a ambos os modelos de programação.
Exemplo
Este exemplo mostra uma função C# que é executada cada vez que os minutos têm um valor divisível por cinco. Por exemplo, quando a função começa às 18:55:00, a próxima execução é às 19:00:00. O objeto TimerInfo
é passado para a função.
A função C# pode ser criada por meio de um dos seguintes modos C#:
- Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces
Microsoft.Azure.Functions.Worker.Extensions.*
. - Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções dentro do processo usam namespaces
Microsoft.Azure.WebJobs.Extensions.*
.
Importante
O suporte terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.
//<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));
A função de exemplo a seguir é disparada e executada a cada cinco minutos. A anotação @TimerTrigger
na função define o agendamento usando o mesmo formato de cadeia de caracteres que as @TimerTrigger
.
@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);
}
O exemplo a seguir mostra uma associação de gatilho de temporizador e um código de função que usa a associação, em que uma instância que representa o temporizador é passada para a função. A função grava um log que indica se esta chamada de função deve-se a uma ocorrência de agendamento ausente. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.
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)
O exemplo a seguir mostra uma função TypeScript de gatilho de temporizador.
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,
});
O exemplo a seguir mostra uma função JavaScript do gatilho de temporizador.
Aqui estão os dados de associação no arquivo function.json:
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
A seguir está o código de função do temporizador no arquivo 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"
Atributos
Em processo A biblioteca C# usa TimerTriggerAttribute do Microsoft.Azure.WebJobs.Extensions, enquanto a biblioteca C# do processo de trabalho isolado usa TimerTriggerAttribute do Microsoft.Azure.Functions.Worker.Extensions.Timer para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json.
Propriedade de atributo | Descrição |
---|---|
Agenda | Um expressão CRON ou um valor TimeSpan. É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo. 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 %ScheduleAppSetting% . |
runOnStartup | Se true , a função será invocada quando o runtime for iniciado. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade. quando o aplicativo de funções é reiniciado devido a alterações de função e quando o aplicativo de funções é escalado horizontalmente. Use com cuidado. RunOnStartup raramente deve ser definido como true , especialmente na produção. |
UseMonitor | Definido como true ou false para indicar se o agendamento deve ser monitorado. 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. Se não for definido explicitamente, o padrão será true para agendamentos que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendamentos que disparam mais de uma vez por minuto, o padrão é false . |
Decoradores
Aplica-se somente ao modelo de programação v2 do Python.
Para funções do Python v2 definidas usando um decorador, as seguintes propriedades no schedule
:
Propriedade | DESCRIÇÃO |
---|---|
arg_name |
O nome da variável que representa o objeto de temporizador no código de função. |
schedule |
Uma expressão NCRONTAB ou um valor TimeSpan . É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo. 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%". |
run_on_startup |
Se true , a função será invocada quando o runtime for iniciado. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade. Quando o aplicativo de função reinicia devido a alterações de função e quando o aplicativo de função é escalado horizontalmente. Use com cuidado. runOnStartup deve raramente ou nunca ser definido como true , especialmente em produção. |
use_monitor |
Definido como true ou false para indicar se o agendamento deve ser monitorado. 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. Se não for definido explicitamente, o padrão será true para agendamentos que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendamentos que disparam mais de uma vez por minuto, o padrão é false . |
Para funções do Python definidas usando o function.json, confira a seção Configuração.
Anotações
A anotação @TimerTrigger
na função define o schedule
usando o mesmo formato de cadeia de caracteres que as expressões CRON. Essa anotação é compatível com as seguintes configurações:
Configuração
Aplica-se apenas ao modelo de programação v1 do Python.
A tabela a seguir explica as propriedades que você pode definir no objeto options
transmitido para o método app.timer()
.
Propriedade | Descrição |
---|---|
schedule | Uma expressão NCRONTAB ou um valor TimeSpan . É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo. 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%". |
runOnStartup | Se true , a função será invocada quando o runtime for iniciado. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade. Quando o aplicativo de função reinicia devido a alterações de função e quando o aplicativo de função é escalado horizontalmente. Use com cuidado. runOnStartup deve raramente ou nunca ser definido como true , especialmente em produção. |
useMonitor | Definido como true ou false para indicar se o agendamento deve ser monitorado. 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. Se não for definido explicitamente, o padrão será true para agendamentos que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendamentos que disparam mais de uma vez por minuto, o padrão é false . |
A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.
Propriedade function.json | Descrição |
---|---|
tipo | Deve ser definido como "timerTrigger". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. |
direction | Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. |
name | O nome da variável que representa o objeto de temporizador no código de função. |
schedule | Uma expressão NCRONTAB ou um valor TimeSpan . É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo. 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%". |
runOnStartup | Se true , a função será invocada quando o runtime for iniciado. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade. Quando o aplicativo de função reinicia devido a alterações de função e quando o aplicativo de função é escalado horizontalmente. Use com cuidado. runOnStartup deve raramente ou nunca ser definido como true , especialmente em produção. |
useMonitor | Definido como true ou false para indicar se o agendamento deve ser monitorado. 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. Se não for definido explicitamente, o padrão será true para agendamentos que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendamentos que disparam mais de uma vez por minuto, o padrão é false . |
Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values
.
Cuidado
Não defina runOnStartup como true
em produção. Usar essa configuração faz com que código seja executado em momentos altamente imprevisíveis. Em determinadas configurações de produção, essas execuções extras podem resultar em custos significativamente mais altos para aplicativos hospedados em um plano de consumo. Por exemplo, com runOnStartup habilitado, o gatilho é invocado sempre que seu aplicativo de funções é dimensionado. Verifique se você compreender totalmente o comportamento de produção de suas funções antes de habilitar runOnStartup em produção.
Consulte a Seção de exemplo para obter exemplos completos.
Uso
Quando uma função de gatilho de temporizador é invocada, um objeto de temporizador é passado para a função. O JSON a seguir é uma representação de exemplo do objeto timer.
{
"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
}
A propriedade isPastDue
é true
quando a invocação da função atual é posterior ao agendado. Por exemplo, uma reinicialização do aplicativo de função pode causar a perda de uma invocação.
Expressões NCRONTAB
O Azure Functions usa a biblioteca NCronTab para interpretar as expressões NCRONTAB. 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:
{second} {minute} {hour} {day} {month} {day-of-week}
Cada campo pode ter um dos seguintes tipos de valores:
Type | Exemplo | Quando disparado |
---|---|---|
Um valor específico | 0 5 * * * * |
Uma vez a cada hora do dia, no minuto 5 de cada hora |
Todos os valores (* ) |
0 * 5 * * * |
A cada minuto na hora, durante a hora 5 |
Um intervalo (- operador) |
5-7 * * * * * |
Três vezes por minuto nos segundos de 5 a 7 durante cada minuto de cada hora de cada dia |
Um conjunto de valores (, operador) |
5,8,10 * * * * * |
Três vezes por minuto nos segundos 5, 8 e 10 durante cada minuto de cada hora de cada dia |
Um valor de intervalo (/ operador) |
0 */5 * * * * |
12 vezes por hora no segundo 0 de cada quinto minuto de cada hora de cada dia |
Para especificar meses ou dias, você pode usar valores numéricos, nomes ou abreviações de nomes:
- Para dias, os valores numéricos são de 0 a 6, onde 0 começa com domingo.
- Nomes estão em inglês. Por exemplo,
Monday
,January
. - Os nomes não diferenciam maiúsculas de minúsculas.
- Os nomes podem ser abreviados. Recomendamos usar três letras para abreviações. Por exemplo,
Mon
,Jan
.
Exemplos de NCRONTAB
Aqui estão alguns exemplos de expressões NCRONTAB, que você pode usar para o gatilho de temporizador no Azure Functions.
Exemplo | Quando disparado |
---|---|
0 */5 * * * * |
uma vez a cada cinco minutos |
0 0 * * * * |
uma vez a cada hora |
0 0 */2 * * * |
uma vez a cada duas horas |
0 0 9-17 * * * |
uma vez a cada hora entre 9h e 17h |
0 30 9 * * * |
às 9h30 todos os dias |
0 30 9 * * 1-5 |
às 9h30 todo dia útil |
0 30 9 * Jan Mon |
em 9H30 toda segunda-feira em janeiro |
Observação
A expressão NCRONTAB dá suporte aos formatos de cinco campos e seis campos. A sexta posição do campo é um valor para segundos que é colocado no início da expressão. Se a expressão CRON for inválida, o Teste de Função do Portal do Azure exibirá um erro 404, se o Application Insights estiver conectado, mais detalhes serão registrados lá.
Fusos horários NCRONTAB
Os números em uma expressão NCRONTAB referem-se a uma hora e data, não a um intervalo de tempo. Por exemplo, um 5 no campo hour
se refere a 5h, não cada cinco horas.
O fuso horário padrão usado com as expressões CRON é a Hora Universal Coordenada (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
.
O valor dessa configuração depende do sistema operacional e do plano no qual seu aplicativo de funções é executado.
Sistema operacional | Plano | Valor |
---|---|---|
Windows | Tudo | Defina o valor para o nome do fuso horário desejado, conforme fornecido pela segunda linha de cada par fornecido pelo comando do Windowstzutil.exe /L |
Linux | Premium Dedicado |
Defina o valor como o nome do fuso horário desejado, conforme mostrado no banco de dados tz. |
Observação
No momento, não há suporte para WEBSITE_TIME_ZONE
e TZ
durante a execução no Linux em um plano de Consumo. Nesse caso, definir WEBSITE_TIME_ZONE
ou TZ
pode criar problemas relacionados ao SSL e fazer com que as métricas parem de funcionar para seu aplicativo.
Por exemplo, o horário do leste dos EUA (representado por Eastern Standard Time
(Windows) ou America/New_York
(Linux)) atualmente usa UTC-05: 00 durante o horário padrão e UTC-04:00 durante o dia. Para que um acionador de cronômetro seja disparado às 10:00, horário do leste dos EUA, todos os dias, crie uma configuração de aplicativo para seu aplicativo de funções chamado WEBSITE_TIME_ZONE
, defina o valor como Eastern Standard Time
(Windows) ou America/New_York
(Linux) e, em seguida, use a seguinte expressão NCRONTAB:
"0 0 10 * * *"
Quando você usa WEBSITE_TIME_ZONE
, o horário é ajustado para alterações de horário no fuso horário específico, incluindo horário de verão e alterações no horário padrão.
TimeSpan
É possível usar um TimeSpan
somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo.
Ao contrário de uma expressão NCRONTAB, um TimeSpan
valor especifica o intervalo de tempo entre cada chamada de função. 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.
Expresso como uma cadeia de caracteres, o formato TimeSpan
é hh:mm:ss
quando hh
é menor que 24. Quando os dois primeiros dígitos são 24 ou superior, o formato é dd:hh:mm
. Estes são alguns exemplos:
Exemplo | Quando disparado |
---|---|
"01:00:00" | a cada hora |
"00:01:00" | a cada minuto |
"25:00:00:00" | a cada 25 dias |
"1.00:00:00" | todos os dias |
Escalabilidade horizontal
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. Ele não será acionado novamente se houver uma invocação pendente ainda em execução.
Armazenamento de compartilhamento de aplicativos de função
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.
Versão do Functions | Configuração |
---|---|
2. x (e superior) | A variável de ambiente AzureFunctionsWebHost__hostid |
1.x | id em id |
Você pode omitir o valor identificador ou definir manualmente cada aplicativo de funções identificando a configuração a um valor diferente.
O gatilho de temporizador usa um bloqueio de armazenamento para garantir que haverá apenas uma instância de temporizador quando um aplicativo de funções escalar horizontalmente para várias instâncias. Se dois aplicativos de funções compartilharem a mesma configuração identificadora e cada um usar um gatilho de temporizador, somente um temporizador será executado.
Tentar comportamento novamente
Ao contrário do gatilho de fila, o gatilho de temporizador não tenta novamente após a falha de uma função. Quando uma função falha, ele não é chamado novamente até a próxima vez na agenda.
Invocar manualmente um gatilho de temporizador
O gatilho de temporizador para Azure Functions fornece um webhook HTTP que pode ser invocado para disparar a função manualmente. Isso pode ser muito útil nos seguintes cenários:
- Teste de integração
- Trocas de slot como parte de uma atividade de teste de aceitação do build ou aquecimento
- Implantação inicial de uma função para popular imediatamente um cache ou uma tabela de pesquisa em um banco de dados
Consulte exectutar manualmente uma função não disparada por http para obter detalhes sobre como invocar manualmente uma função disparada por temporizador.
Solução de problemas
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.