Discourse-Abfragen mit Google Sheets synchronisieren

Dokumentation Integrationen
, ,
1

Syncronisieren von Discourse Data Explorer-Abfragen mit Google Sheets

:bookmark: Diese Anleitung erklärt, wie Sie den Import von Ergebnissen aus Data Explorer-Abfragen in Google Sheets mithilfe von Google Apps Script automatisieren.

:person_raising_hand: Erforderliche Benutzerebene: Administrator

Überblick

Durch die Verbindung von Google Sheets mit dem Data Explorer-Plugin Ihrer Discourse-Site können Sie Abfrageergebnisse automatisch nach einem Zeitplan abrufen. Dies ist nützlich für die Erstellung von Dashboards, die Verfolgung von Metriken oder das Teilen von Berichten mit Teammitgliedern, die keinen Discourse-Admin-Zugriff haben.

Voraussetzungen

Stellen Sie vor Beginn sicher, dass Sie Folgendes haben:

  • Das Data Explorer Plugin auf Ihrer Discourse-Site aktiviert
  • Eine gespeicherte Data Explorer-Abfrage, die Sie synchronisieren möchten
  • Administratorzugriff auf Ihre Discourse-Site
  • Ein Google-Konto mit Zugriff auf Google Sheets

Schritt 1: Discourse vorbereiten

Abfrage-ID abrufen

  1. Navigieren Sie zum Admin-Panel Ihrer Discourse-Site
  2. Gehen Sie zu Plugins → Data Explorer
  3. Öffnen Sie die Abfrage, die Sie synchronisieren möchten
  4. Schauen Sie in die URL in der Adressleiste Ihres Browsers – sie sieht wahrscheinlich so aus wie .../queries/123. Die Zahl am Ende ist Ihre Abfrage-ID

API-Schlüssel generieren

  1. Gehen Sie zu Admin → Erweitert → API-Schlüssel

  2. Klicken Sie auf Neuer API-Schlüssel

  3. Konfigurieren Sie den Schlüssel:

    • Beschreibung: Geben Sie etwas Beschreibendes ein, wie z. B. „Google Sheets Sync“
    • Benutzerebene: Wählen Sie „Einzelner Benutzer“ und wählen Sie einen Admin-Benutzer aus, oder wählen Sie „Alle Benutzer“
    • Geltungsbereich: Wählen Sie „Granular“ und aktivieren Sie dann Abfragen ausführen im Abschnitt Data Explorer

    :information_source: Die Verwendung des granularen Geltungsbereichs „Abfragen ausführen“ beschränkt diesen API-Schlüssel nur auf die Ausführung von Data Explorer-Abfragen, was sicherer ist, als einen globalen Schlüssel zu verwenden.

  4. Klicken Sie auf Speichern und kopieren Sie den API-Schlüssel sofort – Sie werden ihn nicht erneut sehen können

Weitere Details zu API-Schlüsseln finden Sie unter: Einen API-Schlüssel erstellen und konfigurieren

Schritt 2: Google Apps Script einrichten

Google Apps Script enthält UrlFetchApp als integrierten Dienst – Sie müssen nichts installieren. Geben Sie ihn einfach in den Code-Editor ein, und die Skript-Engine erkennt ihn automatisch.

  1. Öffnen Sie Ihr Google Sheet
  2. Gehen Sie zu Erweiterungen → Apps Script
  3. Löschen Sie jeglichen vorhandenen Code in Code.gs und fügen Sie Folgendes ein:
function syncDiscourseData() {
  // ============ KONFIGURATION ============
  const DISCOURSE_URL = "https://your-forum.com"; // Ihre Discourse URL (ohne abschließenden Schrägstrich)
  const QUERY_ID = "123";                         // Ihre Data Explorer Abfrage-ID
  const API_KEY = "your_api_key_here";            // Ihr API-Schlüssel
  const API_USERNAME = "system";                  // Benutzername für API-Anfragen
  // =======================================
  
  const url = `${DISCOURSE_URL}/admin/plugins/explorer/queries/${QUERY_ID}/run.csv`;
  
  const options = {
    "method": "post",
    "headers": {
      "Api-Key": API_KEY,
      "Api-Username": API_USERNAME
    }
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const csvData = response.getContentText();
    const data = Utilities.parseCsv(csvData);
    
    const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
    
    // Bestehende Daten löschen und neue Daten schreiben
    sheet.clear(); 
    sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
    
    // Einen „Zuletzt aktualisiert“-Zeitstempel zwei Spalten nach den Daten hinzufügen
    const timestampCell = sheet.getRange(1, data[0].length + 2);
    const now = new Date();
    timestampCell.setValue("Zuletzt aktualisiert: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Erfolgreich " + (data.length - 1) + " Zeilen synchronisiert");
    
  } catch (e) {
    Logger.log("Fehler: " + e.toString());
  }
}
  1. Aktualisieren Sie die Konfigurationswerte am Anfang des Skripts:
    • Ersetzen Sie https://your-forum.com durch Ihre Discourse-URL
    • Ersetzen Sie 123 durch Ihre Abfrage-ID
    • Ersetzen Sie your_api_key_here durch Ihren API-Schlüssel

