Publication de l’offre

Description métier

La fonction «Publication» sert à partager en public l’ensemble de vos données en format GTFS ou NeTEx avec vos partenaires.

L’utilisateur autorisé et membre de l’organisation propriétaire du Groupe de Travail peut gérer les publications de données qui sont réalisées automatiquement.

Open

Gestion des publications

Plusieurs Publications peuvent être définies au sein du Groupe de Travail. Chacune définissant un export et les destinations à donner aux informations exportées.

Vous pouvez consulter la liste des publications actuellement définies dans la section “Publications Automatiques” du Groupe de travail.

Open

Il vous est possible de filtrer suivant le type d’export, ainsi que de trier par type et par nom de la publication.

La roue dentée de chaque ligne permet de consulter, éditer ou supprimer (avec confirmation) la publication.

L’utilisateur autorisé et membre de l’organisation propriétaire du Groupe de Travail peut créer et modifier une Publication de données.

Pour chaque Publication, vous définissez :

• le nom (pour mieux identifier son rôle)

• l’activation ou la désactivation

• l’activation ou la désactivation de la Publication Quotidiennement

• les paramètres de l’export

• les destinations

Les paramètres de l’export

Plusieurs types d’export sont proposés par Chouette.

L’export GTFS :

Lors de l’export, un zip est créé contenant les fichiers .txt suivants :

• agencies.txt

• stops.txt

• routes.txt

• trips.txt

• stop_times.txt

• calendars.txt

• shapes.txt

• transfers.txt

Ces fichiers sont conformes à la norme GTFS. Pour en savoir plus sur le format GTFS à l’export, réferez-vous à la partie Export | Export GTFS.

Lorsque vous choisissez de faire un export de type GTFS vous pouvez paramétrer les informations suivantes :

• Les périodes à exporter. Vous pouvez préciser si vous prenez toutes les périodes disponibles, seulement quelques jours ou une période statique.

• Les lignes à exporter. Vous pouvez décider de ne pas exporter toutes les lignes, mais les sélectionnées selon le transporteur associé, les fournisseurs de lignes associés ou selon une liste de ligne que vous définissez.

