Dieser Leitfaden erklärt, wie Sie die Discourse API verwenden, um Abfragen mit dem Data Explorer Plugin zu erstellen, auszuführen und zu verwalten.
Erforderliches Benutzerniveau: Administrator
Praktisch jede Aktion, die über die Discourse Benutzeroberfläche ausgeführt werden kann, kann auch mit der Discourse API ausgelöst werden.
Dieses Dokument bietet einen umfassenden Überblick über die Nutzung der API speziell in Verbindung mit dem Data Explorer Plugin.
Für einen allgemeinen Überblick darüber, wie Sie die richtige API-Anforderung für eine Aktion finden, siehe: Reverse engineer the Discourse API .
Ausführen einer Data Explorer Abfrage
Um eine Data Explorer Abfrage über die API auszuführen, senden Sie eine POST-Anforderung an /admin/plugins/discourse-data-explorer/queries/<query-id>/run. Sie finden die Abfrage-ID, indem Sie sie auf Ihrer Discourse-Seite besuchen und den id-Parameter in der Adressleiste überprüfen.
Unten ist ein Beispiel für eine Abfrage mit der ID 20, die Themen nach Aufrufen an einem bestimmten Datum zurückgibt:
--[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
Diese Abfrage kann von einem Terminal aus mit folgendem Befehl ausgeführt werden:
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"}'
Beachten Sie, dass Sie <api-key> und <your-site-url> durch Ihren API-Schlüssel und Ihre Domain ersetzen müssen.
Umgang mit großen Datensätzen
Das Data Explorer Plugin begrenzt JSON-Ergebnisse standardmäßig auf 1000 Zeilen (gesteuert durch die versteckte Site-Einstellung data_explorer_query_result_limit). Sie können dies pro Anfrage überschreiben, indem Sie einen limit-Parameter übergeben, bis zu einem Maximum von 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"
Für Datensätze, die größer als 10.000 Zeilen sind, müssen Sie auf SQL-Ebene paginieren. Sie können die unten stehende Beispielabfrage verwenden:
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
Um die Ergebnisse Seite für Seite abzurufen, erhöhen Sie den page-Parameter in der Anfrage:
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"}'
Stoppen Sie, wenn result_count null ist.
Weitere Informationen zum Umgang mit großen Datensätzen finden Sie unter: Result Limits and Exporting Queries
Entfernen von relations-Daten aus den Ergebnissen
Wenn Data Explorer-Abfragen über die Benutzeroberfläche ausgeführt werden, wird den Ergebnissen ein relations-Objekt hinzugefügt. Diese Daten werden zum Rendern des Benutzers in den UI-Ergebnissen verwendet, sind aber wahrscheinlich nicht erforderlich, wenn Sie Abfragen über die API ausführen.
Um diese Daten aus den Ergebnissen zu entfernen, fügen Sie Ihrem Request den Parameter download=true hinzu:
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"
API-Authentifizierung
Details zur Erstellung eines API-Schlüssels für die Anfragen finden Sie hier: Create and configure an API key .
Wenn der API-Schlüssel nur zum Ausführen von Data Explorer-Abfragen verwendet werden soll, können Sie im Dropdown-Menü „Scope“ „Granular“ auswählen und dann den Scope „run queries“ auswählen.
FAQs
Gibt es einen API-Endpunkt, den ich verwenden kann, um die Liste der Berichte und die ID-Nummern abzurufen? Ich möchte ein Dropdown-Menü mit der Liste erstellen?
Ja, Sie können eine authentifizierte GET-Anfrage an /admin/plugins/discourse-data-explorer/queries.json senden, um eine Liste aller Abfragen auf der Site zu erhalten.
Ist es möglich, Abfragen über die API zu erstellen?
Ja. Dokumentation dazu finden Sie unter Create a Data Explorer query using the API
Ist es möglich, Parameter mit der POST-Anfrage zu senden?
Ja, SQL-Parameter können mit der Option -F gesendet werden, wie in den Beispielen gezeigt.
Wird der CSV-Export für Abfragen von der API unterstützt?
Ja. Hängen Sie .csv an die URL des Run-Endpunkts an, um Ergebnisse im CSV-Format zu erhalten:
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"}'
CSV-Antworten geben standardmäßig bis zu 10.000 Zeilen zurück. Sie können einen limit-Parameter übergeben, um diese Zahl zu reduzieren.