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:
Riferimenti per sviluppatori C#:
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.
Il codice sorgente per il pacchetto di estensione timer si trova nel repository GitHub azure-webjobs-sdk-extensions .
Importante
Questo articolo usa schede per supportare più versioni del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per sviluppatori di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la guida alla migrazione.
Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.
Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.
Questo articolo supporta entrambi i modelli di programmazione.
Esempio
Questo esempio mostra una funzione C# che viene eseguita ogni volta che i minuti hanno un valore divisibile per cinque. Ad esempio, quando la funzione inizia alle 18:55:00, l'esecuzione successiva è alle 19:00:00. Un TimerInfo oggetto viene passato alla funzione .
È possibile creare una funzione C# usando una delle modalità C# seguenti:
- Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano
Microsoft.Azure.Functions.Worker.Extensions.*spazi dei nomi. - Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano
Microsoft.Azure.WebJobs.Extensions.*spazi dei nomi.
Importante
Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.
//<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));
La funzione di esempio seguente si attiva e viene eseguita ogni cinque minuti. L’@TimerTriggerannotazione sulla funzione definisce la pianificazione usando lo stesso formato di stringa delle espressioni 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);
}
L'esempio seguente mostra un'associazione di trigger timer e un codice di funzione che usa l'associazione, in cui un'istanza che rappresenta il timer viene passata alla funzione. La funzione scrive un log che indica se la chiamata di funzione è dovuta un'occorrenza di pianificazione mancante. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o 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)
L'esempio seguente mostra una funzione TypeScript trigger timer.
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,
});
L'esempio seguente mostra una funzione JavaScript trigger timer.
const { app } = require('@azure/functions');
app.timer('timerTrigger1', {
schedule: '0 */5 * * * *',
handler: (myTimer, context) => {
context.log('Timer function processed request.');
},
});
Ecco i dati di associazione nel file function.json:
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
Di seguito è riportato il codice della funzione timer nel file 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"
Attributi
La libreria C# in-process usa TimerTriggerAttribute da Microsoft.Azure.WebJobs.Extensions , mentre la libreria C# del processo di lavoro isolato usa TimerTriggerAttribute da Microsoft.Azure.Functions.Worker.Extensions.Timer per definire la funzione. Lo script C# usa invece un file di configurazione function.json.
| Proprietà dell'attributo | Descrizione |
|---|---|
| Fissa appuntamento | 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 di pianificazione in un'impostazione dell'app e impostare questa proprietà sul nome dell'impostazione dell'app di cui è stato eseguito il wrapping nei % segni, come %ScheduleAppSetting%. |
| 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 alle funzioni e quando l'app per le funzioni viene ridimensionata. Usare con cautela.RunOnStartup deve raramente essere impostato truesu , soprattutto nell'ambiente di produzione. |
| 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 è true per le pianificazioni con un intervallo di ricorrenza maggiore o uguale a 1 minuto. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false. |
Elementi Decorator
Si applica solo al modello di programmazione Python v2.
Per le funzioni Python v2 definite usando un elemento Decorator, le proprietà seguenti in schedule:
| Proprietà | Descrizione |
|---|---|
arg_name |
Nome della variabile che rappresenta l'oggetto timer nel codice della funzione. |
schedule |
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%". |
run_on_startup |
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 alle funzioni e quando l'app per le funzioni viene ridimensionata. Usare con cautela.runOnStartup deve raramente essere impostato truesu , soprattutto nell'ambiente di produzione. |
use_monitor |
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 è true per le pianificazioni con un intervallo di ricorrenza maggiore o uguale a 1 minuto. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false. |
Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .
Annotazioni
L'annotazione @TimerTrigger nella funzione definisce l'oggetto schedule utilizzando lo stesso formato di stringa delle espressioni CRON. L'annotazione supporta le impostazioni seguenti:
Impostazione
Si applica solo al modello di programmazione Python v1.
Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al app.timer() metodo .
| Proprietà | Descrizione |
|---|---|
| schedule | 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 | 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 alle funzioni e quando l'app per le funzioni viene ridimensionata. Usare con cautela.runOnStartup deve raramente essere impostato truesu , soprattutto nell'ambiente di produzione. |
| 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 è true per le pianificazioni con un intervallo di ricorrenza maggiore o uguale a 1 minuto. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false. |
Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.
| Proprietà di function.json | Descrizione |
|---|---|
| type | Il valore deve essere impostato su "timerTrigger". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure. |
| direction | Il valore deve essere impostato su "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure. |
| name | Nome della variabile che rappresenta l'oggetto timer nel codice della funzione. |
| schedule | 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 | 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 alle funzioni e quando l'app per le funzioni viene ridimensionata. Usare con cautela.runOnStartup deve raramente essere impostato truesu , soprattutto nell'ambiente di produzione. |
| 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 è true per le pianificazioni con un intervallo di ricorrenza maggiore o uguale a 1 minuto. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false. |
Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.
Attenzione
Non impostare runOnStartup sutrue nell'ambiente di produzione. Con questa impostazione, il codice viene eseguito in momenti estremamente imprevedibili. In determinate impostazioni di produzione, queste esecuzioni aggiuntive possono comportare costi significativamente più elevati per le app ospitate in un piano a consumo. Ad esempio, con runOnStartup abilitato, il trigger viene richiamato ogni volta che l'app per le funzioni viene ridimensionata. Prima di abilitare runOnStartup in un ambiente di produzione assicurarsi di avere ben compreso il comportamento in produzione delle proprie funzioni.
Per esempi completi, vedere la sezione Esempio.
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
}
{
"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 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 * * * |
Ogni minuto nell'ora, durante l'ora 5 |
Intervallo (operatore -) |
5-7 * * * * * |
Tre volte al minuto - in secondi da 5 a 7 durante ogni minuto di ogni ora del giorno |
Set di valori (operatore ,) |
5,8,10 * * * * * |
Tre volte al minuto - a secondi 5, 8 e 10 durante ogni minuto di ogni ora del giorno |
Valore di intervallo (operatore /) |
0 */5 * * * * |
12 volte un'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 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 cinque campi che sei formati di campo. La sesta posizione del campo è un valore per i secondi che viene 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 | Tutte le date | Impostare il valore sul nome del fuso orario desiderato in base alla seconda riga di ogni coppia specificata dal comando di Windows tzutil.exe /L |
| Linux | Premium Dedicato |
Impostare il valore sul nome del fuso orario desiderato, come illustrato nel database tz. |
Nota
WEBSITE_TIME_ZONE e TZ non sono attualmente supportati durante l'esecuzione in Linux in un piano a consumo. In questo caso, l'impostazione WEBSITE_TIME_ZONE o TZ la creazione di problemi correlati a SSL causa l'interruzione del funzionamento delle metriche per l'app.
Ad esempio, l'ora orientale negli Stati Uniti (rappresentata 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 timer alle 10:00 ora 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) e quindi usare l'espressione NCRONTAB seguente:
"0 0 10 * * *"
Quando si usa WEBSITE_TIME_ZONE l'ora viene modificata per le modifiche all'ora nel fuso orario specifico, tra cui l'ora legale e 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:00" | ogni 25 giorni |
| "1.00:00:00" | Ogni giorno |
Scalabilità orizzontale
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 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.
| Versione di Funzioni | Impostazione |
|---|---|
| 2.x (e versioni successive) | La variabile di ambiente AzureFunctionsWebHost__hostid |
| 1.x | id in host.json |
È 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.
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 fornisce un webhook HTTP che può essere richiamato per attivare manualmente la funzione. Ciò può essere estremamente utile negli scenari seguenti.
- Test di integrazione
- 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.
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).