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:

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 o modelo v4 funciona, consulte o Guia de desenvolvedor do Node.js para Azure Functions. Para conhecer as diferenças entre v3 e 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.*.
//<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.

const { app } = require('@azure/functions');

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: (myTimer, context) => {
        context.log('Timer function processed request.');
    },
});

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 caution.RunOnStartup deve ser definido raramente ou nunca como true, principalmente 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.

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 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 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ções é reiniciado devido a alterações de função e quando o aplicativo de funções é escalado horizontalmente. Use com caution.runOnStartup deve ser definido raramente ou nunca como true, principalmente 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 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 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ções é reiniciado devido a alterações de função e quando o aplicativo de funções é escalado horizontalmente. Use com caution.runOnStartup deve ser definido raramente ou nunca como true, principalmente 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 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 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ções é reiniciado devido a alterações de função e quando o aplicativo de funções é escalado horizontalmente. Use com caution.runOnStartup deve ser definido raramente ou nunca como true, principalmente 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:

  • Por dias, os valores numéricos são 0 a 6, onde 0 começa com o 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. Três letras é o comprimento de abreviação recomendada. 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.

Fusos horários NCRONTAB

Os números em uma expressão CRON se referem a uma hora e uma data, não a um período 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 CRON, um valor TimeSpan especifica o intervalo de tempo entre cada invocação 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á disparado 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.

Próximas etapas