Déclencheur de minuteur pour Azure FunctionsTimer trigger for Azure Functions

Cet article explique comment utiliser des déclencheurs de minuteur dans Azure Functions.This article explains how to work with timer triggers in Azure Functions. Un déclencheur de minuteur vous permet d’exécuter une fonction de manière planifiée.A timer trigger lets you run a function on a schedule.

Il s’agit des informations de référence pour les développeurs Azure Functions.This is reference information for Azure Functions developers. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :If you're new to Azure Functions, start with the following resources:

Packages - Functions 1.xPackages - Functions 1.x

Le déclencheur de minuteur est fourni dans le package NuGet Microsoft.Azure.WebJobs.Extensions version 2.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 2.x. Le code source du package se trouve dans le référentiel GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

La prise en charge de cette liaison est automatique dans tous les environnements de développement.Support for this binding is automatically provided in all development environments. Vous n’avez pas besoin d’installer manuellement le package ou d’enregistrer l’extension.You don't have to manually install the package or register the extension.

Packages - Functions 2.xPackages - Functions 2.x

Le déclencheur de minuteur est fourni dans le package NuGet Microsoft.Azure.WebJobs.Extensions version 3.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 3.x. Le code source du package se trouve dans le référentiel GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

La prise en charge de cette liaison est automatique dans tous les environnements de développement.Support for this binding is automatically provided in all development environments. Vous n’avez pas besoin d’installer manuellement le package ou d’enregistrer l’extension.You don't have to manually install the package or register the extension.

ExemplesExample

Consultez l’exemple propre à un langage particulier :See the language-specific example:

Exemple en code C#C# example

L’exemple suivant montre une fonction C# qui est exécutée chaque fois que les minutes ont une valeur divisible par 5 (par exemple, si la fonction commence à 18:57:00, l’exécution suivante aura lieu à 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’objet TimerInfo est transmis à la fonction.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}");
}

Exemple de script C#C# script example

L’exemple suivant montre une liaison de déclencheur de minuteur dans un fichier function.json et une fonction de script C# qui utilise la liaison.The following example shows a timer trigger binding in a function.json file and a C# script function that uses the binding. La fonction écrit un journal indiquant si cet appel de fonction est dû à une occurrence de planification manquée.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. L’objet TimerInfo est transmis à la fonction.The TimerInfo object is passed into the function.

Voici les données de liaison dans le fichier function.json :Here's the binding data in the function.json file:

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

Voici le code 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}" );  
}

Exemple F#F# example

L’exemple suivant montre une liaison de déclencheur de minuteur dans un fichier function.json et une fonction de script F# qui utilise la liaison.The following example shows a timer trigger binding in a function.json file and an F# script function that uses the binding. La fonction écrit un journal indiquant si cet appel de fonction est dû à une occurrence de planification manquée.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. L’objet TimerInfo est transmis à la fonction.The TimerInfo object is passed into the function.

Voici les données de liaison dans le fichier function.json :Here's the binding data in the function.json file:

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

Voici le code de 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)

Exemple JavaJava example

L’exemple suivant lance et exécute la fonction toutes les cinq minutes.The following example function triggers and executes every five minutes. L’annotation @TimerTrigger sur la fonction définit le programme avec le même format de chaîne de caractères que les expressions 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);
}

Exemple JavaScriptJavaScript example

L’exemple suivant montre une liaison de déclencheur de minuteur dans un fichier function.json et une fonction JavaScript qui utilise la liaison.The following example shows a timer trigger binding in a function.json file and a JavaScript function that uses the binding. La fonction écrit un journal indiquant si cet appel de fonction est dû à une occurrence de planification manquée.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. L’objet de minuteur est transmis à la fonction.A timer object is passed into the function.

Voici les données de liaison dans le fichier function.json :Here's the binding data in the function.json file:

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

Voici le code 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();
};

Exemple PythonPython example

L’exemple suivant utilise une liaison de déclencheur de minuteur dont la configuration est décrite dans le fichier function.json.The following example uses a timer trigger binding whose configuration is described in the function.json file. La véritable fonction Python qui utilise la liaison est décrite dans le fichier init.py.The actual Python function that uses the binding is described in the init.py file. L’objet transmis à la fonction est de type Objet azure.functions.TimerRequest.The object passed into the function is of type azure.functions.TimerRequest object. La logique de fonction écrit dans les journaux indiquant si l’appel est dû à une occurrence de planification manquée.The function logic writes to the logs indicating whether the current invocation is due to a missed schedule occurrence.

