bin | 1 year ago | ||
conditor-dumps | 5 days ago | ||
corhal-dumps | 8 months ago | ||
doiwos-dumps | 12 months ago | ||
halcnrs-dumps | 1 year ago | ||
halinria-dumps | 2 years ago | ||
wos-dumps | 1 year ago | ||
.gitignore | 12 months ago | ||
Makefile | 2 years ago | ||
README.md | 1 year ago | ||
apil-dumps-config.json | 1 year ago | ||
conditor-dumps-config.json | 1 year ago | ||
corhal-dumps-config.json | 2 years ago | ||
doiwos-dumps-config.json | 2 years ago | ||
halcnrs-dumps-config.json | 1 year ago |
Le dépôt tdm/web-dumps contient les programmes de plusieurs procédures automatiques de collecte et d'enrichissement de données.
Ces procédures, dont le principe est similaire, sont chacune rangée dans un répertoire de premier niveau.
. ├── apil-dumps ├── apil-dumps-config.json ├── corhal-dumps ├── corhal-dumps-config.json ├── halcnrs-dumps ├── halcnrs-dumps-config.json ├── halinria-dumps └── wos-dumps
Chaque répertoire est destiné à être déployé dans une instance de l'application lodex-contab
sur ezMaster.
À intervalle régulier, les scripts ezs sont executés. Leur objectif 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:
Dans le deuxième cas, on n'exécute la procédure que si le fichier dont elle dépend a changé.
Les procédures étant déployées sur un serveur (avec ezmaster), elles ont l'avantage de pouvoir durer autant que nécessaire, et ne sont pas contraintes 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.
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:
CronRule
: quand déclencher l'actionTarget
: quel fichier on veut obtenirRunOnStartup
: 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 https://crontab.guru/ 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 champFileName
plutôt que le champTarget
(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
).
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).
{ "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 } ] }
Chaque nom de répertoire doit être en deux parties, séparées par un tiret.
Ceci pour respecter la nomenclature des instances dans ezmaster.
Afin de faciliter le déploiement (et de le limiter à un répertoire), on peut 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 dépôt. Leur seul paramètre est le nom du répertoire.
⚠️ Attention : Vérifiez que vous êtes bien à la racine du projet avant de lancer la commande.
Exemple:
$ 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] 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 programme.
Il suffit de la coller dans la clé files.zip
de l'instance de lodex-crontab
.
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 qui les ont produits.
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.