Planifier et publier une version Strapi 5 via l’API
Apprenez pas à pas à générer un token admin, créer une version planifiée, ajouter des actions de publication et déclencher la version avec l’API admin de Strapi 5, entièrement en code.
Par l’équipe Revisionary · · 4 min de lecture
Vous pouvez créer une version de contenu planifiée et la publier entièrement via l’API admin de Strapi 6. Le processus consiste à générer un token admin, créer une version, ajouter des actions décrivant les entrées à publier ou dépublier, puis appeler le point de terminaison de publication à l’heure prévue.
Prérequis
- Strapi 5 fonctionnant sur Node 18–24 avec une base de données PostgreSQL, MySQL ou SQLite (voir la page Exigences).
- Un plan Growth ou Enterprise, car la fonctionnalité Content Releases n’est pas disponible sur le niveau gratuit.
- Un compte avec le rôle admin pouvant gérer les permissions
plugin::content-releases.*. - Une connaissance de base de curl ou d’un client HTTP Node.js.
1. Générer un token admin
L’API admin est protégée par des tokens admin, et non par les tokens de l’API publique de contenu. Créez un token dans l’interface admin de Strapi via Settings → Administration Panel → Admin Tokens. Donnez‑lui un nom descriptif (par ex. Release‑automation) et copiez le secret généré.
# Exemple : stocker le token dans une variable d’environnement
export STRAPI_ADMIN_TOKEN="<your‑admin‑token>"Lors de l’appel de l’API, incluez le token dans l’en‑tête Authorization :
Authorization: Bearer <your‑admin‑token>Pour plus de détails sur la création du token, consultez la documentation des tokens admin.
2. Créer une version
Une version regroupe un ensemble d’actions de publication/dépublication et peut être planifiée à une date UTC future. Le point de terminaison est une requête standard POST vers /content-releases.
curl -X POST https://my‑strapi.example.com/content-releases \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring 2027 Launch",
"scheduledAt": "2027-04-01T10:00:00Z",
"timezone": "Europe/Paris"
}'La réponse contient l’ID de la version nouvellement créée et un status : empty :
{
"id": 42,
"name": "Spring 2027 Launch",
"scheduledAt": "2027-04-01T10:00:00Z",
"timezone": "Europe/Paris",
"status": "empty",
"actions": { "meta": { "count": 0 } }
}3. Ajouter des entrées à la version
Chaque entrée que vous souhaitez publier (ou dépublier) devient une action. Le payload minimal comprend le type de l’action, le slug contentType, et le entryDocumentId obtenu via l’API Document Service.
curl -X POST https://my‑strapi.example.com/content-releases/42/actions \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "publish",
"contentType": "articles",
"entryDocumentId": "hgv1vny5cebq2l3czil1rpb3",
"locale": "en"
}'Vous pouvez répéter la requête pour chaque entrée, ou utiliser le point de terminaison en bloc (voir la section suivante).
4. Ajouter des actions en bloc (optionnel)
Lorsque vous avez de nombreuses entrées, envoyez un tableau avec POST vers /content-releases/:releaseId/actions/bulk.
curl -X POST https://my‑strapi.example.com/content-releases/42/actions/bulk \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"actions": [
{"type":"publish","contentType":"articles","entryDocumentId":"id‑1","locale":"en"},
{"type":"publish","contentType":"pages","entryDocumentId":"id‑2"},
{"type":"unpublish","contentType":"news","entryDocumentId":"id‑3","locale":"fr"}
]
}'La réponse indique le nombre d’entrées ajoutées et celles qui faisaient déjà partie de la version.
5. Comprendre le statut de la version
Une version suit un cycle de vie simple :
| Statut | Signification |
|---|---|
empty | Aucune action attachée pour le moment |
ready | Au moins une action, prête à être publiée |
blocked | Erreur de validation (ex. scheduledAt dans le passé) |
failed | Publication échouée pour une ou plusieurs actions |
done | Toutes les actions traitées avec succès |
Le statut se met à jour automatiquement lorsque vous appelez le point de terminaison de publication.
6. Publier la version
Lorsque l’heure scheduledAt arrive, Strapi exécute automatiquement le job de publication. Vous pouvez également le déclencher manuellement (utile pour les tests) avec :
curl -X POST https://my‑strapi.example.com/content-releases/42/publish \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN"La réponse fournit un bref résumé :
{
"totalEntries": 3,
"totalPublishedEntries": 2,
"totalUnpublishedEntries": 1,
"status": "done"
}Si la version est planifiée dans le futur, le même point de terminaison mettra les actions en file d’attente qui seront exécutées à l’heure UTC définie.
7. Lister et inspecter les versions
Vous pouvez récupérer toutes les versions (paginées) avec :
curl -X GET "https://my‑strapi.example.com/content-releases?page=1&pageSize=20" \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN"Une requête de détail d’une seule version (GET /content-releases/:id) renvoie le payload complet, y compris la liste des actions et leur état actuel. Cela est pratique pour les tableaux de bord qui doivent afficher les versions en attente.
8. Gestion courante des erreurs
| Situation | Statut HTTP | Cause typique | Solution |
|---|---|---|---|
| Requête invalide | 400 Bad Request | scheduledAt dans le passé ou champs obligatoires manquants | S’assurer que le timestamp est futur et que tous les champs sont fournis |
| Permission manquante | 403 Forbidden | Le token admin ne possède pas les permissions plugin::content-releases.* | Accorder les trois permissions (create, read, publish) dans Settings → Roles → Plugins → Content‑releases |
| Identifiant de version introuvable | 404 Not Found | Erreur de saisie dans l’URL ou version supprimée | Vérifier l’ID via le point de terminaison de liste |
Consignez toujours le corps de la réponse ; Strapi inclut un champ message qui explique le problème de validation.
9. Bonnes pratiques pour la production
- Utiliser des tokens admin limités – Créez un token dédié ne possédant que les trois permissions de version. Stockez‑le de façon sécurisée (ex. Vault ou gestionnaire de secrets d’environnement).
- Valider les payloads localement – Reproduisez le schéma JSON de
@strapi/content-releases(disponible dans le paquet npm) pour détecter les erreurs avant d’interroger l’API. - Actions idempotentes – Si votre pipeline CI/CD peut s’exécuter deux fois, vérifiez si une action existe déjà (
GET /content-releases/:id/actions) avant d’ajouter des doublons. - Surveiller le journal d’audit – Le journal d’audit intégré de Strapi enregistre chaque création de version et chaque événement de publication. Passez‑le en revue régulièrement pour détecter toute activité inattendue.
- Repli gracieux – Lorsqu’une publication planifiée échoue, le statut devient
failed. Implémentez une routine de nouvelle tentative qui lit les actions en échec et tente de republier après correction de la cause racine.
10. Optionnel : combiner avec Revisionary pour du contenu versionné
Si vous avez également besoin d’un historique de version finement granulaire, le plugin Revisionary conserve chaque modification d’un type de contenu versionné. Bien que Revisionary ne remplace pas l’API Release, il le complète : vous pouvez planifier une version qui publie une version spécifique d’une entrée, puis utiliser le panneau Historique des versions de Revisionary pour auditer précisément quels champs ont changé avant que la version ne soit mise en ligne. Pour plus d’informations, consultez les pages du guide utilisateur du plugin, telles que « What Revisionary does » et « The audit log ».
Conclusion
Planifier et publier du contenu avec l’API admin de Strapi 6 est simple une fois que vous disposez d’un token admin et des permissions adéquates. Créez une version, joignez des actions de publication (individuellement ou en bloc), et laissez Strapi gérer l’exécution programmée. En suivant les conseils de gestion des erreurs et les bonnes pratiques de production présentés ci‑dessus, vous pouvez automatiser les déploiements de contenu pour des campagnes marketing, des lancements de produits ou tout flux de travail de publication sensible au temps.
Sources
L’équipe Revisionary
Les développeurs de Revisionary, un plugin d’historique des versions pour Strapi 5. Nous écrivons sur Strapi, le développement web, l’IA et la sécurité des applications.
Cet article a été rédigé avec l'aide d'une IA.