Timer trigger for Azure Functions

Este artigo explica como trabalhar com gatilhos temporizadores no Azure Functions. Um gatilho de temporizador permite executar uma função em uma agenda.

Esta é informação de referência para programadores do Azure Functions. Se és novo no Azure Functions, começa pelos seguintes recursos:

• Azure Functions referência do programador

• Azure Functions gatilhos e conceitos de ligações

• Code e teste Azure Functions localmente

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 temporizador encontra-se no repositório azure-webjobs-sdk-extensions GitHub.

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));
    logger.LogInformation($"Function Ran. Next timer schedule = {timerInfo.ScheduleStatus?.Next}");
}

[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}");
}

@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);
}

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=False) 
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)

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

import datetime
import logging

import azure.functions as func


def main(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.now(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)

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,
});

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

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

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.isPastDue)
    {
        context.log('Node is running late!');
    }
    context.log('Node timer trigger function ran!', timeStamp);   
};

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

# 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"

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Consulte a seção Exemplo para obter exemplos completos.

Usage

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

Azure Functions utiliza 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:

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 do NCRONTAB que pode usar para o temporizador no Azure Functions.

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.

Por exemplo, a Hora do Leste nos EUA (representada por Eastern Standard Time (Windows) ou America/New_York (Linux)) utiliza atualmente UTC-05:00 durante o horário padrão e UTC-04:00 durante o horário de verão. Para que um temporizador dispare às 10:00 da manhã, hora do Leste dos EUA, todos os dias, crie uma definição de aplicação para a sua aplicação de funções chamada WEBSITE_TIME_ZONE, defina o valor para Eastern Standard Time (Windows) ou America/New_York (Linux), e depois use a seguinte expressão NCRONTAB:

"0 0 10 * * *"

Quando usa WEBSITE_TIME_ZONE, a hora é ajustada 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:

Scale-out

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.

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 disparador temporizador para o Azure Functions fornece um webhook HTTP que pode ser invocado para ativar 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.

Troubleshooting

Para informações sobre o que fazer quando o temporizador não funciona como esperado, veja Investigar e reportar problemas com funções ativadas por temporizador que não disparam.

Connections

Os gatilhos temporizadores têm uma dependência implícita do armazenamento de blobs, exceto quando executados localmente através das Ferramentas Core do Azure Functions. O sistema usa o armazenamento de blob para coordenar várias instâncias quando o aplicativo é expandido. Ele acessa o armazenamento de blob usando a conexão de armazenamento de host (AzureWebJobsStorage). Se você configurar o armazenamento do host para usar uma conexão baseada em identidade, a identidade deverá ter a função de Proprietário de Dados do Blob de Armazenamento , que é o requisito padrão para o armazenamento do host.

Próximos passos