• Les arrêts référents. Vous pouvez indiquer que vous préférez ou non l’utilisation des arrêts référents pour votre export. Avec cette option, l’export GTFS utilisera les arrêts Référents (s'il y en a) au lieu des arrêts particuliers.

• Les transporteurs référents. Vous pouvez indiquer que vous préférez ou non l’utilisation des transporteurs référents pour votre export. Avec cette option, l’export GTFS utilisera les transporteurs Référents (s'il y en a) au lieu des transporteurs particuliers.

• Les lignes référentes.

• Ignorer les arrêts parents. Les arrêts vont être exportés sans leurs parents.

• La prise en compte des Zones de Lieux avec une Zone d’Embarquement Unique. Avec cette option, vous pouvez choisir d’ignorer les ZDL ne contenant qu’une seule ZDE.

L’export Netex Générique :

NeTEx (Network Exchange) est un format de référence pour échanger des données d’offre théorique du transport collectif, défini au niveau européen.

Lors de l’export d'un fichier, un fichier zip se crée contenant différents fichier XML.

Pour en savoir plus sur le format Netex à l’export, référez-vous à la page Export | Export NeTEx.

Lorsque vous choisissez de faire un export de type NeTex Générique vous pouvez paramétrer les informations suivantes :

• Les périodes à exporter. Comme pour l’export GTFS, vous pouvez choisir quelles périodes exportées.

• Le profil de l’export NeTex. Le format NeTex présente différents profils que vous choisissez avec Chouette.

• Les Lignes exportées. Comme pour l’export GTFS, vous pouvez choisir d’exporter les lignes selon le fournisseur de ligne, le transporteur ou selon une liste de ligne que vous définissez.

• La prise en compte des arrêts référents. Avec cette option, vous pouvez choisir d’ignorer les arrêts référents dans votre export NeTEx.

• La prise en compte des lignes référentes. Avec cette options, vous pouvez choisir d’exporter les lignes référentes à la place des lignes particulières.

L’export Ara :

Si vous alimentez Ara à partir des données inscrit dans Chouette, vous pouvez sélectionner le type d’export Ara. Lors de l’export, un fichier csv se crée contenant les différents attributs de votre export. Dans le fichier csv, chaque ligne correspond aux informations d’un attribut :

• operator

• stop_area

• line

• vehicle_journey

Lorsque vous choisissez de faire un export de type Ara, vous pouvez paramétrer les informations suivantes :

• Les lignes exportées. Vous pouvez choisir d’exporter les lignes selon le fournisseur de ligne, le transporteur ou selon une liste de lignes que vous définissez.

Destination de la publication

Une Publication de données intégrant un export complet peut inclure différents types de destination de publication. L’export est envoyé à la(aux) destination(s) que vous paramétrez.

Destination de type API de Publication

Vous pouvez paramétrer que votre publication ait pour destination une API.

A chaque publication, l’API de Publication est informée que les données à réceptionner sont les données exportées par cette publication.

Pour ce type de destination, vous devez choisir une API de publication déjà existante. Pour gérer les API de Publication, référez-vous à la partie plus bas : Publication de l’offre | Gestion des APIs de Publication

Une même API peut être alimentée par plusieurs Publications. La contrainte (actuelle) est que chaque Publication doit utiliser un format d’export différent.

Destination de type Notification Email

Vous pouvez choisir une destination email pour votre publication. Vous avez la possibilité de :

• mettre l’export en pièce-jointe

• inclure un lien vers une API de Publication

• choisir les destinataires de ce mail

• rédiger le contenu du mail

Destination de type Ara SaaS

Le type de destination Ara SaaS paramètre votre publication en destination d’un référentiel Ara.

Pour ce faire, vous devez renseigner l’URL du Referential Ara de destination souhaité et le Token d’identification.

Destination de type Google Cloud Storage

L’utilisateur peut choisir le type de destination Google Cloud Storage.

Vous devez renseigner le projet, le bucket et la clé secrète de votre espace Google Cloud Storage. Le fichier publié sera donc automatiquement envoyé vers le bucket que vous définissez.

Destination de type SFTP

L’utilisateur peut choisir le type de destination SFTP.

Pour ce type de destination, vous devez renseigner :

• L’Hôte avec l’URL du serveur

• le Port

• le Répertoire où le fichier publié sera envoyé

• la clé secrète du serveur

Consultation d’une publication

Une publication activée se lance automatiquement après chaque agrégation. En cliquant sur le nom d’une publication vous avez accès aux informations suivantes :

• un bloc “Informations” avec le nom de la Publication et sa date de création et de modification

• un bloc “Paramètres de l’Export” avec le type de l’export réalisé à chaque Publication et les paramètres de cet export

• un bloc “Destination”, avec pour chaque Destination le type de la Destination et les paramètres de la Destination

Sous ces informations, la liste des derniers rapports de cette Publication est présentée avec les liens vers les sources de la publication.

Vous avez la possibilité de lancer une publication manuellement avec le bouton “Publier maintenant”. Un export sera créé avec les données de la dernière offre agrégée de votre Groupe de Travail.

Pour chaque Source de publication, Chouette crée un rapport intégrant :

• Le nom de l’offre qui a été publiée, avec un lien vers le rapport de publication

• L’état final de cette Publication

• La date de démarrage et de fin de cette Publication

Chaque rapport de publication est accessible en cliquant sur le nom de la source, ou “Consulter” via la roue dentée. Sur cette page, vous trouverez les détails de la publication en question.

Un bloc “Informations” avec:

• l'état de la publication

• le nom de la publication

• le nom de l’offre utilisée pour créer la publication avec son lien

Un bloc “Traitement” avec :

• La date de création de la publication

• La date de début du traitement de la publication

• La date de fin de traitement de la publication

• La durée de l’opération

Un bloc “Export” avec :

• Le nom de l’export avec un lien pour accéder au téléchargement du fichier

• Le type d’export

• L'état de l’envoi vers la destination

• Les paramètres de l’export

Un rapport d’envoi vers les destinations liées à cette publication :

• Le type d’envoi

• le nom court de la destination

• L'état de l’envoi vers la destination

• Message d’erreur

• Le début de la transmission

• La fin de la transmission

• la durée de l’opération

Gestion des APIs de Publication

L’utilisateur membre de l’organisation propriétaire du Groupe de Travail peut consulter les APIs de publications qui sont définies au niveau du Groupe de Travail.

Si vous disposez des permissions requises, vous pourrez gérer ces APIs de Publications.

Plusieurs APIs de Publication peuvent être définies au sein du Groupe de Travail. Chaque peut être la destination de plusieurs Publications de données. Cette souplesse permet de diffuser l’offre du Groupe de Travail sous plusieurs formats, plusieurs modalités (durée de l’offre, etc) en gérant des accès aux niveaux de chaque API.

Vous pouvez consulter les APIs de Publication actuellement définies.

La gestion des publications est accessible via le menu « Paramétrages » > « Publications » > « APIs de Publication ».

L’utilisateur autorisé et membre de l’organisation propriétaire du Groupe de Travail peut créer et modifier une API de Publications.

Vous pouvez définir:

• un nom, qui sera présent dans Chouette, et en externe.

• un nom court (ou nicename), correspond au nom utilisé dans l’URL de l’API. Le nom court « acmee » produira, par exemple, des URLs comme /api/v1/datas/acmee.gtfs.zip.

L’URL publique se met à jour en fonction du nom court, au fur et à mesure que vous remplissez ce champ.

En cliquant sur “Valider”, Chouette crée une API de Publication, vous arrivez sur la page de consultation de cette API.

L’utilisateur membre de l’organisation propriétaire du Groupe de Travail peut consulter le paramétrage d’une API de Publication.

Les détails d’une API de Publication intègrent :

Les informations, avec :

• le nom

• le nom court

• l’URL publique

• les dates de création et de dernière modification

Les publications associées, avec, pour chacune :

• le nom avec un lien vers le dernier rapport de publication (qui a alimenté cette API),

• le type d’export

Les clés d’accès, avec, pour chacune :

• le nom

• le token, ou jeton d’accès

• les dates de création et de dernière modification

L’utilisateur avec les permissions requises peut créer, modifier, ou supprimer chaque clé d’accès.

Les clés d’accès peuvent être confiées à des tiers pour leur donner un accès à toutes les données publiées par l’API. Dès qu’une clé est supprimée, l’accès n’est plus possible. Vous pouvez ainsi confier des clés différentes à chaque tiers et gérer finement les droits d’accès et leur révocation.

Par défaut, quand l’API vient d’être créée, il n’y a pas encore de clé d’accès. Il n’y a donc pas de tableau, mais un texte d’aide : « Cette API ne dispose pas encore de clé d’accès. »

Lors de la création d’une API, vous pouvez cocher l’option « API publique » pour désactiver l’authentification lors des accès à une API de Publication. Dans ce cas les données publiées via l’API peuvent être téléchargées librement.

Accès à la page publique de votre API de Publication

Dès que vous créez une API de publication (publique ou privée), vous pouvez transmettre à vos consommateurs de données une page publique décrivant toutes les ressources que vous mettez à leur disposition

Accès aux données d’une API de Publication

Pour chaque Publication utilisant un export complet et ayant comme destination une API de Publication, celle-ci donne accès aux données de l’export en mettant à disposition le fichier exporté sur une URL de la forme : /api/v1/datas/<nom court>.<format>.zip

Par exemple, pour une API avec le nom court « test », on pourra accéder aux données via une URL de type /api/v1/datas/test.gtfs.zip

Lorsqu’une Publication met à disposition des données, les données accessibles via l’API sont mises à jour, mais l’URL reste inchangée.

Publique

Dans le cas d’une API de publication publique, n’importe quel consommateur peut accéder aux données publiées.

Privée

Dans le cas d’une API de publication privée, elle est accessible uniquement si la requête de consultation utilise l’une des clés associées à l’API de Publication. Le token de clé doit être inclus dans une entête HTTP de la forme Authorization: Token token=<token>.

L’utilisateur autorisé peut créer une clé d’accès d’API de Publication depuis les détails d’une API de Publication.

Vous pouvez définir un nom à la clé d’accès précisant par exemple quel est le consommateur associé. Le token ou jeton d’accès est généré automatiquement par Chouette.

Récupération des données d’une API par requêtes

La description et l’utilisation de l'API de publication est disponible dans de nombreux langages via notre documentation Postman.

Postman permet l’utilisation de toutes les requêtes fournies. Si vous voulez créer votre propre espace : voir le bouton “Run in Postman“ en haut à droite.

Pour paramétrer les requêtes Postman, il faut récupérer les identifiants nécessaires sur l’interface de Chouette ou dans le fichier de l’import initial.