Trigger timer per Funzioni di Azure

Questo articolo illustra come usare trigger timer in Funzioni di Azure. Un trigger timer consente di eseguire una funzione in base a una pianificazione.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:

• Guida di riferimento per gli sviluppatori a Funzioni di Azure

• Concetti relativi a trigger e associazioni in Funzioni di Azure

• Scrivere codici per Funzioni di Azure e testarle in locale

Per informazioni su come eseguire manualmente una funzione attivata da timer, vedere Eseguire manualmente una funzione non attivata da HTTP.

Il supporto per questa associazione viene fornito automaticamente in tutti gli ambienti di sviluppo. Non è necessario installare il pacchetto o registrare l'estensione manualmente.

Source code for the timer extension package is in the azure-webjobs-sdk-extensions GitHub repository.

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

When you're developing locally, add your application settings in the local.settings.json file in the Values collection.

See the Example section for complete examples.

Quando viene richiamata una funzione trigger timer, un oggetto timer viene passato alla funzione. Il codice JSON seguente è una rappresentazione di esempio dell'oggetto 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
}

La proprietà isPastDue è true quando la chiamata della funzione corrente avviene successivamente al momento pianificato. Ad esempio, un riavvio dell'app per le funzioni può causare la mancata riuscita di una chiamata.

Azure Functions uses the NCronTab library to interpret NCRONTAB expressions. Un'espressione NCRONTAB è simile a un'espressione CRON, ad eccezione del fatto che include un sesto campo aggiuntivo all'inizio da usare per la precisione temporale in secondi:

{second} {minute} {hour} {day} {month} {day-of-week}

Ogni campo può avere uno dei tipi di valori seguenti:

Per specificare mesi o giorni è possibile usare valori numerici, nomi o abbreviazioni di nomi:

• Per i giorni, i valori numerici vanno da 0 a 6, in cui 0 corrisponde alla domenica.
• I nomi sono in inglese. Ad esempio: Monday, January.
• Per i nomi viene fatta distinzione tra maiuscole e minuscole.
• I nomi possono essere abbreviati. È consigliabile usare tre lettere per le abbreviazioni. Ad esempio: Mon, Jan.

Ecco alcuni esempi di espressioni NCRONTAB che è possibile usare per il trigger timer in Funzioni di Azure.

I numeri in un'espressione NCRONTAB fanno riferimento a un'ora e a una data, non a un intervallo di tempo. Ad esempio, il valore 5 nel campo hour fa riferimento alle 5.00 e non a ogni 5 ore.

Il fuso orario predefinito usato con le espressioni CRON è Coordinated Universal Time (UTC). Per fare in modo che l'espressione CRON sia basata su un altro fuso orario, creare un'impostazione per l'app per le funzioni denominata WEBSITE_TIME_ZONE.

Il valore di questa impostazione dipende dal sistema operativo e dal piano in cui viene eseguita l'app per le funzioni.

Ad esempio, il fuso orientale negli Stati Uniti (rappresentato da Eastern Standard Time (Windows) o America/New_York (Linux)) usa attualmente UTC-05:00 durante l'ora solare e UTC-04:00 durante l'ora legale. Per attivare un trigger orario alle 10:00 del fuso orientale ogni giorno, creare un'impostazione dell'app per l'app per le funzioni denominata WEBSITE_TIME_ZONE, impostare il valore su Eastern Standard Time (Windows) o America/New_York (Linux), quindi usare l'espressione NCRONTAB seguente:

"0 0 10 * * *"

Quando si usa WEBSITE_TIME_ZONE, l'ora viene modificata per le variazioni di ora nel fuso orario specifico, tra cui l'ora legale e le modifiche nell'ora solare.

TimeSpan può essere usato solo per un'app per le funzioni in esecuzione in un piano di servizio app.

A differenza di un'espressione NCRONTAB, un TimeSpan valore specifica l'intervallo di tempo tra ogni chiamata di funzione. Quando una funzione viene completata dopo essere stata eseguita più a lungo dell'intervallo specificato, il timer richiama immediatamente di nuovo la funzione.

Espresso come stringa, il formato di TimeSpan è hh:mm:ss, dove hh è minore di 24. Quando le prime due cifre sono un numero uguale o maggiore di 24, il formato è dd:hh:mm. Di seguito sono riportati alcuni esempi.

Se un'app per le funzioni viene scalata orizzontalmente a più istanze, viene eseguita un'unica istanza di una funzione attivata dal timer in tutte le istanze. Non verrà attivato di nuovo se è ancora in esecuzione una chiamata in sospeso.

Se si condividono gli account di archiviazione tra app per le funzioni non distribuite nel servizio app, potrebbe essere necessario assegnare in modo esplicito l'ID host a ogni app.

È possibile omettere il valore di identificazione o impostare manualmente la configurazione di identificazione di ogni app per le funzioni su un valore diverso.

Il trigger timer usa un blocco di archiviazione per assicurarsi che sia presente una sola istanza timer quando un'app per le funzioni viene ridimensionata in più istanze. Se due app per le funzioni condividono la stessa configurazione di identificazione e ognuna usa un trigger timer, viene eseguito un solo timer.

Diversamente dal trigger di coda, il trigger timer non viene ripetuto se una funzione non riesce. Quando una funzione non riesce, non viene chiamata di nuovo fino alla volta successiva nella pianificazione.

Il trigger timer per Funzioni di Azure fornisce un webhook HTTP che può essere richiamato per attivare manualmente la funzione. Ciò può essere estremamente utile negli scenari seguenti.

• Integration testing
• Slot swaps come parte di un smoke test o di un'attività di riscaldamento
• Distribuzione iniziale di una funzione per popolare immediatamente una tabella di cache o ricerca in un database

Per informazioni dettagliate su come richiamare manualmente una funzione attivata da timer, vedere eseguire manualmente una funzione attivata da HTTP.

Per informazioni su cosa fare quando il trigger timer non funziona come previsto, vedere Investigating and reporting issues with timer triggered functions not firing (Analisi e segnalazione di problemi quando non vengono eseguite le funzioni attivate da timer).

I trigger timer hanno una dipendenza implicita dall'archiviazione BLOB, tranne quando vengono eseguiti localmente tramite gli strumenti di base di Funzioni di Azure. Il sistema usa l'archiviazione BLOB per coordinare più istanze quando l'app aumenta il numero di istanze. Accede all'archiviazione BLOB usando la connessione di archiviazione host (AzureWebJobsStorage). If you configure the host storage to use an identity-based connection, the identity should have the Storage Blob Data Owner role, which is the default requirement for host storage.