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 sull’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 è riportata una query di esempio con un ID di 20 che restituisce argomenti per 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 set di dati di grandi dimensioni
Il plugin Data Explorer limita i risultati JSON a 1000 righe per impostazione predefinita (controllato dall’impostazione del sito nascosta data_explorer_query_result_limit). Puoi sovrascrivere questo limite per richiesta passando un parametro limit, fino a un massimo di 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"
Per set di dati più grandi di 10.000 righe, dovrai utilizzare la paginazione a livello SQL. Puoi usare 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 set di dati di grandi dimensioni, consulta: Limiti dei risultati ed esportazione delle query
Rimozione dei dati relations dai risultati
Quando le query di Data Explorer vengono eseguite tramite l’interfaccia utente, viene aggiunto un oggetto relations ai risultati. Questi dati vengono utilizzati per visualizzare l’utente nei risultati dell’interfaccia utente, ma è improbabile che ti servano 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 di Data Explorer, puoi selezionare “Granulare” dal menu a discesa Ambito, quindi selezionare l’ambito “esegui query”.
FAQ
Esiste un endpoint API che posso usare 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 si trova 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?
Sì. Aggiungi .csv all’URL dell’endpoint di esecuzione per ottenere i risultati in formato 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"}'
Le risposte CSV restituiscono per impostazione predefinita fino a 10.000 righe. Puoi passare un parametro limit per ridurlo.