Déclencheur de minuteur pour Azure Functions
Cet article explique comment utiliser des déclencheurs de minuteur dans Azure Functions. Un déclencheur de minuteur vous permet d’exécuter une fonction de manière planifiée.
Il s’agit des informations de référence pour les développeurs Azure Functions. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :
Références pour les développeurs C# :
Pour savoir comment exécuter manuellement une fonction déclenchée par un minuteur, consultez Exécuter manuellement une fonction non déclenchée via HTTP.
La prise en charge de cette liaison est automatique dans tous les environnements de développement. Vous n’avez pas besoin d’installer manuellement le package ou d’enregistrer l’extension.
Le code source du package de l’extension du minuteur se trouve dans le référentiel GitHub azure-webjobs-sdk-extensions.
Exemple
Cet exemple montre une fonction C# qui s’exécute chaque fois que les minutes ont une valeur divisible par cinq. Par exemple, lorsque la fonction démarre à 18:55:00, l’exécution suivante a lieu à 19:00:00. Un objet TimerInfo
est transmis à la fonction.
Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :
- Bibliothèque de classes in-process : fonction C# compilée exécutée dans le même processus que le runtime Functions.
- Bibliothèque de classes de processus Worker isolé : fonction C# compilée exécutée dans un processus Worker isolé du runtime. Un processus Worker isolé est nécessaire pour prendre en charge les fonctions C# s’exécutant sur les versions non LTS de .NET et du .NET Framework.
- Script C# : principalement utilisé lors de la création de fonctions C# dans le Portail Azure.
[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}");
}
L’exemple suivant lance et exécute la fonction toutes les cinq minutes. L’annotation @TimerTrigger
sur la fonction définit le programme avec le même format de chaîne de caractères que les @TimerTrigger
.
@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’exemple suivant illustre une liaison de déclencheur de minuteur dans un fichier function.json et un code de fonction qui utilise la liaison, où une instance représentant le minuteur est transmise à la fonction. La fonction écrit un journal indiquant si cet appel de fonction est dû à une occurrence de planification manquée.
Voici les données de liaison dans le fichier function.json :
{
"schedule": "0 */5 * * * *",
"name": "myTimer",
"type": "timerTrigger",
"direction": "in"
}
Voici le code JavaScript :
module.exports = async 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);
};
Voici le code de la fonction de minuteur dans le fichier 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"
Voici le code Python, où l’objet transmis à la fonction est de type Objet azure.functions.TimerRequest.
import datetime
import logging
import azure.functions as func
def main(mytimer: func.TimerRequest) -> None:
utc_timestamp = datetime.datetime.now(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)
Attributs
La bibliothèque C# In-process utilise un TimerTriggerAttribute de Microsoft.Azure.WebJobs.Extensions, tandis que la bibliothèque C# processus Worker isolé utilise un TimerTriggerAttribute de Microsoft.Azure.Functions.Worker.Extensions.Timer pour définir la fonction.
Le script C# utilise à la place un fichier de configuration function.json.
Propriété d’attribut | Description |
---|---|
Planification | Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. 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é entre les signes %, par exemple %ScheduleAppSetting% . |
RunOnStartup | Si la valeur est true , la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété RunOnStartup doit rarement, voire jamais, être définie sur true , notamment en production. |
UseMonitor | Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. 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. 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. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false . |
Annotations
L’annotation @TimerTrigger
sur la fonction définit le schedule
avec le même format de chaîne que les expressions CRON. L’annotation prend en charge les paramètres suivants :
Configuration
Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.
Propriété function.json | Description |
---|---|
type | Doit avoir la valeur « timerTrigger ». Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure. |
direction | Doit être défini sur « in ». Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure. |
name | Nom de la variable qui représente l’objet de minuteur dans le code de la fonction. |
schedule | Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. 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% ». |
runOnStartup | Si la valeur est true , la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété runOnStartup doit rarement, voire jamais, être définie sur true , notamment en production. |
useMonitor | Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. 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. 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. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false . |
Lorsque vous développez en local, ajoutez vos paramètres d’application dans le fichier local.settings.json de la collection .
Attention
Ne définissez pas runOnStartup sur true
en production. Si vous utilisez cette définition, le code s’exécute à des moments extrêmement imprévisibles. 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 un plan Consommation. Par exemple, avec la propriété runOnStartup activée, le déclencheur est appelé à chaque fois que votre Function App est mise à l’échelle. Veillez à bien comprendre le comportement en production de vos fonctions avant d’activer la propriété runOnStartup en production.
Pour obtenir des exemples complets, consultez la section Exemple.
Usage
Lorsqu’une fonction de déclencheur de minuteur est appelée, l’objet minuteur est transmis à la fonction. Le code JSON suivant est un exemple de représentation de l’objet minuteur.
{
"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 propriété isPastDue
est true
lorsque l’appel de fonction en cours arrive plus tard que prévu. Par exemple, un redémarrage de la fonction d’application peut entraîner l’échec d’un appel.
Expressions NCRONTAB
Azure Functions utilise la bibliothèque NCronTab pour interpréter les expressions NCRONTAB. 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 :
{second} {minute} {hour} {day} {month} {day-of-week}
Chaque champ peut être associé aux types de valeurs suivants :
Type | Exemple | En cas de déclenchement |
---|---|---|
Une valeur spécifique | 0 5 * * * * |
Une fois par heure du jour, à la 5e minute de chaque heure |
Toutes les valeurs (* ) |
0 * 5 * * * |
Une fois par minute, à partir de la 5e heure |
Une plage (opérateur - ) |
5-7 * * * * * |
Trois fois par minute - aux secondes 5 à 7 de chaque minute de chaque heure de chaque jour |
Un ensemble de valeurs (opérateur , ) |
5,8,10 * * * * * |
Trois fois par minute - aux secondes 5, 8 et 10 de chaque minute de chaque heure de chaque jour |
Une valeur d’intervalle (opérateur / ) |
0 */5 * * * * |
12 fois par heure - à la seconde 0 de la 5e minute de chaque heure de chaque jour |
Pour spécifier les mois ou les jours, vous pouvez utiliser des valeurs numériques, des noms ou des abréviations de noms :
- Pour les jours, les valeurs numériques vont de 0 à 6 (ici, 0 représente « dimanche »).
- Les noms sont en anglais. Par exemple :
Monday
,January
. - Les noms sont sensibles à la casse.
- Les noms peuvent être abrégés. La longueur d’abréviation recommandée est de trois lettres. Par exemple :
Mon
,Jan
.
Exemples NCRONTAB
Voici quelques exemples d’expressions NCRONTAB que vous pouvez utiliser pour le déclencheur de minuteur dans Azure Functions.
Exemple | En cas de déclenchement |
---|---|
0 */5 * * * * |
une fois toutes les cinq minutes |
0 0 * * * * |
une fois toutes les heures |
0 0 */2 * * * |
une fois toutes les deux heures |
0 0 9-17 * * * |
une fois toutes les heures entre 9h et 17h |
0 30 9 * * * |
à 9h30 tous les jours |
0 30 9 * * 1-5 |
à 9h30 tous les jours de la semaine |
0 30 9 * Jan Mon |
à 9h30 tous les lundis en janvier |
Notes
L’expression NCRONTAB prend en charge le format à cinq champs et le format à six champs. Le sixième champ comprend une valeur correspondant aux secondes qui est placée au début de l'expression.
Fuseaux horaires NCRONTAB
Les nombres d’une expression CRON font référence à une heure et à une date, pas à un intervalle de temps. Par exemple, un 5 dans le champ hour
correspond à 17h, pas à toutes les 5 heures.
Le fuseau horaire par défaut utilisé avec les expressions CRON est le Temps universel coordonné (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.
La valeur de ce paramètre dépend du système d’exploitation et du plan sur lequel l’application de fonction s’exécute.
Système d’exploitation | Plan | Valeur |
---|---|---|
Windows | Tous | Définissez la valeur sur le nom du fuseau horaire souhaité comme indiqué par la deuxième ligne de chaque paire donnée par la commande Windows tzutil.exe /L |
Linux | Premium Dédié |
Définissez la valeur sur le nom du fuseau horaire souhaité comme indiqué dans la base de données tz. |
Notes
WEBSITE_TIME_ZONE
n’est pas pris en charge sur le plan consommation Linux.
Par exemple, l’heure de la côte est des États-Unis (représentée par Eastern Standard Time
(Windows) ou America/New_York
(Linux)) utilise actuellement l’heure UTC (temps universel coordonné) 05:00 pendant l’heure standard et l’heure UTC 04:00 pendant l’heure d’été. Pour qu’un déclencheur de minuteur s’active à 10:00 (heure de la côte est) chaque jour, créez un paramètre d’application nommé WEBSITE_TIME_ZONE
pour votre application de fonction, définissez la valeur sur Eastern Standard Time
(Windows) ou sur America/New_York
(Linux), puis utilisez l’expression NCRONTAB suivante :
"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, notamment pour tenir compte de l’heure d’été et des changements de l’heure standard.
TimeSpan
TimeSpan
peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service.
Contrairement à une expression CRON, une valeur TimeSpan
spécifie l’intervalle de temps entre chaque appel de fonction. Quand une fonction se termine après une exécution plus longue que l’intervalle spécifié, le minuteur rappelle immédiatement la fonction.
Exprimé sous forme de chaîne, le format TimeSpan
est hh:mm:ss
lorsque la valeur de hh
est inférieure à 24. Lorsque les deux premiers chiffres sont 24 ou plus, le format est dd:hh:mm
. Voici quelques exemples :
Exemple | En cas de déclenchement |
---|---|
"01:00:00" | toutes les heures |
"00:01:00" | chaque minute |
"25:00:00:00" | Tous les 25 jours |
"1.00:00:00" | chaque jour |
Montée en charge
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. Elle ne se déclenchera plus si un appel en attente est toujours en cours d’exécution.
Applications de fonction qui partagent du stockage
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.
Version de Functions | Paramètre |
---|---|
2.x (et ultérieures) | AzureFunctionsWebHost__hostid variable d’environnement |
1.x | id dans id |
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.
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. 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.
Comportement pour les nouvelles tentatives
À 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. En cas d’échec d’une fonction, elle n’est pas rappelée avant la prochaine période planifiée.
Appeler manuellement un déclencheur de retardateur
Le déclencheur de retardateur pour Azure Functions fournit un webhook HTTP qui peut être appelé pour déclencher manuellement la fonction. Cela peut être très utile dans les scénarios suivants.
- Tests d’intégration
- Échanges d’emplacements dans le cadre d’une activité de test d'acceptation de build ou de préparation
- Déploiement initial d’une fonction pour remplir immédiatement un cache ou une table de recherche dans une base de données
Veuillez consulter Exécuter manuellement une fonction non déclenchée via HTTP pour plus de détails sur la façon d’appeler manuellement une fonction déclenchée par un retardateur.
Dépannage
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).