Sincronizar datos de Discourse Data Explorer con Google Sheets
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.
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, rastrear métricas o compartir informes con miembros del equipo que no tienen acceso de administrador de Discourse.
Requisitos previos
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 su ID de consulta
- Navegue al panel de Administración de su sitio de Discourse
- Vaya a Plugins → Data Explorer
- Abra la consulta que desea sincronizar
- Observe 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
-
Vaya a Admin → Advanced → API Keys (Administración → Avanzado → Claves de API)
-
Haga clic en New API Key (Nueva clave de API)
-
Configure la clave:
- Description: Ingrese algo descriptivo como “Sincronización de Google Sheets”
- User Level: Seleccione “Single User” (Usuario único) y elija un usuario administrador, o seleccione “All Users” (Todos los usuarios)
- Scope: Seleccione “Granular” (Granular) y luego marque run queries (ejecutar consultas) en la sección Data Explorer
Usar el ámbito 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. -
Haga clic en Save (Guardar) y copie la clave de API inmediatamente; no podrá volver a verla
Para obtener más detalles sobre las claves de API, consulte: Create and configure an API key (Crear y configurar una clave de API)
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.
- Abra su Google Sheet
- Vaya a Extensions → Apps Script (Extensiones → Apps Script)
- Elimine cualquier código existente en
Code.gsy pegue lo siguiente:
function syncDiscourseData() {
// ============ CONFIGURATION ============\n const DISCOURSE_URL = \"https://your-forum.com\"; // Su URL de Discourse (sin barra final)\n const QUERY_ID = \"123\"; // Su ID de consulta de Data Explorer\n const API_KEY = \"your_api_key_here\"; // Su clave de API\n const API_USERNAME = \"system\"; // Nombre de usuario para las solicitudes de API\n // ========================================\n \n const url = `${DISCOURSE_URL}/admin/plugins/explorer/queries/${QUERY_ID}/run.csv`;\n \n const options = {\n \"method\": \"post\",\n \"headers\": {\n \"Api-Key\": API_KEY,\n \"Api-Username\": API_USERNAME\n }\n };\n\n try {\n const response = UrlFetchApp.fetch(url, options);\n const csvData = response.getContentText();\n const data = Utilities.parseCsv(csvData);\n \n const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();\n \n // Borrar datos existentes y escribir datos nuevos\n sheet.clear(); \n sheet.getRange(1, 1, data.length, data[0].length).setValues(data);\n \n // Agregar una marca de tiempo "Last Updated" dos columnas después de los datos\n const timestampCell = sheet.getRange(1, data[0].length + 2);\n const now = new Date();\n timestampCell.setValue(\"Last Updated: \" + Utilities.formatDate(now, Session.getScriptTimeZone(), \"yyyy-MM-dd HH:mm:ss\"));\n timestampCell.setFontWeight(\"bold\");\n \n Logger.log(\"Successfully synced \" + (data.length - 1) + \" rows\");\n \n } catch (e) {\n Logger.log(\"Error: \" + e.toString());\n }\n}\n```
4. 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) (💾) y asigne un nombre a su proyecto (por ejemplo, "Discourse Sync")
2. Haga clic en el botón **Run** (Ejecutar) (▶️)
3. Aparecerá una ventana emergente solicitando 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. Verifique 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) (🕐) en la barra lateral izquierda
2. Haga clic en **+ Add Trigger** (Añadir desencadenador) (esquina inferior derecha)
3. Configure el desencadenador:
* **Function to run:** `syncDiscourseData`
* **Event source:** Time-driven (Impulsado por el tiempo)
* **Type of time based trigger:** Elija su frecuencia preferida (por ejemplo, Day timer, Hour timer)
* **Time of day/interval:** 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:
```javascript
const options = {\n \"method\": \"post\",\n \"headers\": {\n \"Api-Key\": API_KEY,\n \"Api-Username\": API_USERNAME\n },\n \"payload\": {\n \"params\": JSON.stringify({\n \"start_date\": \"2024-01-01\",\n \"category_id\": \"5\"\n })\n }\n};\n```
> :warning: Todos los valores de los parámetros deben ser cadenas, incluso para los parámetros numéricos.
Para obtener más detalles sobre la ejecución de consultas parametrizadas, consulte: [Run Data Explorer queries with the Discourse API](https://meta.discourse.org/t/run-data-explorer-queries-with-the-discourse-api/120063) (Ejecutar consultas de Data Explorer con la API de Discourse)
## 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`:
```sql
--[params]\n-- integer :limit = 1000\n-- integer :page = 0\n\nSELECT *\nFROM your_table\nOFFSET :page * :limit\nLIMIT :limit\n```
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 ámbito "run queries" y que el nombre de usuario tenga acceso de administrador |
| Error 404 Not Found (No encontrado) | Verifique que el ID de 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 retrasos entre solicitudes si es necesario |
## Recursos adicionales
* [Discourse Data Explorer](https://meta.discourse.org/t/discourse-data-explorer/32566)
* [Run Data Explorer queries with the Discourse API](https://meta.discourse.org/t/run-data-explorer-queries-with-the-discourse-api/120063)
* [Create and configure an API key](https://meta.discourse.org/t/create-and-configure-an-api-key/230124)
* [Google Apps Script UrlFetchApp documentation](https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app)