Questa guida spiega come utilizzare l’API di Discourse per creare, eseguire e gestire query con il plugin Data Explorer.
Livello utente richiesto: Amministratore
Praticamente qualsiasi azione che può essere eseguita tramite l’interfaccia utente di Discourse può anche essere attivata con l’API di Discourse.
Questo documento fornisce una panoramica completa per l’utilizzo dell’API specificamente in combinazione con il plugin Data Explorer.
Per una panoramica generale su come trovare la richiesta API corretta per un’azione, vedere: Reverse engineer the Discourse API .
Esecuzione di una query Data Explorer
Per eseguire una query Data Explorer tramite l’API, effettua una richiesta POST a /admin/plugins/discourse-data-explorer/queries/<query-id>/run. Puoi trovare l’ID della query visitandola tramite il tuo sito Discourse e controllando il parametro id nella barra degli indirizzi.
Di seguito è riportato un esempio di query con un ID di 20 che restituisce argomenti in base alle visualizzazioni in una data specificata:
--[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
Questa query può essere eseguita da un terminale con:
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"}'
Nota che dovrai sostituire <api-key> e <your-site-url> con la tua chiave API e il tuo dominio.
Gestione di grandi set di dati
Il plugin Data Explorer limita i risultati a 1000 righe per impostazione predefinita. Per eseguire la paginazione attraverso set di dati più grandi, puoi utilizzare la query di esempio seguente:
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
Per recuperare i risultati pagina per pagina, incrementa il parametro page nella richiesta:
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"}'
Interrompi quando result_count è zero.
Per ulteriori informazioni sulla gestione di grandi set di dati, vedere: Result Limits and Exporting Queries
Rimozione dei dati relations dai risultati
Quando le query Data Explorer vengono eseguite tramite l’interfaccia utente, un oggetto relations viene aggiunto ai risultati. Questi dati vengono utilizzati per il rendering dell’utente nei risultati dell’interfaccia utente, ma è improbabile che tu ne abbia bisogno quando esegui query tramite l’API.
Per rimuovere tali dati dai risultati, aggiungi un parametro download=true alla tua richiesta:
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"
Autenticazione API
I dettagli sulla generazione di una chiave API per le richieste sono disponibili qui: Create and configure an API key .
Se la chiave API verrà utilizzata solo per eseguire query Data Explorer, puoi selezionare “Granulare” dal menu a discesa Ambito (Scope), quindi selezionare l’ambito “run queries”.
FAQ
Esiste un endpoint API che posso utilizzare per ottenere l’elenco dei report e i numeri ID? Voglio creare un menu a discesa con l’elenco al suo interno?
Sì, puoi effettuare una richiesta GET autenticata a /admin/plugins/discourse-data-explorer/queries.json per ottenere un elenco di tutte le query sul sito.
È possibile creare query tramite l’API?
Sì. La documentazione su come farlo è disponibile su Create a Data Explorer query using the API
È possibile inviare parametri con la richiesta post?
Sì, includi i parametri SQL utilizzando l’opzione -F, come mostrato negli esempi.
L’esportazione CSV per le query è supportata dall’API?
Sebbene l’output JSON sia standard, puoi convertire manualmente i risultati in CSV. L’esportazione CSV nativa non è più supportata.