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, effettuare una richiesta POST a /admin/plugins/explorer/queries/<query-id>/run. È possibile trovare l’ID della query visitandola tramite il proprio 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 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/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"}'
Si noti che sarà necessario sostituire <api-key> e <your-site-url> con la propria chiave API e dominio.
Gestione di set di dati di grandi dimensioni
Il plugin Data Explorer limita i risultati a 1000 righe per impostazione predefinita. Per eseguire la paginazione attraverso set di dati più grandi, è possibile 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, incrementare il parametro page nella richiesta:
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"}'
Interrompere quando result_count è zero.
Per ulteriori informazioni sulla gestione di set di dati di grandi dimensioni, vedere: Result Limits and Exporting Queries
Rimozione dei dati relations dai risultati
Quando le query di 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 siano necessari quando si eseguono query tramite l’API.
Per rimuovere tali dati dai risultati, aggiungere un parametro download=true alla richiesta:
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"
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, è possibile selezionare “Granular” dal menu a discesa Scope, quindi selezionare lo scope “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?
Sì, è possibile effettuare una richiesta GET autenticata a /admin/plugins/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ì, includere 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, è possibile convertire manualmente i risultati in CSV. L’esportazione CSV nativa non è più supportata.