Voici les données de liaison dans le fichier function.json :Here's the binding data in the function.json file:

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

Voici le code 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)

AttributsAttributes

Dans les bibliothèques de classes C#, utilisez l’attribut TimerTriggerAttribute.In C# class libraries, use the TimerTriggerAttribute.

Le constructeur de l’attribut prend une expression CRON ou TimeSpan.The attribute's constructor takes a CRON expression or a TimeSpan. Vous pouvez utiliser TimeSpan uniquement si l’application de fonction s’exécute sur un plan App Service.You can use TimeSpan only if the function app is running on an App Service plan. L’exemple suivant illustre une expression 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}");
}

ConfigurationConfiguration

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json et l’attribut TimerTrigger.The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype n/an/a Doit avoir la valeur « timerTrigger ».Must be set to "timerTrigger". Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a Doit être défini sur « in ».Must be set to "in". Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/an/a Nom de la variable qui représente l’objet de minuteur dans le code de la fonction.The name of the variable that represents the timer object in function code.
scheduleschedule ScheduleExpressionScheduleExpression Une expression CRON ou une valeur TimeSpan.A CRON expression or a TimeSpan value. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service.A TimeSpan can be used only for a function app that runs on an App Service Plan. Vous pouvez placer l’expression de planification dans un paramètre d’application et définir cette propriété selon le nom du paramètre d’application encapsulé dans les signes % , comme sur cet exemple : « %ScheduleAppSetting% ».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 Si la valeur est true, la fonction est appelée au démarrage du runtime.If true, the function is invoked when the runtime starts. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité.For example, the runtime starts when the function app wakes up after going idle due to inactivity. Lorsque l’application de fonction redémarre en raison de modifications apportées à la fonction, et lorsque l’application de fonction augmente la taille des instances. Par conséquent, la propriété runOnStartup doit être rarement, voire jamais, définie sur true, notamment en production.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 Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non.Set to true or false to indicate whether the schedule should be monitored. La surveillance de planification conserve les occurrences de planification pour garantir la maintenance correcte de cette dernière même en cas de redémarrage des instances de l’application de fonction.Schedule monitoring persists schedule occurrences to aid in ensuring the schedule is maintained correctly even when function app instances restart. Si elle n’est pas définie explicitement, la valeur par défaut est true pour les planifications dont l’intervalle de récurrence est supérieur ou égal à 1 minute.If not set explicitly, the default is true for schedules that have a recurrence interval greater than or equal to 1 minute. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false.For schedules that trigger more than once per minute, the default is false.

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Attention

Nous vous déconseillons de définir la propriété runOnStartup sur true en production.We recommend against setting runOnStartup to true in production. Si vous utilisez cette définition, le code s’exécute à des moments extrêmement imprévisibles.Using this setting makes code execute at highly unpredictable times. Dans certains paramètres de production, ces exécutions supplémentaires peuvent entraîner des coûts sensiblement plus élevés pour les applications hébergées dans les plans Consommation.In certain production settings, these extra executions can result in significantly higher costs for apps hosted in Consumption plans. Par exemple, avec la propriété runOnStartup activée, le déclencheur est appelé à chaque fois que votre Function App est mise à l’échelle.For example, with runOnStartup enabled the trigger is invoked whenever your function app is scaled. Veillez à bien comprendre le comportement en production de vos fonctions avant d’activer la propriété runOnStartup en production.Make sure you fully understand the production behavior of your functions before enabling runOnStartup in production.

UsageUsage

Lorsqu’une fonction de déclencheur de minuteur est appelée, l’objet minuteur est transmis à la fonction.When a timer trigger function is invoked, a timer object is passed into the function. Le code JSON suivant est un exemple de représentation de l’objet minuteur.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 propriété IsPastDue est true lorsque l’appel de fonction en cours arrive plus tard que prévu.The IsPastDue property is true when the current function invocation is later than scheduled. Par exemple, un redémarrage de la fonction d’application peut entraîner l’échec d’un appel.For example, a function app restart might cause an invocation to be missed.

Expressions NCRONTABNCRONTAB expressions

Azure Functions utilise la bibliothèque NCronTab pour interpréter les expressions NCRONTAB.Azure Functions uses the NCronTab library to interpret NCRONTAB expressions. Une expression NCRONTAB est semblable à une expression CRON, à ceci près qu’elle comprend un sixième champ supplémentaire au début pour utiliser la précision de temps en secondes :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}

Chaque champ peut être associé aux types de valeurs suivants :Each field can have one of the following types of values:

