Aller au contenu

Synchronisations GTFS externes

Un réseau dont le GTFS est produit ailleurs — par un agrégateur régional, un logiciel de graphicage — n'a pas à l'importer à la main. Une synchronisation externe récupère chaque jour le fichier à une URL, et l'importe puis le publie s'il a changé depuis la veille.

Une synchronisation, un fichier, une heure

Une synchronisation porte l'URL du fichier et l'heure à laquelle le récupérer. Chaque synchronisation a sa propre exécution quotidienne : deux réseaux synchronisés ne passent pas forcément à la même heure. On choisit l'heure après celle à laquelle la source génère son fichier, pour ne pas récupérer celui de la veille.

Endpoint Rôle
GET /api/v4/groups/<group_id>/gtfs/external-synchronizations Liste les synchronisations du groupe et le résultat de leur dernière exécution
POST /api/v4/groups/<group_id>/gtfs/external-synchronizations Crée une synchronisation
PATCH /api/v4/groups/<group_id>/gtfs/external-synchronizations/<synchronization_id> Change son URL, son heure, son fuseau ou la suspend

Ces routes demandent le rôle admin sur le groupe.

Les réglages

  • url : l'URL HTTP(S) du fichier. Son hôte doit se résoudre uniquement vers des adresses publiques : une adresse locale, privée ou interne est refusée en 422 GTFS_EXTERNAL_SYNCHRONIZATION_URL_REJECTED.
  • time : l'heure locale de récupération, au format "HH:MM", 00:00 par défaut. Une heure avec décalage (01:00+01:00) est refusée : c'est le fuseau qui suit le changement d'heure.
  • timezone : le fuseau IANA de cette heure ("Europe/Paris"). Sans lui, c'est le fuseau du groupe, celui du GTFS publié : la synchronisation le suit quand une publication le change. Le remettre à null revient au fuseau du groupe.
  • enabled : false suspend la synchronisation sans la supprimer.

Le résultat de la dernière exécution

Chaque synchronisation garde, en lecture seule, ce qu'a donné sa dernière exécution :

  • last_status : imported (un nouveau fichier importé et publié), unchanged (le même fichier que la dernière fois, rien n'est importé) ou failed ;
  • last_error : la raison d'un échec, vide après un succès ;
  • last_checksum et last_gtfs_id : l'empreinte MD5 du dernier fichier publié et le GTFS qu'il a créé ;
  • last_attempt_at : la date de cette exécution.

Un fichier injoignable est retenté plusieurs fois avant d'être déclaré en échec. Un fichier importé mais dont la publication échoue n'est pas considéré comme publié : la nuit suivante le réimporte.

Le report d'exécution

Le flow Prefect Synchronize external transit files exécute une synchronisation par run, planifié par l'API à l'heure de la synchronisation, et rapporte son résultat par une route interne réservée au super-admin.

Endpoint Rôle
POST /api/v4/groups/<group_id>/gtfs/external-synchronizations/<synchronization_id>/results Enregistre le résultat d'une exécution

Les sous-commandes pysae_admin import-gtfs-external-synchronizations et pysae_admin reconcile-gtfs-external-synchronization-schedules reprennent les synchronisations de l'ancien bloc Prefect et réalignent les planifications du déploiement sur les synchronisations. Tant que la reprise n'est pas faite, l'ancien run quotidien, lancé sans paramètres, traite toujours l'ancien bloc ; la réconciliation supprime son schedule. Les deux sous-commandes se lancent dans la même session, pour qu'aucun réseau ne soit traité deux fois la même nuit.