Skip to content

Fonctionnement du moissonneur bal

Jérôme Desboeufs edited this page Dec 9, 2022 · 5 revisions

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.

Fonctionnement

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.

Sources

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.

Modèle

{
  _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'
}

Moissonnages (harvests)

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.

Les statuts d'un moissonnage

  • active : moissonnage en cours
  • completed : moissonnage terminé avec succès
  • failed : moissonnage échoué

Modèle

{
    _id: 'xxxxxxxxxxxxxxxx',
    sourceId: 'xxxxxxxxxxxxxxxx',
    status: 'active',
    error: null, // Message d'erreur si "status === failed"
    startedAt: '1970-01-01',
    finishedAt: '1970-01-01'
}

Fichiers (files)

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ées nbRowsWithErrors sont conservées.

Révisions (revisions)

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.

Modèle

{
    _id: 'xxxxxxxxxxxxxxxx',
    fileId: 'xxxxxxxxxxxxxxxx',
    sourceId: 'xxxxxxxxxxxxxxxx',
    codeCommune: '27115',
    updateStatus: 'updated' || 'unchanged',
    fileHash: 'xxxxxxxxxxxxxxxx',
    dataHash: 'xxxxxxxxxxxxxxxx',
    nbRows: 42,
    nbRowsWithErrors: 21
  }

Publication sur l'API de dépôt

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.