Schritt 3: Skript ausführen und autorisieren

  1. Klicken Sie auf das Speichern-Symbol (:floppy_disk:) und geben Sie Ihrem Projekt einen Namen (z. B. „Discourse Sync“)

  2. Klicken Sie auf die Schaltfläche Ausführen (:play_button:)

  3. Es wird ein Popup angezeigt, das zur Autorisierung auffordert:

    • Klicken Sie auf Berechtigungen überprüfen
    • Wählen Sie Ihr Google-Konto
    • Wenn Sie „Google hat diese App nicht verifiziert“ sehen, klicken Sie auf Erweitert → Weiter zu [Projektname] (unsicher)
    • Klicken Sie auf Zulassen

  4. Überprüfen Sie Ihr Google Sheet – die Daten sollten nun angezeigt werden

:bulb: Wenn Fehler auftreten, klicken Sie im Apps Script-Editor auf Ansicht → Protokolle, um detaillierte Fehlermeldungen anzuzeigen.

Schritt 4: Automatisierte Synchronisierung einrichten (optional)

Um die Synchronisierung automatisch nach einem Zeitplan auszuführen:

  1. Klicken Sie im Apps Script-Editor auf das Symbol Trigger (:one_o_clock:) in der linken Seitenleiste

  2. Klicken Sie unten rechts auf + Trigger hinzufügen

  3. Konfigurieren Sie den Trigger:

    • Auszuführende Funktion: syncDiscourseData
    • Ereignisquelle: Zeitgesteuert
    • Art des zeitbasierten Triggers: Wählen Sie Ihre bevorzugte Frequenz (z. B. Tages-Timer, Stunden-Timer)
    • Tageszeit/Intervall: Wählen Sie aus, wann die Synchronisierung ausgeführt werden soll

  4. Klicken Sie auf Speichern

Umgang mit Abfragen mit Parametern

Wenn Ihre Data Explorer-Abfrage Parameter verwendet, fügen Sie diese der Anforderungs-Payload hinzu:

const options = {
  "method": "post",
  "headers": {
    "Api-Key": API_KEY,
    "Api-Username": API_USERNAME
  },
  "payload": {
    "params": JSON.stringify({
      "start_date": "2024-01-01",
      "category_id": "5"
    })
  }
};

:warning: Alle Parameterwerte müssen Zeichenfolgen sein, auch für numerische Parameter.

Weitere Details zur Ausführung parametrisierter Abfragen finden Sie unter: Data Explorer-Abfragen mit der Discourse API ausführen

Umgang mit großen Datensätzen

CSV-Exporte sind standardmäßig auf maximal 10.000 Zeilen begrenzt. Implementieren Sie für größere Datensätze die Paginierung in Ihrer Abfrage mithilfe der Parameter LIMIT und OFFSET:

--[params]
-- integer :limit = 1000
-- integer :page = 0

SELECT *
FROM your_table
OFFSET :page * :limit
LIMIT :limit

Ändern Sie dann Ihr Skript so, dass es durch die Seiten iteriert, bis keine Ergebnisse mehr zurückgegeben werden.

Fehlerbehebung

Problem Lösung
403 Forbidden Fehler Überprüfen Sie, ob Ihr API-Schlüssel den Geltungsbereich „Abfragen ausführen“ hat und der Benutzername Admin-Zugriff hat
404 Not Found Fehler Überprüfen Sie, ob die Abfrage-ID korrekt ist und die Abfrage existiert
Leere Ergebnisse Überprüfen Sie, ob die Abfrage Daten zurückgibt, wenn sie direkt in Data Explorer ausgeführt wird
Ratenbegrenzungsfehler Discourse begrenzt Data Explorer API-Anfragen standardmäßig auf 2 pro 10 Sekunden. Fügen Sie bei Bedarf Verzögerungen zwischen den Anfragen hinzu

Zusätzliche Ressourcen

2 „Gefällt mir“