Exécuter des requêtes Data Explorer avec l'API Discourse

[Discourse]

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.

Ressources supplémentaires

• Create a Data Explorer query using the API
• Create and configure an API key
• Reverse engineer the Discourse API
• GitHub - lee-dohm/execute-discourse-query: Executes a Discourse data-explorer query via the API

[37Rb (Ryan)]

@simon

La prise en charge de limit=ALL pour les exportations CSV

Ce commentaire semble impliquer que vous pouvez faire une exportation CSV à partir de l’API. Est-ce possible ? Je suis juste curieux car j’ai besoin des données au format CSV. Je peux toujours les obtenir au format JSON et les convertir en CSV, mais s’il existe un moyen intégré d’obtenir du CSV, ce serait un peu plus facile.

[francis_exalate (Francis Martens (Exalate))]

Est-il possible de faire une requête « comme créé ou mis à jour dans les 50 dernières secondes » ?

[Canapin (Coin-coin le Canapin)]

L’IA dit

-- [params]
-- int :seconds = 50

SELECT
    p.id AS post_id,
    p.created_at,
    p.updated_at,
    p.raw AS post_content,
    p.user_id,
    t.title AS topic_title,
    t.id AS topic_id
FROM posts p
INNER JOIN topics t ON t.id = p.topic_id
WHERE
    (EXTRACT(EPOCH FROM (NOW() - p.created_at)) <= :seconds
    OR EXTRACT(EPOCH FROM (NOW() - p.updated_at)) <= :seconds)
    AND p.deleted_at IS NULL
    AND t.deleted_at IS NULL
ORDER BY p.created_at DESC
LIMIT 50

J’ai fait un test rapide, ça semble fonctionner

[Moin]

Je ne vois pas le « j’aime  » que j’ai ajouté à une publication en utilisant votre requête.

Je pense que vous devez utiliser post_actions

--[params]
--string :timespan = 50 seconds

SELECT post_id,
       user_id,
       created_at,
       updated_at,
       deleted_at
FROM  post_actions
WHERE post_action_type_id=2 AND updated_at > NOW() - INTERVAL :timespan

Version avec de plus beaux résultats

--[params]
--string :timespan = 50 seconds
--boolean :include_in_timespan_deleted = false

SELECT
  post_id,
  user_id,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400), ' days ago')
  END AS relative_created_at,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 86400), ' days ago')
  END AS relative_updated_at,
  CASE
    WHEN deleted_at IS NULL THEN 'no'
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 86400), ' days ago')
  END AS relative_deleted_at
FROM
  post_actions
WHERE
  post_action_type_id = 2
  AND updated_at > NOW() - INTERVAL :timespan
  AND (
    :include_in_timespan_deleted = false
    OR (deleted_at IS NOT NULL AND deleted_at > NOW() - INTERVAL :timespan)
  )

[Canapin (Coin-coin le Canapin)]

Oooh j’ai mal lu ! J’ai lu la phrase comme « Est-il possible de faire une requête comme « créé ou mis à jour au cours des 50 dernières secondes » ? »

(notez la position de la virgule simple)

[francis_exalate (Francis Martens (Exalate))]

Merci à tous,

J’ai posté ici car c’est là que ask.discourse m’a dirigé.
Je cherche à savoir si l’API offre cette fonctionnalité.

[Canapin (Coin-coin le Canapin)]

Oui, bien sûr.

Vous créez la requête dans l’explorateur de données, puis vous exécutez la requête via l’API comme décrit dans ce guide.

Je viens d’exécuter la requête de Moin via l’API et elle a correctement renvoyé les résultats attendus.

[tanya_byrne (kukulaka)]

Je me posais la même question. JSON est-il le seul moyen d’exporter des données via l’API ou l’export CSV est-il également pris en charge pour Data Explorer ?

[francis_exalate (Francis Martens (Exalate))]

Merci à tous,

Désolé pour ma réponse tardive - j’étais hors ligne pendant un moment.

Ce que je fais actuellement, c’est rechercher tous les sujets/messages créés aujourd’hui, et filtrer les sujets/messages mis à jour avant l’horodatage.

[Canapin (Coin-coin le Canapin)]

@francis_exalate

Ce que je fais actuellement, c’est rechercher tous les sujets/messages créés aujourd’hui, et filtrer les sujets/messages mis à jour avant l’horodatage.

Si vous ne voulez pas vous salir les mains, vous pouvez demander au bot sur ask.discourse.com. Il est généralement assez précis en ce qui concerne les requêtes SQL relatives à Discourse (mais ne supposez pas qu’il a raison, vérifiez le code pour être sûr).

[srinivas.chilukuri]

@Discourse

-H "Content-Type: multipart/form-data; `

---

L’en-tête Content-Type est-il correct ?
Dans les outils de développement, lors de l’inspection d’une requête Data Explorer avec des paramètres, l’en-tête Content-Type apparaît comme suit :

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Cependant, la commande cURL actuelle inclut :

-H "Content-Type: multipart/form-data;"

---

[blake (Blake Erickson)]

• multipart/form-data
• application/x-www-form-urlencoded
• application/json

sont tous des types de contenu valides que vous pouvez utiliser lors de la création d’une requête API.

[srinivas.chilukuri]

@blake
language python
library requests
Pourriez-vous fournir une requête d’exemple d’API Data Explorer qui inclut trois paramètres
référez-vous à Topic qui indique que les paramètres doivent être strictement entre guillemets doubles.

[blake (Blake Erickson)]

Bien sûr, voici un exemple utilisant Python :

import json
import requests

API_KEY      = "VOTRE_CLE_API"
API_USERNAME = "system"
QUERY_ID     = 20
SITE_URL     = "https://votre-url-de-site"

# toutes les valeurs doivent être des chaînes de caractères
params = {
    "user_id":   "2",
    "viewed_at": "2019-06-10",
    "limit":     "5"
}

# Data Explorer attend les paramètres sous forme de chaîne encodée en JSON
payload = {
    "params": json.dumps(params)
}

url = f"{SITE_URL}/admin/plugins/explorer/queries/{QUERY_ID}/run"
headers = {
    "Api-Key":       API_KEY,
    "Api-Username":  API_USERNAME,
    "Content-Type":  "application/json"
}

r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
print(r.json())