Esta guía explica cómo usar la API de Discourse para crear, ejecutar y administrar consultas con el plugin Data Explorer.
Nivel de usuario requerido: Administrador
Prácticamente cualquier acción que se pueda realizar a través de la interfaz de usuario de Discourse también se puede activar con la API de Discourse.
Este documento proporciona una descripción general completa para utilizar la API específicamente en conjunto con el plugin Data Explorer.
Para una descripción general de cómo encontrar la solicitud de API correcta para una acción, consulte: Reverse engineer the Discourse API .
Ejecutar una consulta de Data Explorer
Para ejecutar una consulta de Data Explorer a través de la API, realice una solicitud POST a /admin/plugins/explorer/queries/<query-id>/run. Puede encontrar el ID de la consulta visitándola a través de su sitio de Discourse y verificando el parámetro id en la barra de direcciones.
A continuación se muestra una consulta de ejemplo con un ID de 20 que devuelve temas por vistas en una fecha especificada:
--[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
Esta consulta se puede ejecutar desde una terminal con:
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"}'
Tenga en cuenta que deberá reemplazar <api-key> y <your-site-url> con su clave de API y dominio.
Manejo de grandes conjuntos de datos
El plugin Data Explorer limita los resultados a 1000 filas por defecto. Para paginar a través de conjuntos de datos más grandes, puede usar la consulta de ejemplo a continuación:
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
Para obtener los resultados página por página, incremente el parámetro page en la solicitud:
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"}'
Deténgase cuando result_count sea cero.
Para obtener información adicional sobre el manejo de grandes conjuntos de datos, consulte: Result Limits and Exporting Queries
Eliminación de datos de relations de los resultados
Cuando las consultas de Data Explorer se ejecutan a través de la interfaz de usuario, se agrega un objeto relations a los resultados. Estos datos se utilizan para representar al usuario en los resultados de la interfaz de usuario, pero es poco probable que los necesite al ejecutar consultas a través de la API.
Para eliminar esos datos de los resultados, agregue un parámetro download=true con su solicitud:
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"
Autenticación de API
Los detalles sobre cómo generar una clave de API para las solicitudes se pueden encontrar aquí: Create and configure an API key .
Si la clave de API solo se va a utilizar para ejecutar consultas de Data Explorer, puede seleccionar “Granular” en el menú desplegable Scope, y luego seleccionar el ámbito “run queries”.
Preguntas frecuentes
¿Hay algún endpoint de api que pueda usar para obtener la lista de informes y los números de ID? Quiero crear un menú desplegable con la lista.
Sí, puede realizar una solicitud GET autenticada a /admin/plugins/explorer/queries.json para obtener una lista de todas las consultas en el sitio.
¿Es posible crear consultas a través de la api?
Sí. La documentación sobre cómo hacerlo se encuentra en Create a Data Explorer query using the API
¿Es posible enviar parámetros con la solicitud post?
Sí, incluya parámetros SQL usando la opción -F, como se muestra en los ejemplos.
¿La exportación a CSV es compatible con la API para las consultas?
Aunque la salida JSON es estándar, puede convertir manualmente los resultados a CSV. La exportación nativa a CSV ya no es compatible.