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:

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á disponível em geral 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.
//<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 aciona e executa 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.

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 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:

Propriedade Description
arg_name O nome da variável que representa o objeto de temporizador no código da função.
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 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.

Propriedade 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 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 .

propriedade function.json Description
tipo 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 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 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 é quando a invocação da função atual é true 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. Três letras é o comprimento de abreviatura recomendado. 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.

Fusos horários NCRONTAB

Os números em uma expressão CRON 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 valor
Windows Tudo 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, a Hora do Leste nos EUA (representada 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 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 CRON, 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 é quando hh é hh:mm:ss 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. Não será acionado novamente se ainda existir uma invocação pendente 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.

Próximos passos