将 Discourse Data Explorer 查询同步到 Google Sheets
本操作指南说明如何使用 Google Apps Script 自动将 Discourse Data Explorer 查询结果导入 Google Sheets。
所需用户级别：管理员
概述
通过将 Google Sheets 连接到 Discourse 站点的 Data Explorer 插件，您可以按计划自动提取查询结果。这对于创建仪表板、跟踪指标或与没有 Discourse 管理员访问权限的团队成员共享报告非常有用。
先决条件
在开始之前，请确保您拥有：
- 在您的 Discourse 站点上启用了 Data Explorer 插件
- 一个要同步的已保存的 Data Explorer 查询
- 对您的 Discourse 站点的管理员访问权限
- 一个有权访问 Google Sheets 的 Google 帐户
步骤 1：准备 Discourse
获取查询 ID
- 导航到您的 Discourse 站点的管理面板
- 转到 Plugins → Data Explorer
- 打开您要同步的查询
- 查看浏览器地址栏中的 URL——它看起来像
.../queries/123。末尾的数字就是您的 查询 ID
生成 API 密钥
-
转到 Admin → Advanced → API Keys
-
点击 New API Key
-
配置密钥：
- Description: 输入描述性内容，例如“Google Sheets Sync”
- User Level: 选择“Single User”并选择一个管理员用户，或选择“All Users”
- Scope: 选择“Granular”，然后在 Data Explorer 部分下勾选 run queries
使用精细的“run queries”范围将此 API 密钥限制为仅运行 Data Explorer 查询，这比使用全局密钥更安全。 -
点击 Save 并立即复制 API 密钥——您将无法再次看到它
有关 API 密钥的更多详细信息，请参阅：Create and configure an API key
步骤 2：设置 Google Apps Script
Google Apps Script 包含 UrlFetchApp 作为内置服务——您无需安装任何内容。只需将其键入代码编辑器中，脚本引擎就会自动识别它。
- 打开您的 Google Sheet
- 转到 Extensions → Apps Script
- 删除
Code.gs中任何现有代码并粘贴以下内容：
function syncDiscourseData() {
// ============ CONFIGURATION ============
const DISCOURSE_URL = "https://your-forum.com"; // 您的 Discourse URL（末尾不要有斜杠）
const QUERY_ID = "123"; // 您的 Data Explorer 查询 ID
const API_KEY = "your_api_key_here"; // 您的 API 密钥
const API_USERNAME = "system"; // 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();
// 清除现有数据并写入新数据
sheet.clear();
sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
// 在数据右侧的第二个单元格添加“上次更新”时间戳
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());
}
}
- 更新脚本顶部的配置值：
- 将
https://your-forum.com替换为您的 Discourse URL - 将
123替换为您的查询 ID - 将
your_api_key_here替换为您的 API 密钥
- 将
步骤 3：运行并授权脚本
-
点击 Save 图标 (
) 并命名您的项目（例如，“Discourse Sync”） -
点击 Run 按钮 (
) -
将出现一个弹出窗口要求授权：
- 点击 Review Permissions
- 选择您的 Google 帐户
- 如果您看到“Google hasn’t verified this app”，请点击 Advanced → Go to [Project Name] (unsafe)
- 点击 Allow
-
检查您的 Google Sheet——数据现在应该已显示
如果遇到错误，请在 Apps Script 编辑器中点击 View → Logs 查看详细的错误消息。
步骤 4：设置自动化同步（可选）
要按计划自动运行同步：
-
在 Apps Script 编辑器中，点击左侧边栏中的 Triggers 图标 (
) -
点击（右下角）+ Add Trigger
-
配置触发器：
- Function to run:
syncDiscourseData - Event source: Time-driven
- Type of time based trigger: 选择您偏好的频率（例如，Day timer, Hour timer）
- Time of day/interval: 选择您希望同步运行的时间
- Function to run:
-
点击 Save
处理带参数的查询
如果您的 Data Explorer 查询使用参数，请将它们添加到请求负载中：
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"
})
}
};
所有参数值都必须是字符串，即使是数字参数也是如此。
有关运行带参数查询的更多详细信息，请参阅：Run Data Explorer queries with the Discourse API
处理大型数据集
CSV 导出默认最多限制为 10,000 行。对于更大的数据集，请在查询中使用 LIMIT 和 OFFSET 参数来实现分页：
--[params]
-- integer :limit = 1000
-- integer :page = 0
SELECT *
FROM your_table
OFFSET :page * :limit
LIMIT :limit
然后修改您的脚本以循环遍历页面，直到没有更多结果返回为止。
故障排除
| 问题 | 解决方案 |
|---|---|
| 403 Forbidden 错误 | 验证您的 API 密钥是否具有“run queries”范围，并且用户名是否具有管理员访问权限 |
| 404 Not Found 错误 | 检查查询 ID 是否正确并且查询是否存在 |
| 结果为空 | 验证查询在 Data Explorer 中直接运行时是否返回数据 |
| 速率限制错误 | Discourse 默认将 Data Explorer API 请求限制为每 10 秒 2 次。如有需要，请在请求之间添加延迟 |