本指南介绍如何使用 Discourse API 来创建、运行和管理 Data Explorer 插件的查询。
所需用户级别：管理员
通过 Discourse API 几乎可以触发任何可以通过 Discourse 用户界面执行的操作。
本文档提供了专门与 Data Explorer 插件结合使用 API 的全面概述。
有关如何查找执行操作的正确 API 请求的常规概述，请参阅：Reverse engineer the Discourse API 。
运行 Data Explorer 查询
要通过 API 运行 Data Explorer 查询，请向 /admin/plugins/explorer/queries/<query-id>/run 发出 POST 请求。您可以通过在您的 Discourse 站点上访问该查询并在地址栏中查看 id 参数来找到查询 ID。
下面是一个 ID 为 20 的示例查询，它返回指定日期的按浏览量排序的主题：
--[params]
-- date :viewed_at
SELECT
topic_id,
COUNT(1) AS views_for_date
FROM topic_views
WHERE viewed_at = :viewed_at
GROUP BY topic_id
ORDER BY views_for_date DESC
可以使用以下命令从终端运行此查询：
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
请注意，您需要将 <api-key> 和 <your-site-url> 替换为您的 API 密钥和域名。
处理大型数据集
Data Explorer 插件默认将结果限制为 1000 行。要分页浏览更大的数据集，您可以使用下面的示例查询：
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
要逐页获取结果，请在请求中递增 page 参数：
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}'
当 result_count 为零时停止。
有关处理大型数据集的更多信息，请参阅：Result Limits and Exporting Queries
从结果中移除 relations 数据
当 Data Explorer 查询通过用户界面运行时，结果中会添加一个 relations 对象。此数据用于在 UI 结果中渲染用户，但在通过 API 运行查询时您不太可能需要它。
要从结果中删除该数据，请在请求中添加 download=true 参数：
curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}' \
-F "download=true"
API 身份验证
有关生成用于请求的 API 密钥的详细信息，请参阅：Create and configure an API key 。
如果 API 密钥仅用于运行 Data Explorer 查询，您可以从“Scope”（范围）下拉菜单中选择“Granular”（粒度），然后选择“run queries”（运行查询）范围。
常见问题解答
我可以使用任何 api 端点来获取报告列表和 ID 编号吗？我想在其中构建一个下拉列表？
是的，您可以向 /admin/plugins/explorer/queries.json 发出经过身份验证的 GET 请求，以获取站点上所有查询的列表。
是否可以通过 api 创建查询？
是的。有关如何执行此操作的文档位于 Create a Data Explorer query using the API
是否可以将参数与 post 请求一起发送？
是的，使用 -F 选项包含 SQL 参数，如示例所示。
API 是否支持查询的 CSV 导出？
虽然 JSON 输出是标准的，但您可以手动将结果转换为 CSV。原生 CSV 导出不再受支持。