Aller au contenu

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

person using black laptop computer on brown wooden table
Photo de Dell sur Unsplash

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é.

bash
# 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 :

http
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.

bash
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 :

json
{
  "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.

bash
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.

bash
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 :

StatutSignification
emptyAucune action attachée pour le moment
readyAu moins une action, prête à être publiée
blockedErreur de validation (ex. scheduledAt dans le passé)
failedPublication échouée pour une ou plusieurs actions
doneToutes les actions traitées avec succès

Le statut se met à jour automatiquement lorsque vous appelez le point de terminaison de publication.

Lines of colorful JavaScript code displayed on a dark screen
Photo de Markus Spiske sur Unsplash

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 :

bash
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é :

json
{
  "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 :

bash
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

SituationStatut HTTPCause typiqueSolution
Requête invalide400 Bad RequestscheduledAt dans le passé ou champs obligatoires manquantsS’assurer que le timestamp est futur et que tous les champs sont fournis
Permission manquante403 ForbiddenLe 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 introuvable404 Not FoundErreur de saisie dans l’URL ou version suppriméeVé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

  1. 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).
  2. 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.
  3. 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.
  4. 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.
  5. 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.

Mots-clésstrapi 5versions de contenuAPI adminpublication planifiéenode.js

Sources

  1. Strapi 5 releases feature
  2. Admin tokens documentation
  3. Strapi REST API reference
  4. Introducing scheduling for your releases
  5. Release service implementation
  6. Draft and publish feature

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.

Tous les articles