Configurer un traitement Import depuis une API JSON

L'API OpenAgenda nécessite une clé : sans elle, chaque appel échoue avec une erreur 403. Créez un compte sur openagenda.com, puis ouvrez Paramètres → Clés API pour la récupérer. Elle s'utilise en l'ajoutant à l'en-tête HTTP key de chaque requête — c'est justement ce que permet la méthode d'authentification Clé d'API dans un en-tête du traitement, configurée plus bas.

Chaque agenda a son propre identifiant numérique dans l'URL — ici 83549053, celui de Bordeaux Métropole, visible dans l'URL de l'agenda sur openagenda.com ou dans ses Paramètres → Général : remplacez-le par celui du vôtre pour interroger un autre agenda.

Tout le paramétrage du plugin consiste à décrire des chemins dans la réponse JSON. Il faut donc commencer par la regarder. Un appel à l'API renvoie un objet englobant : le nombre total de résultats, puis le tableau des évènements sous la clé events [1] — c'est ce chemin qu'il faudra indiquer comme Chemin du tableau de résultats.

Chaque évènement mélange trois formes de données, et c'est cette diversité qui rend l'exemple intéressant :

• des objets imbriqués — le titre n'est pas une chaîne mais un objet par langue [2] (OpenAgenda est multilingue), et le lieu regroupe nom, ville et coordonnées sous location [4] ;
• un tableau de chaînes — les mots-clés [3], sous keywords.fr ;
• des tableaux d'objets — les liens [5], et surtout les séances [6] : un même évènement peut se tenir plusieurs jours, chaque créneau ayant son début et sa fin sous timings.

Les champs keywords, links et timings ne sont renvoyés que si la requête porte le paramètre detailed=1 — d'où sa présence dans l'URL configurée ci-dessous.

La configuration propre au plugin se répartit sur deux onglets : Source des données (où aller chercher le JSON) et Champs à récupérer (comment le transformer en colonnes). Le troisième onglet, Jeu de données, est décrit dans le cours générique — à l'exception d'une case propre à ce plugin, présentée en fin de section (2.5).

Renseignez l'URL de l'API [1] : https://api.openagenda.com/v2/agendas/83549053/events?detailed=1&relative[]=upcoming&sort=lastTiming.asc. Elle ne contient aucun secret, elle reste donc lisible et partageable. Seuls detailed=1 et l'identifiant de l'agenda sont nécessaires ; relative[]=upcoming&sort=lastTiming.asc ne servent qu'à trier les évènements à venir par ordre chronologique, pour un exemple plus lisible.

Choisissez ensuite la méthode d'authentification [2] : Clé d'API dans un en-tête. Deux champs apparaissent : le Nom de l'en-tête [3], celui attendu par la source (key pour OpenAgenda), et la Valeur de la clé [4], la clé elle-même — un champ de type mot de passe, jamais réaffiché. Cela permet de documenter et de partager la configuration sans jamais exposer le secret.

Reste la pagination [5]. La plupart des API ne renvoient qu'une page de résultats à la fois : sans pagination, le traitement n'importera que cette première page. Le plugin propose trois méthodes.

[1] Pas de pagination. Un seul appel, une seule page. C'est le bon choix quand la source renvoie tout d'un coup (petit fichier JSON, API de configuration), ou pour un premier essai — c'est ce que fait ce cours, qui se contente des 20 évènements de la page par défaut.

[2] Lien vers la page suivante dans la réponse. Pour les API qui renvoient elles-mêmes le lien de la page suivante dans leur réponse — le style HAL / JSON:API, très répandu. Indiquez le Chemin de l'URL de la page suivante dans le JSON (par exemple next) ; le traitement suit ce lien de proche en proche jusqu'à ce qu'il soit vide. Les champs Paramètre « limit » et Éléments par page (1000 par défaut) permettent en plus de demander de grandes pages, pour limiter le nombre d'appels.

[3] Paramètres offset / limit dans l'URL. Pour les API qui ne fournissent aucun lien mais acceptent un couple de paramètres de décalage et de taille — le cas le plus courant, et celui d'OpenAgenda (from et size). Renseignez le Paramètre « offset » (offset par défaut, souvent from ou skip) et, si l'API l'accepte, le Paramètre « limit » (size, limit, take…) : sans lui, la pagination continue tant que l'API renvoie des lignes. Par défaut, le décalage est incrémenté du nombre de lignes déjà lues ; si votre API compte en numéros de page et non en nombre d'éléments, cochez Offset en numéro de page, qui l'incrémente de 1 à chaque appel.

En résumé : la réponse contient un lien vers la suite → méthode [2] ; il faut fabriquer soi-même l'URL de la page suivante → méthode [3] ; tout tient en un appel → méthode [1]. En cas de doute, essayez la source dans un navigateur et regardez ce que contient la réponse.

Le second onglet décrit la transformation du JSON en tableau. Le Chemin du tableau de résultats [1] indique où se trouve, dans la réponse, le tableau à parcourir : events, comme repéré plus haut. Une ligne du jeu de données sera produite par élément de ce tableau. Si l'API renvoyait directement un tableau à la racine, ce champ resterait vide.

Chaque entrée de la liste Colonnes associe ensuite une Clé de la colonne — le nom qu'aura la colonne dans le jeu de données — à un Chemin dans le JSON, évalué dans l'objet de chaque évènement :

Trois notations, mais il faut les distinguer.

