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 über die Discourse API ausgelöst werden.
Dieses Dokument bietet einen umfassenden Überblick über die Verwendung der API speziell in Verbindung mit dem Data Explorer Plugin.
Eine allgemeine Übersicht darüber, wie Sie die richtige API-Anfrage für eine Aktion finden, finden Sie unter: 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-Anfrage an /admin/plugins/explorer/queries/<query-id>/run. Die Abfrage-ID finden Sie, indem Sie sie auf Ihrer Discourse-Seite besuchen und den id-Parameter in der Adressleiste überprüfen.
Unten sehen Sie 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/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 beschränkt die Ergebnisse standardmäßig auf 1000 Zeilen. Um größere Datensätze seitenweise abzurufen, können Sie 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 seitenweise abzurufen, erhöhen Sie den page-Parameter in der Anfrage:
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"}'
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 Abfragen über die API ausgeführt werden.
Um diese Daten aus den Ergebnissen zu entfernen, fügen Sie Ihrer Anfrage den Parameter download=true hinzu:
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"
API-Authentifizierung
Details zur Generierung 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 eine Dropdown-Liste damit erstellen?
Ja, Sie können eine authentifizierte GET-Anfrage an /admin/plugins/explorer/queries.json senden, um eine Liste aller Abfragen auf der Seite 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 fügen Sie mit der Option -F hinzu, wie in den Beispielen gezeigt.
Wird der CSV-Export für Abfragen von der API unterstützt?
Obwohl die JSON-Ausgabe Standard ist, können Sie Ergebnisse manuell in CSV konvertieren. Der native CSV-Export wird nicht mehr unterstützt.