Fonctionnement du moissonneur bal
Le moissonneur a pour objectif de récupérer les bases Adresse locales disponibles en open data et de les déposer dans la Base Adresse Nationale via l'api-depot.
Le moissonneur-bal effectue différentes actions à intervalles régulières afin de maintenir les données à jour.
- ⏱️ Toutes les 5min, la liste des sources est mises à jour.
- ⏱️ Toutes les heures, le moissonnage automatique des sources (nouvelles et anciennes non moissonnées depuis plus de 24h).
- ⏱️ Toutes les 2min, tous les moissonnages en cours depuis plus de 30min (bloqués) sont supprimés.
- ⏱️ Toutes les 30sec, les demande de moissonnages manuels sont effectuées.
Les sources représentent l'ensemble des points moissonnés. La mise à jour de ces sources s'effectue de deux façons :
- Depuis le fichier
sources.yml
où elles sont divisées en deux parties, whitelist et blacklist. - Récupérées depuis data.gouv.fr sur les organisations vérifiées et grâce au tag
base-adresse-locale
et si le jeu de donnée n’est pas archivé.
Si une source n’est plus disponible entre deux mises à jour, celle-ci est indiquée comme supprimée {_deleted: true}
.
Certaines sources mettant à disposition des BAL non-standard nécessitent un "convertisseur" permettant de générer le fichier BAL/CSV à partir des données publiées par le producteur. Ces convertisseurs se trouvent dans
/converters
.
Une source ne sera moissonnée que si son dernier moissonnage date de plus de 24h.
Il est cependant possible de demander un moissonnage manuellement à condition que la source soit active enabled: true
et qu'aucun moissonnage ne soit déjà en cours.
{
_id: 'xxxxxxxxxxxxxxxx',
_created: '2022-10-20T15:22:12.137Z', // Date de création
_deleted: false, // Date de suppression
converter: null, // Nom du convertisseur nécessaire au traitement de la donnée (optionnel)
data: { // Dernière donnée moissonnée
fileHash: 'xxxxxxxxxxxxxxxx',
fileId: 'xxxxxxxxxxxxxxxx',
harvestDate: '1970-01-01',
harvestId: 'xxxxxxxxxxxxxxxx'
},
description: 'Description de la source',
harvesting: { // Information sur le dernier moissonnage
lastHarvest: '1970-01-01',
lastHarvestStatus: 'completed',
lastHarvestUpdateStatus: 'updated',
harvestingSince: null, // Date indiquant le début du moissonnage
asked: true // La moissonnage a été demandé manuellement
},
license: 'lov2',
model: 'bal' // "bal" ou "custom" pour les données non-conformes nécessitant l’utilisation d'un convertisseur,
organization: {
name: 'Nom de l’organisation',
page: 'https://www.organisation.fr/',
logo: 'https://static.data.gouv.fr/avatars/organisation.png'
},
page: 'https://www.data.gouv.fr/fr/datasets/source/',
title: 'Titre de la source',
type: 'github', // "github" pour les sources issues du fichiers sources.yml ou "datagouv" pour celles récupérées sur data.gouv.fr
url: 'https://url-de-la-source/data.csv', // Lien vers le fichier à moissonner
_updated: '1970-01-01'
}
Lorsque qu’un moissonnage est lancé et un document Harvest
est créé en base de donnée. Ce moissonnage correspond à la source à laquelle il est lié par sa propriété sourceId
.
-
active
: moissonnage en cours -
completed
: moissonnage terminé avec succès -
failed
: moissonnage échoué
{
_id: 'xxxxxxxxxxxxxxxx',
sourceId: 'xxxxxxxxxxxxxxxx',
status: 'active',
error: null, // Message d'erreur si "status === failed"
startedAt: '1970-01-01',
finishedAt: '1970-01-01'
}
Un moissonnage va donner lieu au téléchargement d'un fichier. Lorsque cela est nécessaire (BAL non standard) ce fichier est converti grâce convertisseur dédié à la source.
Taille maximum supporté pour un fichier : 100Mo
Ce fichier est comparé à la version précédente. Si aucune modification n'est constatée alors le fichier actuel de la source est conservé.
Dans le cas contraire, le fichier est validé par le validateur-bal. Si le fichier est illisible ou comporte un trop grand nombre de lignes en erreur, celui-ci est rejeté.
La tolérances des lignes en erreur est + de 5%. En dessous de cette limite, les lignes en erreur sont filtrées, mais les erreurs
uniqueErrors
et le nombre de lignes concernéesnbRowsWithErrors
sont conservées.
Lorsqu’une mise à jour est constatée pendant l’étape d’analyse d'un nouveau fichier, les lignes qu'il contient sont regroupées par commune.
Pour cette révision, comme pour le fichier, ses lignes sont signées et comparées à la révision précédente, puis on détermine l’état de la révision revision.updateStatus
:
-
rejected
: trop d'erreurs pour accepter cette révision (+ de 5%) -
unchanged
: signature identique à la révision précédente pour cette commune -
updated
: nouvelle révision pour la commune
Si updated
on enregistre le fichier (unparsing CSV).
On introduit aussi un flan current: true
qui est placé sur la dernière révision fonctionnelle d'une commune pour une source donnée.
On enregistre les attributs nbRows
et nbRowsWithErrors
.
{
_id: 'xxxxxxxxxxxxxxxx',
fileId: 'xxxxxxxxxxxxxxxx',
sourceId: 'xxxxxxxxxxxxxxxx',
codeCommune: '27115',
updateStatus: 'updated' || 'unchanged',
fileHash: 'xxxxxxxxxxxxxxxx',
dataHash: 'xxxxxxxxxxxxxxxx',
nbRows: 42,
nbRowsWithErrors: 21
}
On regarde la révision publiée actuellement sur l'API.
- Si celle-ci a été publiée par un autre outil que le moissonneur, on ignore avec status:
provided-by-other-client
. - Si celle-ci a été publiée par le moissonneur mais via une autre source de données, on ignore avec status:
provided-by-other-source
. - Si la commune ne dispose pas de révision en vigueur ou si celle-ci provient du moissonneur et de la même source : on publie.
La publication consiste en la production d'un fichier expurgé des lignes en erreurs puisque l'API de dépôt ne supporte pas les fichiers contenant des erreurs.
On publie aussi des métadonnées utiles dans extras :
{
sourceId,
harvestId,
nbRows,
nbRowsWithErrors,
uniqueErrors
}
Le statut final est status: published
.