Ce guide explique comment utiliser l’API Discourse pour créer, exécuter et gérer des requêtes avec le plugin Data Explorer.
Niveau d’utilisateur requis : Administrateur
Virtuellement toute action pouvant être effectuée via l’interface utilisateur de Discourse peut également être déclenchée avec l’API Discourse.
Ce document fournit un aperçu complet de l’utilisation de l’API spécifiquement en conjonction avec le plugin Data Explorer.
Pour un aperçu général sur la façon de trouver la bonne requête API pour une action, consultez : Reverse engineer the Discourse API .
Exécution d’une requête Data Explorer
Pour exécuter une requête Data Explorer via l’API, effectuez une requête POST vers /admin/plugins/explorer/queries/<query-id>/run. Vous pouvez trouver l’ID de la requête en la visitant via votre site Discourse et en vérifiant le paramètre id dans la barre d’adresse.
Ci-dessous se trouve une requête d’exemple avec un ID de 20 qui retourne les sujets par vues à une date spécifiée :
--[params]
-- date :viewed_at
SELECT
topic_id,
COUNT(1) AS views_for_date
FROM topic_views
WHERE viewed_at = :viewed_at
GROUP BY topic_id
ORDER BY views_for_date DESC
Cette requête peut être exécutée depuis un terminal avec :
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
Notez que vous devrez remplacer <api-key> et <your-site-url> par votre clé API et votre domaine.
Gestion des grands ensembles de données
Le plugin Data Explorer limite les résultats à 1000 lignes par défaut. Pour paginer à travers de plus grands ensembles de données, vous pouvez utiliser la requête d’exemple ci-dessous :
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
Pour récupérer les résultats page par page, incrémentez le paramètre page dans la requête :
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}'
Arrêtez lorsque result_count est égal à zéro.
Pour des informations supplémentaires sur la gestion des grands ensembles de données, consultez : Result Limits and Exporting Queries
Suppression des données relations des résultats
Lorsque les requêtes Data Explorer sont exécutées via l’interface utilisateur, un objet relations est ajouté aux résultats. Ces données sont utilisées pour afficher l’utilisateur dans les résultats de l’interface utilisateur, mais vous n’en aurez probablement pas besoin lors de l’exécution de requêtes via l’API.
Pour supprimer ces données des résultats, ajoutez un paramètre download=true à votre requête :
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}' \
-F "download=true"
Authentification API
Les détails sur la génération d’une clé API pour les requêtes se trouvent ici : Create and configure an API key .
Si la clé API ne doit être utilisée que pour exécuter des requêtes Data Explorer, vous pouvez sélectionner « Granular » dans le menu déroulant Scope, puis sélectionner la portée « run queries ».
FAQs
Existe-t-il un endpoint d’API que je peux utiliser pour obtenir la liste des rapports et les numéros d’ID ? Je souhaite créer une liste déroulante avec la liste ?
Oui, vous pouvez effectuer une requête GET authentifiée vers /admin/plugins/explorer/queries.json pour obtenir une liste de toutes les requêtes sur le site.
Est-il possible de créer des requêtes via l’api ?
Oui. La documentation sur la façon de le faire se trouve à l’adresse Create a Data Explorer query using the API
Est-il possible d’envoyer des paramètres avec la requête post ?
Oui, incluez les paramètres SQL en utilisant l’option -F, comme montré dans les exemples.
L’exportation CSV pour les requêtes est-elle prise en charge par l’API ?
Bien que la sortie JSON soit standard, vous pouvez convertir manuellement les résultats en CSV. L’exportation CSV native n’est plus prise en charge.