Synchroniser vos articles

Pour publier automatiquement vos articles, un script installé sur votre serveur interroge l’API à intervalle régulier et importe les nouveautés dans votre site. Cette page décrit la méthode ; les requêtes et leurs paramètres sont détaillés dans Articles.

Principe

1. Première exécution : appelez GET /v1/articles sans curseur.

2. Importez chaque article de data. Si un article avec le même id existe déjà sur votre site, mettez-le à jour au lieu d’en créer un second.

3. Enregistrez nextCursor une fois les articles de la page importés, dans un fichier ou dans votre base de données.

4. Tant que hasMore vaut true, rappelez l’API avec le paramètre cursor égal au nextCursor enregistré, puis reprenez à l’étape 2.

5. Exécutions suivantes : partez du curseur enregistré. Vous ne recevez que les articles nouveaux ou modifiés depuis l’exécution précédente.

Enregistrer le curseur après chaque page importée permet de reprendre au bon endroit si le script s’interrompt. Au pire, la dernière page est importée une seconde fois, ce qui reste sans conséquence grâce à la mise à jour par id.

Pour la première synchronisation, utilisez pageSize=50 : 500 articles se récupèrent en 10 appels.

Un article peut revenir plusieurs fois

Chaque modification d’un article dans Oscar, y compris un changement de statut, le fait revenir après le curseur. C’est ainsi que votre script reçoit les corrections faites après une première importation. Si vous retouchez aussi les articles sur votre site, décidez si une modification venue d’Oscar doit remplacer la vôtre.

Fréquence recommandée

Lancez la synchronisation toutes les 15 à 30 minutes avec une tâche planifiée (cron). Par exemple, cette ligne de crontab lance un script PHP toutes les 15 minutes :

*/15 * * * * php /chemin/vers/synchroniser.php

Une synchronisation toutes les 15 minutes représente environ 100 appels par jour quand il n’y a rien de nouveau, loin de la limite quotidienne. Une fréquence plus élevée n’apporte rien : les articles sont générés au fil du calendrier de vos Oscars, pas en continu.

Ne récupérer que les articles relus

Ajoutez le paramètre status=ready,published pour ne recevoir que les articles relus dans Oscar. Les articles encore à relire (to_review) ne seront pas publiés sur votre site avant votre validation.

Quand vous marquez un article comme relu dans Oscar, cette modification le place après le curseur : la synchronisation suivante le récupère. Gardez le même filtre à chaque appel, car un curseur s’utilise avec les mêmes filtres.

Si vous relisez plutôt les articles dans votre propre outil, n’utilisez pas ce filtre et importez les articles comme brouillons.

Héberger les images

Les adresses de l’image à la une (featuredImage) et des images du contenu (images) pointent vers nos serveurs. Elles ne sont pas garanties dans le temps et cessent notamment de fonctionner après la suppression de votre compte Oscar. Hébergez donc les images vous-même :

1. Téléchargez l’image à la une et chaque image de la liste images.

2. Enregistrez-les sur votre site ou chez votre hébergeur d’images.

3. Dans html, remplacez chaque images[].url par la nouvelle adresse de l’image. url est écrite telle quelle dans html, ce qui permet un simple rechercher-remplacer.

Gardez la correspondance entre l’adresse d’origine et la vôtre : quand un article revient après une modification, vous ne téléchargez que les images que vous n’avez pas encore.