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
Pratiquement 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/discourse-data-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 renvoie 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/discourse-data-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 JSON à 1000 lignes par défaut (contrôlé par le paramètre de site masqué data_explorer_query_result_limit). Vous pouvez remplacer cela par requête en passant un paramètre limit, jusqu’à un maximum de 10 000 :
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F "limit=5000"
Pour les ensembles de données supérieurs à 10 000 lignes, vous devrez effectuer une pagination au niveau SQL. 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/discourse-data-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 zéro.
Pour des informations supplémentaires sur la gestion des grands ensembles de données, consultez : Limites de résultats et exportation des requêtes
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/discourse-data-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 de l’API
Les détails sur la création d’une clé API pour les requêtes se trouvent ici : Create and configure an API key .
Si la clé API ne sera utilisée que pour exécuter des requêtes Data Explorer, vous pouvez sélectionner « Granulaire » dans le menu déroulant Scope, puis sélectionner le scope « 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 cette liste ?
Oui, vous pouvez effectuer une requête GET authentifiée vers /admin/plugins/discourse-data-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 ?
Oui. Ajoutez .csv à l’URL du endpoint d’exécution pour obtenir les résultats au format CSV :
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run.csv" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
Les réponses CSV renvoient par défaut jusqu’à 10 000 lignes. Vous pouvez passer un paramètre limit pour réduire ce nombre.