Le point descend dans les objets. location.city lit la propriété city de l'objet location. Le .fr de title.fr n'est pas décoratif : sans lui, le traitement chercherait une valeur directement sous title, où il n'y a qu'un objet par langue, et la colonne resterait vide.

Les crochets traversent un tableau d'objets. links[].link signifie : pour chaque élément du tableau links, prends sa propriété link. Les valeurs obtenues ne créent pas de lignes supplémentaires : elles sont concaténées dans une seule cellule.

Un nombre après un point vise un élément par sa position. attributes.0 lit le premier élément d'un tableau (à partir de 0, pas [0]), et attributes.1.title sa propriété title — pratique pour ne garder qu'un élément précis sans dépiler ni concaténer tout le tableau.

C'est là qu'intervient le champ Séparateur des valeurs multiples, en bas de l'onglet (; par défaut) : c'est le caractère qui joint ces valeurs multiples. Il n'a de sens que pour les chemins qui ramènent plusieurs valeurs — ceux qui utilisent [], et ceux qui pointent directement un tableau de chaînes. Choisissez un caractère qui n'apparaît pas dans les données elles-mêmes.

Deux pièges, vérifiés à l'exécution :

• un tableau de chaînes se lit sans crochets. Pour les mots-clés, le chemin est keywords.fr, pas keywords.fr[] — le tableau est déjà la valeur finale, il n'y a rien à traverser. Avec les crochets, la colonne ressort vide ;
• les crochets ne se posent que sur un vrai tableau. Écrire keywords[].fr alors que keywords est un objet fait échouer l'exécution.

En cas de doute, comparez le chemin à la réponse JSON de la section 1.2 : [] se place exactement là où vous voyez un [ suivi de { dans le JSON.

La concaténation convient aux mots-clés ou aux liens, mais pas aux séances : un évènement qui se tient les 9 et 10 juillet devrait produire deux lignes, chacune avec sa date, pour être exploitable dans un calendrier ou une recherche par date. C'est le rôle de la carte Développer un tableau imbriqué en plusieurs lignes, en bas de l'onglet.

Elle prend un chemin [1] vers un tableau imbriqué — ici timings — puis rouvre, à l'intérieur, une liste de champs à récupérer [2] dont les chemins sont évalués relativement à chaque élément de ce tableau : begin et end, et non timings.begin. Le séparateur des valeurs multiples, commun à tout le mapping (section 2.3), s'applique aussi ici [4].

Ce que cela produit, mesuré sur une exécution réelle : le traitement émet une ligne par élément du tableau imbriqué, et non une ligne par élément du tableau de résultats. Les colonnes du niveau parent (titre, lieu, ville, mots-clés…) sont recopiées à l'identique sur chacune de ces lignes, et les colonnes du bloc imbriqué s'ajoutent à côté. Le résultat reste un seul tableau plat, qui compte une ligne par séance et non par évènement (voir le résultat en section 3). Un évènement sans séance ni tableau timings produit malgré tout sa ligne, colonnes imbriquées vides.

La carte est récursive [3] : à l'intérieur d'un bloc imbriqué, un nouveau bloc Développer un tableau imbriqué en plusieurs lignes est proposé, sans limite de profondeur. On peut ainsi aplatir un JSON à plusieurs niveaux de tableaux — en gardant en tête que le nombre de lignes se multiplie à chaque niveau.

⚠️ Choisissez donc bien le tableau à déplier : le dépliage définit la granularité d'une ligne du jeu de données. Ici, une ligne n'est plus un évènement mais une séance d'évènement — ce que reflète le titre donné au jeu produit. Si vous vouliez au contraire un enregistrement par évènement, laissez la carte vide et lisez la première date via un chemin simple (firstTiming.begin).

Dans l'onglet Jeu de données, l'action [1] Créer un jeu de données propose une case Jeu de données éditable [2]. Décochée, un jeu de données fichier est créé : chaque exécution remplace le fichier entier — c'est ce que fait ce cours. Cochée, un jeu de données éditable est créé à la place, avec les colonnes du mapping toutes en texte.

⚠️ Piège vérifié : une clé primaire posée sur un jeu qui contient déjà des lignes ne les retrouve pas — l'exécution suivante les considère nouvelles et double le jeu au lieu de le mettre à jour. Posez la clé primaire (onglet Structure du jeu de données) puis videz ses lignes avant de relancer le traitement ; ou créez le jeu éditable à vide au préalable, clé déjà posée, et pointez le traitement vers lui en mode Mettre à jour un jeu de données.

L'exécution produit un jeu de données de 21 enregistrements [1] et 9 colonnes [2] à partir de la première page d'évènements. Dans le schéma, mots_cles et liens portent une icône de liste plutôt que celle d'un texte simple : c'est l'effet du séparateur déclaré sur ces deux colonnes (onglet Schéma), qui indique à la plateforme de les traiter comme des listes plutôt que comme du texte brut.

Dans les données, l'effet du dépliage est visible directement : Les quatre saisons de vivaldi [1] et Cuisine du Bassin d'Arcachon et vins du monde [2] occupent chacun deux lignes, identiques sauf pour debut et fin. Les mots-clés [3] s'affichent en valeurs distinctes grâce au séparateur.

Si la plateforme ne reconnaît pas automatiquement les colonnes latitude et longitude comme des coordonnées géographiques, associez-les au concept correspondant depuis l'onglet Schéma du jeu de données : l'onglet Carte affiche alors chaque évènement à sa position.

Si vous avez des remarques sur ce cours, n'hésitez pas à nous les communiquer.