diff --git a/README.md b/README.md index 8a7df15..12e98c5 100644 --- a/README.md +++ b/README.md @@ -26,19 +26,24 @@ À intervalle régulier, les scripts [ezs](https://inist-cnrs.github.io/ezs/#/?id=ezs) sont executés. Leur objectif -est en général de télécharger des nettoyer, éventuellement de les nettoyer, de +est en général de télécharger des données, éventuellement de les nettoyer, de les reformater, et de les enrichir. Ces intervalles sont paramétrables très finement. +> 📗 Techniquement, il n'est pas requis que ces scripts contiennent une étape de +> collecte des données. Il peut suffire d'avoir un fichier de données à traiter. +> Ceci dit, ce sera le plus souvent le cas, nous supposerons donc dans la suite +> que cette étape est présente. + Les requêtes exécutées par les scripts peuvent ramener des données différentes à chaque fois (les données les plus récentes) ou bien les mêmes, en fonction d'un fichier de paramétrage dont la nature peut varier selon les procédures. Il y a deux modes à ces procédures: -1. exécution d'un script particulier -2. obtention d'un fichier particulier, en fonction d'une table d'identifiant / +1. exécution d'un (ou plusieurs) script(s) particulier(s) +2. obtention d'un fichier particulier, en fonction d'une table d'identifiants / d'un fichier contenant une requête / ou autre. Dans le deuxième cas, on n'exécute la procédure que si le fichier dont elle @@ -49,6 +54,126 @@ par l'extinction ou la mise en veille d'un poste de travail à la fin d'une journée de travail, voire la perte de réseau lors d'un déplacement. +### Configuration + +La partie `tasks` de la configuration de l'instance de `lodex-crontab` dans +ezmaster permet de déclencher le traitement. + +C'est un tableau JSON d'objets comprenant trois champs: + +1. `CronRule`: quand déclencher l'action +2. `Target`: quel fichier on veut obtenir +3. `RunOnStartup`: doit-on déclencher l'action _aussi_ au (re-)démarrage de + l'instance. + +Comme c'est un tableau, on peut spécifier plusieurs tâches dans la même +configuration, ce n'est pas gênant. + +#### `CronRule` + +Champ au format `crontab` (commande UNIX permettant d'exécuter des programmes à +des moments pré-programmés sur une machine locale). + +> 💡 Il est conseillé d'utiliser le site pour vérifier à +> quel(s) moment(s) l'action sera déclenchée. + +La valeur `0 1 * * *` signifie: à une heure du matin, tous les jours. + +Le zéro du début indique les minutes, le 1 suivant indique l'heure. +Viennent ensuite le jour (du mois), le mois puis le jour (de la semaine). + +L'étoile signifie « _tous_ », alors qu'un intervalle s'écrit avec un tiret. +Ainsi `0 8-17 * * *` veut dire que l'action se déclenchera tous les jours, à +chaque heure de travail (de 8 heures à 17 heures). +Le `/` représente un pas: `0 8-17/2 * * *` signifie tous les jours toutes les +deux heures entre 8 heures et 17 heures. +Pour bien faire, on peut aussi limiter aux jours de la semaine (lundi à +vendredi): `0 8-17/2 * * 1-5`. +Cette expression peut servir pendant un développement, mais on verra que +`RunOnStartup` est plus pratique pour ça. + +> 📗 Si la procédure a déjà été exécutée au complet, et qu'aucun fichier n'a été +> supprimé ou remplacé, elle ne sera pas rejouée (de toute façon, elle aurait +> fourni les mêmes résultats). + +> ⚠ Il peut y avoir des cas où rejouer une procédure donne des résultats différents. +> Dans ces cas, il est conseillé d'utiliser le champ `FileName` plutôt que le +> champ `Target` (qu'on préféra dans les cas où rejouer les mêmes scripts donne +> les mêmes résultats). + +#### `Target` / `FileName` + +`Target` est le chemin du fichier qu'on veut produire. + +Par défaut, c'est le fichier produit par la dernière étape (le dernier script). +Mais si par exemple on veut éviter cette dernière étape (peut-être parce qu'elle +n'est pas encore efficace ?), on peut remplacer la valeur de target par +le chemin d'un fichier résultant d'une étape précédente. +Il faut que ce soit le chemin exact à l'intérieur du répertoire de l'instance. +Les fichiers des étapes suivantes ne seront alors pas regénérés. + +Toutes étapes nécessaires (et seulement elles) sont rejouées jusqu'à produire ce +fichier. +Cela signifie que si aucun fichier d'une étape précédente (ou le fichier numéroté `00-...`) n'est plus récent que le fichier `Target`, il ne sera pas regénéré. +Pour forcer la regénération d'un fichier, il suffit de le supprimer. + +> 📗 Ces règles correspondent à celles d'un `Makefile`, car c'est ce qui est +> utilisé. + +On peut aussi choisir l'alternative à `Target`, c'est-à-dire `FileName`. + +De cette manière, on exécute inconditionnellement un script ezs (aux moments +sélectionnés par [`CronRule`](#cronrule)). +C'est intéressant quand on veut lancer à intervalles réguliers une requête dont +on sait que les réponses seront différentes suivant le moment où elle est +lancée, par exemple. + +Le champ `FileName` contient le chemin du fichier à exécuter, relativement à la +racine du répertoire WebDav de l'application. + +#### `RunOnStartup` + +Ce booléen est à `true` par défaut, mais il vaut mieux, une fois la procédure au +point, le positionner à `false`. +Quand il est vrai, la procédure est lancée à chaque (re-)démarrage de +l'instance, c'est-à-dire aussi quand on met à jour la configuration. +Ceci dit, quand on utilise `Target`, ne sont jouées que les étapes qui le +nécessitent (le fichier source de l'étape a changé, ou a été supprimé), ce n'est +pas très grave de le laisser à `true` (mais ce n'est pas le cas quand on utilise +`FileName`). + +> 💡 Pour forcer l'exécution d'une étape et des suivantes, il suffit de +> supprimer le fichier résultant de cette étape (dont le nom commence par le +> numéro de l'étape). + +### Exemple de configuration complète + +```json +{ + "environnement": { + "CRON_VERBOSE": true, + "EZS_VERBOSE": false, + "DEBUG": "ezs", + }, + "packages": [ + "@ezs/core@2.1.0", + "@ezs/basics@1.22.3", + "@ezs/analytics@2.0.2" + ], + + "files" : { + "zip": "https://gitbucket.inist.fr/parmentf/giec-wos/archive/doiswos-dumps/doiwos-dumps-1.0.0.zip" + }, + "tasks": [ + { + "CronRule": "0 1 * * *", + "Target": "data/09-corpus-simple-cnrs.json", + "RunOnStartup": true + } + ] +} +``` + ## Développement Chaque nom de répertoire doit être en deux parties, séparées par un tiret. @@ -60,21 +185,21 @@ utiliser les helpers du Makefile (`make version-major`, `make version-minor`, `make version-patch`). -Ils se chargent de mettre un *tag* git sur un répertoire et de le pousser sur le +Ils se chargent de mettre un _tag_ git sur un répertoire et de le pousser sur le dépôt. Leur seul paramètre est le nom du répertoire. Exemple: ```bash -$ make version-major giec-wos +$ make version-major doiwos-dumps Décompte des objets: 1, fait. Écriture des objets: 100% (1/1), 185 bytes | 185.00 KiB/s, fait. Total 1 (delta 0), reused 0 (delta 0) remote: Updating references: 100% (1/1) To ssh://gitbucket.inist.fr:22222/tdm/web-dumps.git - * [new tag] giec-wos@1.0.0 -> giec-wos@1.0.0 -Nouvelle version créée: giec-wos@1.0.0 -URL à utiliser: https://gitbucket.inist.fr/tdm/web-dumps/archive/giec-wos/giec-wos@1.0.0.zip + * [new tag] doiwos-dumps@1.0.0 -> doiwos-dumps@1.0.0 +Nouvelle version créée: doiwos-dumps@1.0.0 +URL à utiliser: https://gitbucket.inist.fr/tdm/web-dumps/archive/doiwos-dumps/doiwos-dumps@1.0.0.zip ``` L'URL fournie sert à la configuration de l'instance, et permet la mise à jour du @@ -84,16 +209,16 @@ ### Bonnes pratiques -Mettre un fichier de configuration d'exemple, au même nom que le répertoire + +1. Mettre un fichier de configuration d'exemple, au même nom que le répertoire + `.json` pour qu'on puisse le copier et l'adapter dans la configuration de l'instance dans ezMaster. Cette configuration doit contenir les paquets npm nécessaires à l'exécution des scripts. -Numéroter les fichiers de données produits en fonction des numéros des étapes +2. Numéroter les fichiers de données produits en fonction des numéros des étapes qui les ont produits. -Numéroter les scripts ezs selon les étapes qu'ils représentent (un nombre à deux +3. Numéroter les scripts ezs selon les étapes qu'ils représentent (un nombre à deux chiffres au début du nom du fichier, comme pour les données qu'ils produisent). -Documenter chaque procédure, dans un README à l'intérieur de son répertoire. +4. Documenter chaque procédure, dans un README à l'intérieur de son répertoire. diff --git a/doiwos-dumps/README.md b/doiwos-dumps/README.md index a00b5b6..633e3cc 100644 --- a/doiwos-dumps/README.md +++ b/doiwos-dumps/README.md @@ -536,7 +536,7 @@ > supprimer le fichier résultant de cette étape (dont le nom commence par le > numéro de l'étape). -### Exemple de configration complète +### Exemple de configuration complète ```json {