Trigger timer per Funzioni di AzureTimer trigger for Azure Functions

Questo articolo illustra come usare trigger timer in Funzioni di Azure.This article explains how to work with timer triggers in Azure Functions. Un trigger timer consente di eseguire una funzione in base a una pianificazione.A timer trigger lets you run a function on a schedule.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

Pacchetti: Funzioni 1.xPackages - Functions 1.x

Il trigger timer è disponibile nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions versione 2.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 2.x. Il codice sorgente del pacchetto si trova nel repository GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Il supporto per questa associazione viene fornito automaticamente in tutti gli ambienti di sviluppo.Support for this binding is automatically provided in all development environments. Non è necessario installare il pacchetto o registrare l'estensione manualmente.You don't have to manually install the package or register the extension.

Pacchetti: Funzioni 2.xPackages - Functions 2.x

Il trigger timer è disponibile nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions versione 3.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 3.x. Il codice sorgente del pacchetto si trova nel repository GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Il supporto per questa associazione viene fornito automaticamente in tutti gli ambienti di sviluppo.Support for this binding is automatically provided in all development environments. Non è necessario installare il pacchetto o registrare l'estensione manualmente.You don't have to manually install the package or register the extension.

EsempioExample

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Esempio in C#C# example

Nell'esempio seguente viene illustrata una C# funzione che viene eseguita ogni volta che i minuti hanno un valore divisibile per cinque (ad esempio, se la funzione inizia a 18:57:00, le prestazioni successive saranno pari a 19:00:00).The following example shows a C# function that is executed each time the minutes have a value divisible by five (eg if the function starts at 18:57:00, the next performance will be at 19:00:00). L' TimerInfo oggetto viene passato nella funzione.The TimerInfo object is passed into the function.

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

Esempio di script C#C# script example

L'esempio seguente mostra un'associazione di trigger timer in un file function.json e una funzione script C# che usa l'associazione.The following example shows a timer trigger binding in a function.json file and a C# script function that uses the binding. La funzione scrive un log che indica se la chiamata di funzione è dovuta un'occorrenza di pianificazione mancante.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. L' TimerInfo oggetto viene passato nella funzione.The TimerInfo object is passed into the function.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice script C#:Here's the C# script code:

public static void Run(TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}" );  
}

Esempio F#F# example

L'esempio seguente mostra un'associazione di trigger timer in un file function.json e una funzione script F# che usa l'associazione.The following example shows a timer trigger binding in a function.json file and an F# script function that uses the binding. La funzione scrive un log che indica se la chiamata di funzione è dovuta un'occorrenza di pianificazione mancante.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. L' TimerInfo oggetto viene passato nella funzione.The TimerInfo object is passed into the function.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice script F#:Here's the F# script code:

let Run(myTimer: TimerInfo, log: ILogger ) =
    if (myTimer.IsPastDue) then
        log.LogInformation("F# function is running late.")
    let now = DateTime.Now.ToLongTimeString()
    log.LogInformation(sprintf "F# function executed at %s!" now)

Esempio per JavaJava example

La funzione di esempio seguente si attiva e viene eseguita ogni cinque minuti.The following example function triggers and executes every five minutes. L’@TimerTriggerannotazione sulla funzione definisce la pianificazione usando lo stesso formato di stringa delle espressioni CRON.The @TimerTrigger annotation on the function defines the schedule using the same string format as CRON expressions.

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

Esempio JavaScriptJavaScript example

L'esempio seguente mostra un'associazione di trigger timer in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows a timer trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione scrive un log che indica se la chiamata di funzione è dovuta un'occorrenza di pianificazione mancante.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. Un oggetto timer viene passato nella funzione.A timer object is passed into the function.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice JavaScript:Here's the JavaScript code:

module.exports = 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);   

    context.done();
};

Esempio in PythonPython example

Nell'esempio seguente viene usata un'associazione di trigger timer la cui configurazione è descritta nel file Function. JSON .The following example uses a timer trigger binding whose configuration is described in the function.json file. La funzione Python effettiva che usa l'associazione è descritta nel file init. py .The actual Python function that uses the binding is described in the init.py file. L'oggetto passato nella funzione è di tipo Azure. Functions. TimerRequest.The object passed into the function is of type azure.functions.TimerRequest object. La logica della funzione scrive nei log che indicano se la chiamata corrente è dovuta a un'occorrenza di pianificazione mancante.The function logic writes to the logs indicating whether the current invocation is due to a missed schedule occurrence.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice Python:Here's the Python code:

import datetime
import logging

import azure.functions as func


def main(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)

AttributiAttributes

Nelle librerie di classi C# usare l'attributo TimerTriggerAttribute.In C# class libraries, use the TimerTriggerAttribute.

Il costruttore dell'attributo accetta un'espressione CRON o un valore TimeSpan.The attribute's constructor takes a CRON expression or a TimeSpan. È possibile usare TimeSpan solo se l'app per le funzioni viene eseguita in un piano di servizio app.You can use TimeSpan only if the function app is running on an App Service plan. L'esempio seguente mostra un'espressione CRON:The following example shows a CRON expression:

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

ConfigurazioneConfiguration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo TimerTrigger.The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DESCRIZIONEDescription
typetype n/dn/a Il valore deve essere impostato su "timerTrigger".Must be set to "timerTrigger". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/dn/a Il valore deve essere impostato su "in".Must be set to "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/dn/a Nome della variabile che rappresenta l'oggetto timer nel codice della funzione.The name of the variable that represents the timer object in function code.
scheduleschedule ScheduleExpressionScheduleExpression Espressione CRON o valore TimeSpan.A CRON expression or a TimeSpan value. TimeSpan può essere usato solo per un'app per le funzioni in esecuzione in un piano di servizio app.A TimeSpan can be used only for a function app that runs on an App Service Plan. È 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%".You can put the schedule expression in an app setting and set this property to the app setting name wrapped in % signs, as in this example: "%ScheduleAppSetting%".
runOnStartuprunOnStartup RunOnStartupRunOnStartup Se true, la funzione viene richiamata all'avvio del runtime.If true, the function is invoked when the runtime starts. Ad esempio, il runtime viene avviato quando l'app per le funzioni si riattiva dopo un periodo di inattività,For example, the runtime starts when the function app wakes up after going idle due to inactivity. quando l'app per le funzioni viene riavviata a causa di modifiche alla funzione e quando l'app per le funzioni viene scalata orizzontalmente. runOnStartup dovrebbe quindi essere impostato su true solo in rari casi o mai, specialmente in ambienti di produzione.when the function app restarts due to function changes, and when the function app scales out. So runOnStartup should rarely if ever be set to true, especially in production.
useMonitoruseMonitor UseMonitorUseMonitor Impostata su true o false per indicare se monitorare la pianificazione.Set to true or false to indicate whether the schedule should be monitored. 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.Schedule monitoring persists schedule occurrences to aid in ensuring the schedule is maintained correctly even when function app instances restart. Se la proprietà non è impostata in modo esplicito, il valore predefinito è true per le pianificazioni che hanno un intervallo di ricorrenza maggiore di 1 minuto.If not set explicitly, the default is true for schedules that have a recurrence interval greater than 1 minute. Per le pianificazioni attivate più di una volta al minuto, il valore predefinito è false.For schedules that trigger more than once per minute, the default is false.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Attenzione

L'impostazione di runOnStartup su true non è consigliata in ambienti di produzione.We recommend against setting runOnStartup to true in production. Con questa impostazione, il codice viene eseguito in momenti estremamente imprevedibili.Using this setting makes code execute at highly unpredictable times. In alcune impostazioni di produzione queste esecuzioni aggiuntive possono determinare costi molto più elevati per le app ospitate in piani a consumo.In certain production settings, these extra executions can result in significantly higher costs for apps hosted in Consumption plans. Con runOnStartup abilitato, ad esempio, il trigger viene richiamato ogni volta che l'app per le funzioni viene ridimensionata.For example, with runOnStartup enabled the trigger is invoked whenever your function app is scaled. Prima di abilitare runOnStartup in un ambiente di produzione assicurarsi di avere ben compreso il comportamento in produzione delle proprie funzioni.Make sure you fully understand the production behavior of your functions before enabling runOnStartup in production.

UtilizzoUsage

Quando viene richiamata una funzione di trigger del timer, nella funzione viene passato un oggetto timer.When a timer trigger function is invoked, a timer object is passed into the function. Il codice JSON seguente è una rappresentazione di esempio dell'oggetto timer.The following JSON is an example representation of the timer object.