TypeType ExemplesExample En cas de déclenchementWhen triggered
Une valeur spécifiqueA specific value "0 5 * * * *""0 5 * * * *" à hh:05:00 où hh correspond à toutes les heures (une fois par heure)at hh:05:00 where hh is every hour (once an hour)
Toutes les valeurs (*)All values (*) "0 * 5 * * *""0 * 5 * * *" à 5:mm:00 chaque jour, où mm correspond à toutes les minutes de l’heure (60 fois par jour)at 5:mm:00 every day, where mm is every minute of the hour (60 times a day)
Une plage (opérateur -)A range (- operator) "5-7 * * * * *""5-7 * * * * *" à hh:mm:05, hh:mm:06 et hh:mm:07 où hh:mm correspond à toutes les minutes de toutes les heures (3 fois par minute)at hh:mm:05,hh:mm:06, and hh:mm:07 where hh:mm is every minute of every hour (3 times a minute)
Un ensemble de valeurs (opérateur ,)A set of values (, operator) "5,8,10 * * * * *""5,8,10 * * * * *" à hh:mm:05, hh:mm:08 et hh:mm:10 où hh:mm correspond à toutes les minutes de toutes les heures (3 fois par minute)at hh:mm:05,hh:mm:08, and hh:mm:10 where hh:mm is every minute of every hour (3 times a minute)
Une valeur d’intervalle (opérateur /)An interval value (/ operator) "0 */5 * * * *""0 */5 * * * *" à hh:05:00, hh:10:00, hh:15:00 et ainsi de suite jusqu’à hh:55:00, où hh correspond à toutes les heures (12 fois par heure)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)

Pour spécifier les mois ou les jours, vous pouvez utiliser des valeurs numériques, des noms ou des abréviations de noms :To specify months or days you can use numeric values, names, or abbreviations of names:

  • Pour les jours, les valeurs numériques vont de 0 à 6 (ici, 0 représente « dimanche »).For days, the numeric values are 0 to 6 where 0 starts with Sunday.
  • Les noms sont en anglais.Names are in English. Par exemple : Monday, January.For example: Monday, January.
  • Les noms sont sensibles à la casse.Names are case-insensitive.
  • Les noms peuvent être abrégés.Names can be abbreviated. La longueur d’abréviation recommandée est de trois lettres.Three letters is the recommended abbreviation length. Par exemple : Mon, Jan.For example: Mon, Jan.

Exemples NCRONTABNCRONTAB examples

Voici quelques exemples d’expressions NCRONTAB que vous pouvez utiliser pour le déclencheur de minuteur dans Azure Functions.Here are some examples of NCRONTAB expressions you can use for the timer trigger in Azure Functions.

ExemplesExample En cas de déclenchementWhen triggered
"0 */5 * * * *" une fois toutes les cinq minutesonce every five minutes
"0 0 * * * *" une fois toutes les heuresonce at the top of every hour
"0 0 */2 * * *" une fois toutes les deux heuresonce every two hours
"0 0 9-17 * * *" une fois toutes les heures entre 9h et 17honce every hour from 9 AM to 5 PM
"0 30 9 * * *" à 9h30 tous les joursat 9:30 AM every day
"0 30 9 * * 1-5" à 9h30 tous les jours de la semaineat 9:30 AM every weekday
"0 30 9 * Jan Mon" à 9h30 tous les lundis en janvierat 9:30 AM every Monday in January

Fuseaux horaires NCRONTABNCRONTAB time zones

Les nombres d’une expression CRON font référence à une heure et à une date, pas à un intervalle de temps.The numbers in a CRON expression refer to a time and date, not a time span. Par exemple, un 5 dans le champ hour correspond à 17h, pas à toutes les 5 heures.For example, a 5 in the hour field refers to 5:00 AM, not every 5 hours.

Le fuseau horaire par défaut utilisé avec les expressions CRON est le Temps universel coordonné (UTC).The default time zone used with the CRON expressions is Coordinated Universal Time (UTC). Pour baser votre expression CRON sur un autre fuseau horaire, créez un paramètre d’application nommé WEBSITE_TIME_ZONE pour votre application de fonction.To have your CRON expression based on another time zone, create an app setting for your function app named WEBSITE_TIME_ZONE. Définissez la valeur sur le nom du fuseau horaire souhaité comme indiqué dans l’index des fuseaux horaires de Microsoft.Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

