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:

PacchettiPackages

Il trigger timer è disponibile nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package. 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.

Per lo sviluppo locale in Funzioni di Azure versione 2.x, il pacchetto viene automaticamente registrato come estensione dell'associazione.For local development in Azure Functions version 2.x, the package is automatically registered as a binding extension. Per lo sviluppo di librerie di classe C# in Funzioni 1.x e 2.x, il pacchetto viene automaticamente installato nel progetto.For C# class library development in Functions 1.x and 2.x, the package is automatically installed in the project.

Si noti che il codice sorgente segue la numerazione delle versioni di WebJobs SDK: WebJobs SDK versione 2.x equivale a Funzioni di Azure 1.x, pertanto il codice di Funzioni 1.x è incluso nel ramo v2.x nel repository.Note that source code follows WebJobs SDK version numbering: WebJobs SDK version 2.x is equivalent to Azure Functions 1.x, so Functions 1.x code is in the v2.x branch in the repository. I rami master e dev contengono il codice per Web Jobs 3.x, che corrisponde a Funzioni 2.x.Master and dev branches contain code for Web Jobs 3.x, which is the same as Functions 2.x.

EsempioExample

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

Esempio in C#C# example

L'esempio seguente mostra una funzione C# che viene eseguita ogni cinque minuti:The following example shows a C# function that runs every five minutes:

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, TraceWriter log)
{
    if(myTimer.IsPastDue)
    {
        log.Info("Timer is running late!");
    }
    log.Info($"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.

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, TraceWriter log)
{
    if(myTimer.IsPastDue)
    {
        log.Info("Timer is running late!");
    }
    log.Info($"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.

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: TraceWriter ) =
    if (myTimer.IsPastDue) then
        log.Info("F# function is running late.")
    let now = DateTime.Now.ToLongTimeString()
    log.Info(sprintf "F# function executed at %s!" now)

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.

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 JavaScript:Here's the JavaScript script code:

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if(myTimer.isPastDue)
    {
        context.log('Node.js is running late!');
    }
    context.log('Node.js timer trigger function ran!', timeStamp);   

    context.done();
};

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, TraceWriter log)
{
    if (myTimer.IsPastDue)
    {
        log.Info("Timer is running late!");
    }
    log.Info($"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. Di conseguenza, runOnStartup deve essere impostato raramente, o addirittura mai, su true, in quando causa l'esecuzione del codice in momenti estremamente imprevedibili.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, as it will make code execute at highly unpredictable times.
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.

UsoUsage

Quando viene richiamata una funzione di trigger timer, l'oggetto timer viene passato alla funzione.When a timer trigger function is invoked, the 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 CRONCRON expressions

Un'espressione CRON per il trigger timer di Funzioni di Azure include sei campi:A CRON expression for the Azure Functions timer trigger includes six fields:

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

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

Esempi CRONCRON examples

Ecco alcuni esempi di espressioni CRON che è possibile usare per il trigger timer in Funzioni di Azure.Here are some examples of CRON expressions you can use for the timer trigger in Azure Functions.

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

Nota

Alcuni esempi di espressioni CRON sono disponibili online, ma molti omettono il campo {second}.You can find CRON expression examples online, but many of them omit the {second} field. Se si copia una di queste espressioni, aggiungere il campo {second} mancante.If you copy from one of them, add the missing {second} field. In genere è preferibile impostare uno zero in questo campo, anziché un asterisco.Usually you'll want a zero in that field, not an asterisk.

Fusi orari CRONCRON 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 timer trigger ogni giorno alle 10:00 EST, usare la seguente espressione CRON che rappresenta il fuso orario UTC:To have your timer trigger fire at 10:00 AM EST every day, use the following CRON expression that accounts for UTC time zone:

"schedule": "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. Usare quindi l'espressione CRON seguente:Then uses the following CRON expression:

"schedule": "0 0 10 * * *",

Intervallo di tempoTimeSpan

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. Di seguito sono riportati 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

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, viene chiamata di nuovo fino alla volta successiva nella pianificazione.When a function fails, it is't called again until the next time on the schedule.

Passaggi successiviNext steps