Automatizar la sincronización de consultas de Discourse con Google Sheets

Documentación Integraciones
, ,
1

Sincronizar datos de Discourse Data Explorer con Google Sheets

:bookmark: Esta guía de cómo hacerlo explica cómo automatizar la importación de los resultados de las consultas de Data Explorer de Discourse a Google Sheets usando Google Apps Script.

:person_raising_hand: Nivel de usuario requerido: Administrador

Resumen

Al conectar Google Sheets a su complemento Data Explorer del sitio de Discourse, puede extraer automáticamente los resultados de las consultas según un horario. Esto es útil para crear paneles de control, rastrear métricas o compartir informes con miembros del equipo que no tienen acceso de administrador de Discourse.

Prerrequisitos

Antes de comenzar, asegúrese de tener:

  • El complemento Data Explorer habilitado en su sitio de Discourse
  • Una consulta de Data Explorer guardada que desea sincronizar
  • Acceso de administrador a su sitio de Discourse
  • Una cuenta de Google con acceso a Google Sheets

Paso 1: Preparar Discourse

Obtener el ID de su consulta

  1. Navegue al panel de Administración de su sitio de Discourse
  2. Vaya a Plugins → Data Explorer
  3. Abra la consulta que desea sincronizar
  4. Mire la URL en la barra de direcciones de su navegador; se verá como .../queries/123. El número al final es su ID de consulta

Generar una clave de API

  1. Vaya a Admin → Advanced → API Keys (Administración → Avanzado → Claves de API)

  2. Haga clic en New API Key (Nueva clave de API)

  3. Configure la clave:

    • Description (Descripción): Ingrese algo descriptivo como “Sincronización de Google Sheets”
    • User Level (Nivel de usuario): Seleccione “Single User” (Usuario único) y elija un usuario administrador, o seleccione “All Users” (Todos los usuarios)
    • Scope (Alcance): Seleccione “Granular” (Granular), luego marque run queries (ejecutar consultas) en la sección Data Explorer

    :information_source: Usar el alcance granular “run queries” limita esta clave de API solo a ejecutar consultas de Data Explorer, lo cual es más seguro que usar una clave global.

  4. Haga clic en Save (Guardar) y copie la clave de API inmediatamente; no podrá volver a verla

Para más detalles sobre las claves de API, consulte: Create and configure an API key

Paso 2: Configurar Google Apps Script

Google Apps Script incluye UrlFetchApp como un servicio incorporado; no necesita instalar nada. Simplemente escríbalo en el editor de código y el motor de scripts lo reconocerá automáticamente.

  1. Abra su Google Sheet
  2. Vaya a Extensions → Apps Script (Extensiones → Apps Script)
  3. Elimine cualquier código existente en Code.gs y pegue lo siguiente:
function syncDiscourseData() {
  // ============ CONFIGURATION ============
  const DISCOURSE_URL = "https://your-forum.com"; // Su URL de Discourse (sin barra final)
  const QUERY_ID = "123";                         // Su ID de consulta de Data Explorer
  const API_KEY = "your_api_key_here";            // Su clave de API
  const API_USERNAME = "system";                  // Nombre de usuario para las solicitudes de 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();
    
    // Borrar datos existentes y escribir datos nuevos
    sheet.clear(); 
    sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
    
    // Agregar una marca de tiempo "Last Updated" (Última actualización) dos columnas después de los datos
    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. Actualice los valores de configuración en la parte superior del script:
    • Reemplace https://your-forum.com con su URL de Discourse
    • Reemplace 123 con su ID de consulta
    • Reemplace your_api_key_here con su clave de API

Paso 3: Ejecutar y autorizar el script

  1. Haga clic en el icono Save (Guardar) (:floppy_disk:) y asigne un nombre a su proyecto (ej. “Discourse Sync”)

  2. Haga clic en el botón Run (Ejecutar) (:play_button:)

  3. Aparecerá una ventana emergente pidiendo autorización:

    • Haga clic en Review Permissions (Revisar permisos)
    • Seleccione su cuenta de Google
    • Si ve “Google hasn’t verified this app” (Google no ha verificado esta aplicación), haga clic en Advanced (Avanzado) → Go to [Project Name] (unsafe) (Ir a [Nombre del proyecto] (no seguro))
    • Haga clic en Allow (Permitir)

  4. Revise su Google Sheet; los datos deberían aparecer ahora

:bulb: Si encuentra errores, haga clic en View → Logs (Ver → Registros) en el editor de Apps Script para ver mensajes de error detallados.

Paso 4: Configurar la sincronización automática (opcional)

Para ejecutar la sincronización automáticamente según un horario:

  1. En el editor de Apps Script, haga clic en el icono Triggers (Desencadenadores) (:one_o_clock:) en la barra lateral izquierda

  2. Haga clic en + Add Trigger (Añadir desencadenador) (esquina inferior derecha)

  3. Configure el desencadenador:

    • Function to run (Función a ejecutar): syncDiscourseData
    • Event source (Fuente de evento): Time-driven (Basado en tiempo)
    • Type of time based trigger (Tipo de desencadenador basado en tiempo): Elija su frecuencia preferida (ej. Day timer, Hour timer)
    • Time of day/interval (Hora del día/intervalo): Seleccione cuándo desea que se ejecute la sincronización

  4. Haga clic en Save (Guardar)

Manejo de consultas con parámetros

Si su consulta de Data Explorer utiliza parámetros, agréguelos a la carga útil de la solicitud:

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: Todos los valores de los parámetros deben ser cadenas de texto, incluso para los parámetros numéricos.

Para más detalles sobre la ejecución de consultas parametrizadas, consulte: Run Data Explorer queries with the Discourse API

Manejo de conjuntos de datos grandes

Las exportaciones CSV tienen un límite predeterminado de 10,000 filas. Para conjuntos de datos más grandes, implemente la paginación en su consulta utilizando los parámetros LIMIT y OFFSET:

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

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

Luego modifique su script para iterar a través de las páginas hasta que no se devuelvan más resultados.

Solución de problemas

Problema Solución
Error 403 Forbidden (Prohibido) Verifique que su clave de API tenga el alcance “run queries” y que el nombre de usuario tenga acceso de administrador
Error 404 Not Found (No encontrado) Verifique que el ID de la consulta sea correcto y que la consulta exista
Resultados vacíos Verifique que la consulta devuelva datos cuando se ejecuta directamente en Data Explorer
Errores de limitación de velocidad (Rate limiting) Discourse limita las solicitudes de API de Data Explorer a 2 por cada 10 segundos por defecto. Agregue demoras entre solicitudes si es necesario

Recursos adicionales

4 Me gusta