{
    "Schedule":{
    },
    "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.The IsPastDue property is true when the current function invocation is later than scheduled. Ad esempio, un riavvio dell'app per le funzioni può causare la mancata riuscita di una chiamata.For example, a function app restart might cause an invocation to be missed.

Espressioni NCRONTABNCRONTAB expressions

Funzioni di Azure usa la libreria NCronTab per interpretare le espressioni NCronTab.Azure Functions uses the NCronTab library to interpret NCRONTAB expressions. Un exppression NCRONTAB è simile a un'espressione CRON con la differenza che include un sesto campo aggiuntivo all'inizio da usare per la precisione temporale in secondi:An NCRONTAB exppression is similar to a CRON expression except that it includes an additional sixth field at the beginning to use for time precision in seconds:

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

Ogni campo può avere uno dei tipi di valori seguenti:Each field can have one of the following types of values:

TypeType EsempioExample Quando viene attivatoWhen triggered
Valore specificoA specific value "0 5 * * * *""0 5 * * * *" Alle hh.05.00, dove hh corrisponde a ogni ora (una volta all'ora)at hh:05:00 where hh is every hour (once an hour)
Tutti i valori (*)All values (*) "0 * 5 * * *""0 * 5 * * *" Alle 5.mm.00 ogni giorno, dove mm è ogni minuto dell'ora (60 volte al giorno)at 5:mm:00 every day, where mm is every minute of the hour (60 times a day)
Intervallo (operatore -)A range (- operator) "5-7 * * * * *""5-7 * * * * *" Alle hh.mm.05, hh.mm.06 e hh.mm.07, dove hh.mm è ogni minuto di ogni ora (3 volte al minuto)at hh:mm:05,hh:mm:06, and hh:mm:07 where hh:mm is every minute of every hour (3 times a minute)
Set di valori (operatore ,)A set of values (, operator) "5,8,10 * * * * *""5,8,10 * * * * *" Alle hh.mm.05, hh.mm.08 e hh.mm.10, dove hh.mm è ogni minuto di ogni ora (3 volte al minuto)at hh:mm:05,hh:mm:08, and hh:mm:10 where hh:mm is every minute of every hour (3 times a minute)
Valore di intervallo (operatore /)An interval value (/ operator) "0 */5 * * * *""0 */5 * * * *" Alle hh.05.00, hh.10.00, hh.15.00 e così via fino alle hh.55.00, dove hh è ogni ora (12 volte all'ora)at hh:05:00, hh:10:00, hh:15:00, and so on through hh:55:00 where hh is every hour (12 times an hour)

Per specificare mesi o giorni è possibile usare valori numerici, nomi o abbreviazioni di nomi:To specify months or days you can use numeric values, names, or abbreviations of names:

  • Per i giorni, i valori numerici vanno da 0 a 6 in cui 0 corrisponde alla domenica.For days, the numeric values are 0 to 6 where 0 starts with Sunday.
  • I nomi sono in inglese.Names are in English. Ad esempio: Monday, January.For example: Monday, January.
  • Per i nomi viene fatta distinzione tra maiuscole e minuscole.Names are case-insensitive.
  • I nomi possono essere abbreviati.Names can be abbreviated. La lunghezza consigliata per le abbreviazioni è tre lettere.Three letters is the recommended abbreviation length. Ad esempio: Mon, Jan.For example: Mon, Jan.

Esempi di NCRONTABNCRONTAB examples

Di seguito sono riportati alcuni esempi di espressioni NCRONTAB che è possibile usare per il trigger timer in funzioni di Azure.Here are some examples of NCRONTAB expressions you can use for the timer trigger in Azure Functions.

EsempioExample Quando viene attivatoWhen triggered
"0 */5 * * * *" Una volta ogni cinque minutionce every five minutes
"0 0 * * * *" Una volta all'inizio di ogni oraonce at the top of every hour
"0 0 */2 * * *" Una volta ogni due oreonce every two hours
"0 0 9-17 * * *" Una volta ogni ora dalle 9 alle 17once every hour from 9 AM to 5 PM
"0 30 9 * * *" Alle 9.30 di ogni giornoat 9:30 AM every day
"0 30 9 * * 1-5" Alle 9.30 di ogni giorno ferialeat 9:30 AM every weekday
"0 30 9 * Jan Mon" Alle 9.30 di ogni lunedì di gennaioat 9:30 AM every Monday in January

Fusi orari NCRONTABNCRONTAB time zones

I numeri in un'espressione CRON fanno riferimento a una data e a un'ora e non a un intervallo di tempo.The numbers in a CRON expression refer to a time and date, not a time span. Ad esempio, il valore 5 nel campo hour fa riferimento alle 5.00 e non a ogni 5 ore.For example, a 5 in the hour field refers to 5:00 AM, not every 5 hours.

Il fuso orario predefinito usato con le espressioni CRON è Coordinated Universal Time (UTC).The default time zone used with the CRON expressions is 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.To have your CRON expression based on another time zone, create an app setting for your function app named WEBSITE_TIME_ZONE. Impostare il valore sul nome del fuso orario prescelto come illustrato nell'indice dei fusi orari di Microsoft.Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

Ad esempio, Ora solare fuso orientale (EST) è UTC-05:00.For example, Eastern Standard Time is UTC-05:00. Per attivare il trigger del timer alle 10:00 AM EST ogni giorno, usare l'espressione NCRONTAB seguente che rappresenta il fuso orario UTC:To have your timer trigger fire at 10:00 AM EST every day, use the following NCRONTAB expression that accounts for UTC time zone:

"0 0 15 * * *"

In alternativa, è possibile creare un'impostazione per l'app per le funzioni denominata WEBSITE_TIME_ZONE e impostare il valore su Ora solare fuso orientale.Or create an app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. USA quindi l'espressione NCRONTAB seguente:Then uses the following NCRONTAB expression:

"0 0 10 * * *"

Quando si usa WEBSITE_TIME_ZONE, l'ora viene regolata per modifiche all'ora nel fuso orario specifico, ad esempio l'ora legale.When you use WEBSITE_TIME_ZONE, the time is adjusted for time changes in the specific timezone, such as daylight savings time.

TimeSpanTimeSpan

TimeSpan può essere usato solo per un'app per le funzioni in esecuzione in un piano di servizio app.A TimeSpan can be used only for a function app that runs on an App Service Plan.

Diversamente da un'espressione CRON, un valore TimeSpan specifica l'intervallo di tempo tra ogni chiamata di funzione.Unlike a CRON expression, a TimeSpan value specifies the time interval between each function invocation. Quando una funzione viene completata dopo essere stata eseguita più a lungo dell'intervallo specificato, il timer richiama immediatamente di nuovo la funzione.When a function completes after running longer than the specified interval, the timer immediately invokes the function again.

Espresso come stringa, il formato di TimeSpan è hh:mm:ss, dove hh è minore di 24.Expressed as a string, the TimeSpan format is hh:mm:ss when hh is less than 24. Quando le prime due cifre sono un numero uguale o maggiore di 24, il formato è dd:hh:mm.When the first two digits are 24 or greater, the format is dd:hh:mm. Ecco alcuni esempi:Here are some examples:

EsempioExample Quando viene attivatoWhen triggered
"01:00:00""01:00:00" Ogni oraevery hour
"00:01:00""00:01:00" Ogni minutoevery minute
"24:00:00""24:00:00" Ogni 24 giornievery 24 days
"1.00:00:00""1.00:00:00" ogni giornoevery day

Scalabilità orizzontaleScale-out

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.If a function app scales out to multiple instances, only a single instance of a timer-triggered function is run across all instances.

App per le funzioni che condividono un account di archiviazioneFunction apps sharing Storage

Se si condivide un account di archiviazione tra più app per le funzioni, assicurarsi che ogni app abbia un valore diverso per id in host.json.If you share a Storage account across multiple function apps, make sure that each function app has a different id in host.json. È possibile omettere la proprietà id o impostare manualmente la proprietà id di ogni app per le funzioni su un valore diverso.You can omit the id property or manually set each function app's id to a different value. Il trigger timer usa un blocco dell'archiviazione per garantire che vi sia una sola istanza del timer quando un'app per le funzioni viene scalata orizzontalmente a più istanze.The timer trigger uses a storage lock to ensure that there will be only one timer instance when a function app scales out to multiple instances. Se due app per le funzioni condividono la stessa proprietà id e ognuna usa un trigger timer, verrà eseguito solo un timer.If two function apps share the same id and each uses a timer trigger, only one timer will run.

Comportamento in caso di nuovo tentativoRetry behavior

Diversamente dal trigger di coda, il trigger timer non viene ripetuto se una funzione non riesce.Unlike the queue trigger, the timer trigger doesn't retry after a function fails. Quando una funzione non riesce, non viene chiamata di nuovo fino alla volta successiva nella pianificazione.When a function fails, it isn't called again until the next time on the schedule.

Risoluzione dei problemiTroubleshooting

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).For information about what to do when the timer trigger doesn't work as expected, see Investigating and reporting issues with timer triggered functions not firing.

Passaggi successiviNext steps