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:

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

Pacchetti - Funzioni 2.x e versioni successive

Il trigger timer è disponibile nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions versione 3.x. Il codice sorgente del pacchetto si trova nel repository GitHub azure-webjobs-sdk-extensions.

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

Pacchetti: Funzioni 1.x

Il trigger timer è disponibile nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions versione 2.x. Il codice sorgente del pacchetto si trova nel repository GitHub azure-webjobs-sdk-extensions.

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

Esempio

L'esempio seguente illustra una funzione C# che viene eseguita ogni volta che i minuti hanno un valore divisibile per cinque (ad esempio, se la funzione inizia alle 18:55:00, le prestazioni seguenti saranno alle 19:00:00). TimerInfoL'oggetto viene passato alla funzione .

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

Attributi e annotazioni

Nelle librerie di classi C# usare l'attributo TimerTriggerAttribute.

Il costruttore dell'attributo accetta un'espressione CRON o un valore TimeSpan. È possibile usare TimeSpan solo se l'app per le funzioni è in esecuzione in un piano di servizio app. TimeSpannon è supportato per le funzioni a consumo o Premium elastiche.

L'esempio seguente mostra un'espressione CRON:

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

Configurazione

La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo .

Proprietà di function.json Proprietà dell'attributo Descrizione
type n/d Il valore deve essere impostato su "timerTrigger". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direction n/d Il valore deve essere impostato su "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
nome n/d Nome della variabile che rappresenta l'oggetto timer nel codice della funzione.
Programma ScheduleExpression Espressione CRON o valore TimeSpan. TimeSpan può essere usato solo per un'app per le funzioni in esecuzione in un piano di servizio app. È possibile inserire l'espressione schedule in un'impostazione dell'app e definire per questa proprietà il nome dell'impostazione dell'app racchiuso tra simboli %, come in questo esempio: "%ImpostazioneAppSchedule%".
runOnStartup RunOnStartup Se true, la funzione viene richiamata all'avvio del runtime. Ad esempio, il runtime viene avviato quando l'app per le funzioni si riattiva dopo un periodo di inattività, quando l'app per le funzioni viene riavviata a causa di modifiche della funzione e quando l'app per le funzioni viene ridimensionata. RunOnStartup dovrebbe quindi essere impostato raramente se mai su , soprattutto nell'ambiente di produzione.
useMonitor UseMonitor Impostata su true o false per indicare se monitorare la pianificazione. Il monitoraggio della pianificazione rende persistenti le occorrenze della pianificazione per garantire che la pianificazione venga gestita correttamente anche quando le istanze dell'app per le funzioni vengono riavviate. Se non impostato in modo esplicito, il valore predefinito è per le pianificazioni con un intervallo di ricorrenza maggiore o true uguale a 1 minuto. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.

Attenzione

L'impostazione di runOnStartup su non è consigliata in ambienti di produzione. Con questa impostazione, il codice viene eseguito in momenti estremamente imprevedibili. In alcune impostazioni di produzione queste esecuzioni aggiuntive possono determinare costi molto più elevati per le app ospitate in piani a consumo. Ad esempio, con runOnStartup abilitato, il trigger viene richiamato ogni volta che viene ridimensionata l'app per le funzioni. Prima di abilitare runOnStartup in un ambiente di produzione assicurarsi di avere ben compreso il comportamento in produzione delle proprie funzioni.

Utilizzo

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
}

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.

Espressioni NCRONTAB

Funzioni di Azure usa la libreria NCronTab per interpretare le espressioni NCRONTAB. 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:

Type Esempio Quando viene attivato
Valore specifico 0 5 * * * * Una volta ogni ora del giorno al minuto 5 di ogni ora
Tutti i valori (*) 0 * 5 * * * A ogni minuto dell'ora, a partire dall'ora 5
Intervallo (operatore -) 5-7 * * * * * Tre volte al minuto, in secondi da 5 a 7 durante ogni minuto di ogni ora di ogni giorno
Set di valori (operatore ,) 5,8,10 * * * * * Tre volte al minuto, in secondi 5, 8 e 10 per ogni minuto di ogni ora di ogni giorno
Valore di intervallo (operatore /) 0 */5 * * * * 12 volte all'ora, al secondo 0 di ogni 5° minuto di ogni ora di ogni giorno

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. La lunghezza consigliata per le abbreviazioni è tre lettere. Ad esempio: Mon, Jan.

Esempi di NCRONTAB

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

Esempio Quando viene attivato
0 */5 * * * * Una volta ogni cinque minuti
0 0 * * * * Una volta all'inizio di ogni ora
0 0 */2 * * * Una volta ogni due ore
0 0 9-17 * * * Una volta ogni ora dalle 9 alle 17
0 30 9 * * * Alle 9.30 di ogni giorno
0 30 9 * * 1-5 Alle 9.30 di ogni giorno feriale
0 30 9 * Jan Mon Alle 9.30 di ogni lunedì di gennaio

Nota

L'espressione NCRONTAB supporta sia il formato di cinque campi che il formato di sei campi. La sesta posizione del campo è un valore per i secondi posizionato all'inizio dell'espressione.

Fusi orari NCRONTAB

I numeri in un'espressione CRON fanno riferimento a una data e a un'ora e 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.

Sistema operativo Piano Valore
Windows Tutti Impostare il valore sul nome del fuso orario desiderato, come specificato dalla seconda riga di ogni coppia specificata dal comando Windowstzutil.exe /L
Linux Premium
Dedicato
Impostare il valore sul nome del fuso orario desiderato, come illustrato nel database tz.

Nota

WEBSITE_TIME_ZONE non è attualmente supportato nel piano a consumo per Linux distribuzione.

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

"0 0 10 * * *"

Quando si usa l'ora viene regolata per le modifiche dell'ora nel fuso orario specifico, incluse l'ora legale e WEBSITE_TIME_ZONE le modifiche nell'ora solare.

TimeSpan

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

Diversamente da un'espressione CRON, un valore TimeSpan 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:

Esempio Quando viene attivato
"01:00:00" Ogni ora
"00:01:00" Ogni minuto
"25:00:00" ogni 25 giorni
"1.00:00:00" Ogni giorno

Aumento delle istanze

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.

App per le funzioni che condividono un account di archiviazione

Se si condividono 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.

Versione di Funzioni Impostazione
2.x (e versioni successive) La variabile di ambiente AzureFunctionsWebHost__hostid
1.x id in id

È 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 garantire che sia presente una sola istanza del timer quando un'app per le funzioni viene scalata orizzontalmente 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.

Comportamento in caso di nuovo tentativo

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.

Richiamare manualmente un trigger timer

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

  • Test di integrazione
  • Scambi di slot come parte di un'smoke test o di riscaldamento
  • Distribuzione iniziale di una funzione per popolare immediatamente una cache o una tabella di ricerca in un database

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

Risoluzione dei problemi

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

Passaggi successivi