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ência para programadores das Funções do Azure

• Conceitos dos acionadores e dos enlaces das Funções do Azure

• Criar código e testar as Funções do Azure 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 de timer está no repositório GitHub azure-webjobs-sdk-extensions .

Exemplo

//<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));

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

{
    "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.

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:

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.

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

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.

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.

Ligações

Os gatilhos de timer têm uma dependência implícita no armazenamento de blobs, exceto quando executados localmente por meio das Ferramentas Principais 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