Automatizzare la sincronizzazione delle query di Discourse con Google Sheets

Documentazione Integrazioni
, ,
1

Sincronizzare i dati di Discourse Data Explorer con Google Sheets

:bookmark: Questa guida spiega come automatizzare l’importazione dei risultati delle query di Discourse Data Explorer in Google Sheets utilizzando Google Apps Script.

:person_raising_hand: Livello utente richiesto: Amministratore

Panoramica

Collegando Google Sheets al plugin Data Explorer del tuo sito Discourse, puoi importare automaticamente i risultati delle query secondo una pianificazione. Questo è utile per creare dashboard, monitorare metriche o condividere report con i membri del team che non dispongono dell’accesso amministrativo a Discourse.

Prerequisiti

Prima di iniziare, assicurati di avere:

  • Il plugin Data Explorer abilitato sul tuo sito Discourse
  • Una query di Data Explorer salvata che desideri sincronizzare
  • Accesso amministrativo al tuo sito Discourse
  • Un account Google con accesso a Google Sheets

Passo 1: Preparare Discourse

Ottenere l’ID della query

  1. Vai al pannello di amministrazione del tuo sito Discourse
  2. Vai su Plugins → Data Explorer
  3. Apri la query che desideri sincronizzare
  4. Guarda l’URL nella barra degli indirizzi del tuo browser: apparirà come .../queries/123. Il numero alla fine è il tuo ID della query

Generare una chiave API

  1. Vai su Admin → Advanced → API Keys

  2. Clicca su New API Key

  3. Configura la chiave:

    • Description: Inserisci qualcosa di descrittivo come “Sincronizzazione Google Sheets”
    • User Level: Seleziona “Single User” e scegli un utente amministratore, oppure seleziona “All Users”
    • Scope: Seleziona “Granular”, quindi spunta run queries nella sezione Data Explorer

    :information_source: L’utilizzo dello scope granulare “run queries” limita questa chiave API solo all’esecuzione delle query di Data Explorer, il che è più sicuro rispetto all’utilizzo di una chiave globale.

  4. Clicca su Save e copia immediatamente la chiave API: non potrai piĂą vederla

Per maggiori dettagli sulle chiavi API, consulta: Create and configure an API key

Passo 2: Configurare Google Apps Script

Google Apps Script include UrlFetchApp come servizio integrato: non è necessario installare nulla. Basta digitarlo nell’editor di codice e il motore di script lo riconosce automaticamente.

  1. Apri il tuo Google Sheet
  2. Vai su Extensions → Apps Script
  3. Elimina qualsiasi codice esistente in Code.gs e incolla quanto segue:
function syncDiscourseData() {
  // ============ CONFIGURAZIONE ============
  const DISCOURSE_URL = "https://your-forum.com"; // Il tuo URL di Discourse (senza barra finale)
  const QUERY_ID = "123";                         // Il tuo ID della query di Data Explorer
  const API_KEY = "your_api_key_here";            // La tua chiave API
  const API_USERNAME = "system";                  // Nome utente per le richieste API
  // ========================================
  
  const url = `${DISCOURSE_URL}/admin/plugins/discourse-data-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();
    
    // Cancella i dati esistenti e scrivi i nuovi dati
    sheet.clear(); 
    sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
    
    // Aggiungi un timestamp "Last Updated" due colonne dopo i dati
    const timestampCell = sheet.getRange(1, data[0].length + 2);
    const now = new Date();
    timestampCell.setValue("Last Updated: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Successfully synced " + (data.length - 1) + " rows");
    
  } catch (e) {
    Logger.log("Error: " + e.toString());
  }
}
  1. Aggiorna i valori di configurazione all’inizio dello script:
    • Sostituisci https://your-forum.com con il tuo URL di Discourse
    • Sostituisci 123 con il tuo ID della query
    • Sostituisci your_api_key_here con la tua chiave API

Passo 3: Eseguire e autorizzare lo script

  1. Clicca sull’icona Save (:floppy_disk:) e assegna un nome al tuo progetto (es. “Discourse Sync”)

  2. Clicca sul pulsante Run (:play_button:)

  3. Apparirà un popup che richiede l’autorizzazione:

    • Clicca su Review Permissions
    • Seleziona il tuo account Google
    • Se vedi “Google hasn’t verified this app”, clicca su Advanced → Go to \[Project Name\] (unsafe)
    • Clicca su Allow

  4. Controlla il tuo Google Sheet: i dati dovrebbero apparire ora

:bulb: Se riscontri errori, clicca su View → Logs nell’editor di Apps Script per visualizzare i messaggi di errore dettagliati.

Passo 4: Configurare la sincronizzazione automatica (opzionale)

Per eseguire la sincronizzazione automaticamente secondo una pianificazione:

  1. Nell’editor di Apps Script, clicca sull’icona Triggers (:one_o_clock:) nella barra laterale sinistra

  2. Clicca su + Add Trigger (in basso a destra)

  3. Configura il trigger:

    • Function to run: syncDiscourseData
    • Event source: Time-driven
    • Type of time based trigger: Scegli la frequenza preferita (es. Day timer, Hour timer)
    • Time of day/interval: Seleziona quando vuoi che la sincronizzazione venga eseguita

  4. Clicca su Save

Gestione delle query con parametri

Se la tua query di Data Explorer utilizza parametri, aggiungili al payload della richiesta:

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: Tutti i valori dei parametri devono essere stringhe, anche per i parametri numerici.

Per maggiori dettagli sull’esecuzione di query parametrizzate, consulta: Run Data Explorer queries with the Discourse API

Gestione di set di dati di grandi dimensioni

Le esportazioni CSV sono limitate a un massimo di 10.000 righe per impostazione predefinita. Per set di dati piĂą grandi, implementa la paginazione nella tua query utilizzando i parametri LIMIT e OFFSET:

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

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

Quindi modifica lo script per ciclare tra le pagine finché non vengono restituiti più risultati.

Risoluzione dei problemi

Problema Soluzione
Errore 403 Forbidden Verifica che la tua chiave API abbia lo scope “run queries” e che il nome utente abbia accesso amministrativo
Errore 404 Not Found Verifica che l’ID della query sia corretto e che la query esista
Risultati vuoti Verifica che la query restituisca dati quando viene eseguita direttamente in Data Explorer
Errori di limitazione della frequenza (Rate limiting) Discourse limita le richieste API di Data Explorer a 2 ogni 10 secondi per impostazione predefinita. Aggiungi ritardi tra le richieste se necessario

Risorse aggiuntive

4 Mi Piace