Par exemple, l’heure de l’Est correspond à UTC-05:00.For example, Eastern Standard Time is UTC-05:00. Pour que votre déclencheur de minuteur se déclenche à 10:00 AM est tous les jours, utilisez l’expression NCRONTAB suivante qui compte pour le fuseau horaire 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 * * *"

Sinon, vous pouvez créer un paramètre d’application pour votre application de fonction nommé WEBSITE_TIME_ZONE et définir la valeur sur Est.Or create an app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. Utilisez ensuite l’expression NCRONTAB suivante :Then uses the following NCRONTAB expression:

"0 0 10 * * *"

Quand vous utilisez WEBSITE_TIME_ZONE, l’heure est ajustée en fonction des changements d’heure du fuseau horaire spécifique (par exemple, pour tenir compte de l’heure d’été).When you use WEBSITE_TIME_ZONE, the time is adjusted for time changes in the specific timezone, such as daylight savings time.

TimeSpanTimeSpan

TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service.A TimeSpan can be used only for a function app that runs on an App Service Plan.

Contrairement à une expression CRON, une valeur TimeSpan spécifie l’intervalle de temps entre chaque appel de fonction.Unlike a CRON expression, a TimeSpan value specifies the time interval between each function invocation. Quand une fonction se termine après une exécution plus longue que l’intervalle spécifié, le minuteur rappelle immédiatement la fonction.When a function completes after running longer than the specified interval, the timer immediately invokes the function again.

Exprimé sous forme de chaîne, le format TimeSpan est hh:mm:ss lorsque la valeur de hh est inférieure à 24.Expressed as a string, the TimeSpan format is hh:mm:ss when hh is less than 24. Lorsque les deux premiers chiffres sont 24 ou plus, le format est dd:hh:mm.When the first two digits are 24 or greater, the format is dd:hh:mm. Voici quelques exemples :Here are some examples:

ExemplesExample En cas de déclenchementWhen triggered
"01:00:00""01:00:00" toutes les heuresevery hour
"00:01:00""00:01:00" chaque minuteevery minute
"24:00:00""24:00:00" Toutes les 24 heuresevery 24 hours
"1.00:00:00""1.00:00:00" chaque jourevery day

Montée en chargeScale-out

Si une application de fonction augmente la taille de plusieurs instances, une seule instance de fonction déclenchée par minuteur est exécutée sur toutes les instances.If a function app scales out to multiple instances, only a single instance of a timer-triggered function is run across all instances.

Applications de fonction qui partagent du stockageFunction apps sharing Storage

Si vous partagez des comptes de stockage entre des applications de fonction qui ne sont pas déployées sur App Service, vous devrez peut-être affecter explicitement l’ID d’hôte à chaque application.If you are sharing storage accounts across function apps that are not deployed to app service, you might need to explicitly assign host ID to each app.

Version de FunctionsFunctions version ParamètreSetting
2.x2.x AzureFunctionsWebHost__hostid variable d’environnementAzureFunctionsWebHost__hostid environment variable
1.x1.x id dans host.jsonid in host.json

Vous pouvez omettre la valeur d’identification ou définir manuellement la configuration d’identification de chaque application de fonction sur une valeur différente.You can omit the identifying value or manually set each function app's identifying configuration to a different value.

Le déclencheur du minuteur utilise un verrou de stockage pour s’assurer qu’il n’y a qu’une seule instance du minuteur lorsqu’une application de fonction augmente la taille de plusieurs instances.The timer trigger uses a storage lock to ensure that there is only one timer instance when a function app scales out to multiple instances. Si deux applications de fonction partagent la même configuration d’identification et que chacune utilise un déclencheur de minuteur, un seul minuteur s’exécute.If two function apps share the same identifying configuration and each uses a timer trigger, only one timer runs.

Comportement pour les nouvelles tentativesRetry behavior

À la différence du déclencheur de file d’attente, le déclencheur de minuteur n’effectue pas de nouvelle tentative après l’échec d’une fonction.Unlike the queue trigger, the timer trigger doesn't retry after a function fails. En cas d’échec d’une fonction, elle n’est pas rappelée avant la prochaine période planifiée.When a function fails, it isn't called again until the next time on the schedule.

Résolution de problèmesTroubleshooting

Pour plus d’informations sur la procédure à suivre lorsque le déclencheur du minuteur ne fonctionne pas comme prévu, consultez Investigating and reporting issues with timer triggered functions not firing (Examen et rapport des problèmes concernant l’absence de déclenchement des fonctions déclenchées par minuteur).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.

Étapes suivantesNext steps