Sincronizza le 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 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 Plugin → Data Explorer
  3. Apri la query che desideri sincronizzare
  4. Guarda l’URL nella barra degli indirizzi del tuo browser: sarà simile a .../queries/123. Il numero alla fine è il tuo ID query

Generare una chiave API

  1. Vai su Admin → Avanzate → Chiavi API

  2. Clicca su Nuova chiave API

  3. Configura la chiave:

    • Descrizione: Inserisci qualcosa di descrittivo come “Sincronizzazione Google Sheets”
    • Livello utente: Seleziona “Utente singolo” e scegli un utente amministratore, oppure seleziona “Tutti gli utenti”
    • Ambito: Seleziona “Granulare”, quindi spunta esegui query nella sezione Data Explorer

    :information_source: L’utilizzo dell’ambito granulare “esegui query” limita questa chiave API alla sola esecuzione di query di Data Explorer, il che è più sicuro rispetto all’utilizzo di una chiave globale.

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

Per maggiori dettagli sulle chiavi API, consulta: Crea e configura una chiave API

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 Estensioni → 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/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);
    
    // Aggiunge un timestamp "Ultimo aggiornamento" due colonne dopo i dati
    const timestampCell = sheet.getRange(1, data[0].length + 2);
    const now = new Date();
    timestampCell.setValue("Ultimo aggiornamento: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Sincronizzate con successo " + (data.length - 1) + " righe");
    
  } catch (e) {
    Logger.log("Errore: " + 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 query
    • Sostituisci your_api_key_here con la tua chiave API

Passo 3: Eseguire e autorizzare lo script

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

  2. Clicca sul pulsante Esegui (:play_button:)

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

    • Clicca su Rivedi autorizzazioni
    • Seleziona il tuo account Google
    • Se vedi “Google non ha verificato questa app”, clicca su Avanzate → Vai a [Nome Progetto] (non sicuro)
    • Clicca su Consenti

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

:bulb: Se riscontri errori, clicca su Visualizza → Log nell’editor di Apps Script per vedere i messaggi di errore dettagliati.

Passo 4: Impostare la sincronizzazione automatica (facoltativo)

Per eseguire la sincronizzazione automaticamente secondo una pianificazione:

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

  2. Clicca su + Aggiungi trigger (in basso a destra)

  3. Configura il trigger:

    • Funzione da eseguire: syncDiscourseData
    • Origine evento: Basato sul tempo
    • Tipo di trigger basato sul tempo: Scegli la frequenza preferita (es. Timer giornaliero, Timer orario)
    • Ora del giorno/intervallo: Seleziona quando vuoi che venga eseguita la sincronizzazione

  4. Clicca su Salva

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: Esegui query di Data Explorer con l’API di Discourse

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 l’ambito “esegui query” 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 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

2 Mi Piace