Gatilho de temporizador para o Azure Functions
Este artigo explica como trabalhar com gatilhos de timer no Azure Functions. Um gatilho de temporizador permite executar uma função em uma agenda.
Estas são informações de referência para desenvolvedores do Azure Functions. Se você é novo no Azure Functions, comece com os seguintes recursos:
Referências do desenvolvedor 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 esta ligação é fornecido automaticamente em todos os ambientes de desenvolvimento. Não é necessário instalar manualmente o pacote ou registrar a extensão.
O código-fonte do pacote de extensão de timer está no repositório GitHub azure-webjobs-sdk-extensions .
Importante
Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.
O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.
O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.
Este artigo suporta ambos os modelos de programação.
Exemplo
Este exemplo mostra uma função C# que é executada sempre 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. Um TimerInfo
objeto é passado para a função.
Uma função C# pode ser criada usando um dos seguintes modos C#:
- Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam
Microsoft.Azure.Functions.Worker.Extensions.*
namespaces. - Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam
Microsoft.Azure.WebJobs.Extensions.*
namespaces.
Importante
O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.
//<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 é acionada e executada a cada cinco minutos. A @TimerTrigger
anotação na função define a agenda usando o mesmo formato de cadeia de caracteres que as expressões 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);
}
O exemplo a seguir mostra uma ligação de gatilho de temporizador e um código de função que usa a ligação, onde uma instância que representa o temporizador é passada para a função. A função grava um log indicando se essa invocação de função é devido a uma ocorrência de agenda perdida. O exemplo depende se você usa o modelo de programação Python v1 ou v2.
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 de gatilho de temporizador.
Aqui estão os dados de ligação no arquivo function.json :
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
A seguir está o código da função de 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
A biblioteca C# em processo usa TimerTriggerAttribute de Microsoft.Azure.WebJobs.Extensions, enquanto a biblioteca C# de processo de trabalho isolado usa TimerTriggerAttribute de 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 Attribute | Description |
---|---|
Schedule | Uma expressão CRON ou um valor TimeSpan . A TimeSpan só pode ser usado para um aplicativo de função executado em um Plano do Serviço de Aplicativo. Você pode colocar a expressão de agenda em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo encapsulado em % sinais, como %ScheduleAppSetting% . |
RunOnStartup | Se true , a função é invocada quando o tempo de execução é iniciado. Por exemplo, o runtime começa quando a aplicação de funções é reativada depois de ficar inativa devido a inatividade. quando o aplicativo de função é reiniciado devido a alterações de função e quando o aplicativo de função é dimensionado. Use com cuidado. RunOnStartup raramente ou nunca deve ser definido como true , especialmente em produção. |
UseMonitor | Defina como true ou false para indicar se o agendamento deve ser monitorizado. A monitorização do agendamento guarda as ocorrências para ajudar a garantir que o agendamento é mantido corretamente, mesmo quando as instâncias da aplicação de funções são reiniciadas. Se não for definido explicitamente, o padrão é true para agendas que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendas que são acionadas mais de uma vez por minuto, o padrão é false . |
Decoradores
Aplica-se apenas ao modelo de programação Python v2.
Para funções Python v2 definidas usando um decorador, as seguintes propriedades no schedule
:
Property | Description |
---|---|
arg_name |
O nome da variável que representa o objeto de temporizador no código da função. |
schedule |
Uma expressão NCRONTAB ou um valor TimeSpan . A TimeSpan só pode ser usado para um aplicativo de função executado em um Plano do Serviço de Aplicativo. Você pode colocar a expressão de agenda em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo encapsulado em % sinais, como neste exemplo: "%ScheduleAppSetting%". |
run_on_startup |
Se true , a função é invocada quando o tempo de execução é iniciado. Por exemplo, o runtime começa quando a aplicação de funções é reativada depois de ficar inativa devido a inatividade. quando o aplicativo de função é reiniciado devido a alterações de função e quando o aplicativo de função é dimensionado. Use com cuidado. runOnStartup raramente ou nunca deve ser definido como true , especialmente em produção. |
use_monitor |
Defina como true ou false para indicar se o agendamento deve ser monitorizado. A monitorização do agendamento guarda as ocorrências para ajudar a garantir que o agendamento é mantido corretamente, mesmo quando as instâncias da aplicação de funções são reiniciadas. Se não for definido explicitamente, o padrão é true para agendas que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendas que são acionadas mais de uma vez por minuto, o padrão é false . |
Para funções Python definidas usando function.json, consulte a seção Configuração .
Anotações
A @TimerTrigger
anotação na função define o schedule
uso do mesmo formato de cadeia de caracteres que as expressões CRON. A anotação suporta as seguintes configurações:
Configuração
Aplica-se apenas ao modelo de programação Python v1.
A tabela a seguir explica as propriedades que você pode definir no options
objeto passado para o app.timer()
método.
Property | Description |
---|---|
schedule | Uma expressão NCRONTAB ou um valor TimeSpan . A TimeSpan só pode ser usado para um aplicativo de função executado em um Plano do Serviço de Aplicativo. Você pode colocar a expressão de agenda em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo encapsulado em % sinais, como neste exemplo: "%ScheduleAppSetting%". |
runOnStartup | Se true , a função é invocada quando o tempo de execução é iniciado. Por exemplo, o runtime começa quando a aplicação de funções é reativada depois de ficar inativa devido a inatividade. quando o aplicativo de função é reiniciado devido a alterações de função e quando o aplicativo de função é dimensionado. Use com cuidado. runOnStartup raramente ou nunca deve ser definido como true , especialmente em produção. |
usarMonitor | Defina como true ou false para indicar se o agendamento deve ser monitorizado. A monitorização do agendamento guarda as ocorrências para ajudar a garantir que o agendamento é mantido corretamente, mesmo quando as instâncias da aplicação de funções são reiniciadas. Se não for definido explicitamente, o padrão é true para agendas que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendas que são acionadas mais de uma vez por minuto, o padrão é false . |
A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .
function.json propriedade | Description |
---|---|
type | Deve ser definido como "timerTrigger". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. |
direção | Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. |
Designação | O nome da variável que representa o objeto de temporizador no código da função. |
schedule | Uma expressão NCRONTAB ou um valor TimeSpan . A TimeSpan só pode ser usado para um aplicativo de função executado em um Plano do Serviço de Aplicativo. Você pode colocar a expressão de agenda em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo encapsulado em % sinais, como neste exemplo: "%ScheduleAppSetting%". |
runOnStartup | Se true , a função é invocada quando o tempo de execução é iniciado. Por exemplo, o runtime começa quando a aplicação de funções é reativada depois de ficar inativa devido a inatividade. quando o aplicativo de função é reiniciado devido a alterações de função e quando o aplicativo de função é dimensionado. Use com cuidado. runOnStartup raramente ou nunca deve ser definido como true , especialmente em produção. |
usarMonitor | Defina como true ou false para indicar se o agendamento deve ser monitorizado. A monitorização do agendamento guarda as ocorrências para ajudar a garantir que o agendamento é mantido corretamente, mesmo quando as instâncias da aplicação de funções são reiniciadas. Se não for definido explicitamente, o padrão é true para agendas que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendas que são acionadas mais de uma vez por minuto, o padrão é false . |
Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values
coleção.
Atenção
Não defina runOnStartup como true
em produção. O uso dessa configuração faz com que o 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ção é dimensionado. Certifique-se de entender completamente o comportamento de produção de suas funções antes de habilitar o runOnStartup na produção.
Consulte a seção Exemplo para obter exemplos completos.
Utilização
Quando uma função de gatilho de temporizador é invocada, um objeto de temporizador é passado para a função. O JSON a seguir é um exemplo de representação 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 isPastDue
propriedade é true
quando a invocação da função atual é posterior ao agendado. Por exemplo, uma reinicialização de aplicativo de função pode fazer com que uma invocação seja perdida.
Expressões NCRONTAB
O Azure Functions usa a biblioteca NCronTab para interpretar expressões NCRONTAB. Uma expressão NCRONTAB é semelhante a uma expressão CRON, exceto que inclui um sexto campo adicional no início para usar para precisão de tempo em segundos:
{second} {minute} {hour} {day} {month} {day-of-week}
Cada campo pode ter um dos seguintes tipos de valores:
Tipo | Exemplo | Quando acionado |
---|---|---|
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 da hora, durante a hora 5 |
Um intervalo (- operador) |
5-7 * * * * * |
Três vezes por minuto - nos segundos 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 5º minuto de cada hora de cada dia |
Para especificar meses ou dias, você pode usar valores numéricos, nomes ou abreviaturas de nomes:
- Para os dias, os valores numéricos são de 0 a 6, onde 0 começa com domingo.
- Os 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 o uso de três letras para abreviaturas. Por exemplo:
Mon
,Jan
.
Exemplos NCRONTAB
Aqui estão alguns exemplos de expressões NCRONTAB que você pode usar para o gatilho de temporizador no Azure Functions.
Exemplo | Quando acionado |
---|---|
0 */5 * * * * |
uma vez a cada cinco minutos |
0 0 * * * * |
uma vez no topo de cada hora |
0 0 */2 * * * |
uma vez a cada duas horas |
0 0 9-17 * * * |
uma vez a cada hora, das 9h às 17h |
0 30 9 * * * |
às 9:30 todos os dias |
0 30 9 * * 1-5 |
às 9:30 todos os dias da semana |
0 30 9 * Jan Mon |
às 9h30 todas as segundas-feiras de janeiro |
Nota
A expressão NCRONTAB suporta o formato de cinco 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 período de tempo. Por exemplo, um 5 no hour
campo refere-se a 5:00 AM, não a cada 5 horas.
O fuso horário predefinido utilizado com as expressões CRON é Hora Universal Coordenada (UTC). Para ter sua expressão CRON baseada em outro fuso horário, crie uma configuração de aplicativo para seu aplicativo de função chamado WEBSITE_TIME_ZONE
.
O valor desta definição depende do sistema operativo e do plano em que a aplicação de funções é executada.
Sistema operativo | Planear | Value |
---|---|---|
Windows | Todos | Defina o valor para o nome do fuso horário desejado, conforme dado pela segunda linha de cada par fornecido pelo comando do Windows tzutil.exe /L |
Linux | Premium Dedicada |
Defina o valor como o nome do fuso horário desejado, conforme mostrado no banco de dados tz. |
Nota
WEBSITE_TIME_ZONE
e TZ
não são suportados atualmente quando executados em Linux em um plano de consumo. Nesse caso, definir WEBSITE_TIME_ZONE
ou TZ
pode criar problemas relacionados a SSL e fazer com que as métricas parem de funcionar para seu aplicativo.
Por exemplo, o horário do leste nos 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 horário de verão. Para que um temporizador acione o disparo às 10h00 (horário do leste) todos os dias, crie uma configuração de aplicativo para seu aplicativo de função chamado WEBSITE_TIME_ZONE
, defina o valor como Eastern Standard Time
(Windows) ou America/New_York
(Linux) e 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
A TimeSpan
só pode ser usado 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 depois de ser executada mais do que o intervalo especificado, o temporizador imediatamente invoca a função novamente.
Expresso como uma cadeia de caracteres, o TimeSpan
formato é hh:mm:ss
quando hh
é menor que 24. Quando os dois primeiros dígitos são 24 ou superiores, o formato é dd:hh:mm
. Seguem-se alguns exemplos:
Exemplo | Quando acionado |
---|---|
"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 |
Expandir
Se um aplicativo de função for expandido para várias instâncias, apenas uma única instância de uma função acionada 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.
Funções de partilha de aplicações Armazenamento
Se você estiver compartilhando contas de armazenamento entre aplicativos funcionais 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 das funções | Definição |
---|---|
2.x (e superior) | AzureFunctionsWebHost__hostid variável de ambiente |
1.x | id em host.json |
Você pode omitir o valor de identificação ou definir manualmente a configuração de identificação de cada aplicativo de função para um valor diferente.
O gatilho de temporizador usa um bloqueio de armazenamento para garantir que haja apenas uma instância de temporizador quando um aplicativo de função é expandido para várias instâncias. Se dois aplicativos de função compartilharem a mesma configuração de identificação e cada um usar um gatilho de temporizador, apenas um temporizador será executado.
Comportamento de repetição
Ao contrário do gatilho de fila, o gatilho de temporizador não tenta novamente depois que uma função falha. Quando uma função falha, ela não é chamada novamente até a próxima vez na agenda.
Invoque manualmente um gatilho de temporizador
O gatilho de temporizador para o Azure Functions fornece um webhook HTTP que pode ser invocado para acionar manualmente a função. Isso pode ser extremamente útil nos seguintes cenários.
- Testes de integração
- Trocas de faixas horárias como parte de um teste de fumo ou atividade de aquecimento
- Implantação inicial de uma função para preencher imediatamente um cache ou tabela de pesquisa em um banco de dados
Consulte executar manualmente uma função não acionada por HTTP para obter detalhes sobre como invocar manualmente uma função acionada por temporizador.
Resolução de Problemas
Para obter informações sobre o que fazer quando o gatilho do temporizador não funciona conforme o esperado, consulte Investigando e relatando problemas com funções acionadas pelo temporizador que não são acionadas.