Este guia explica como usar a API do Discourse para criar, executar e gerenciar consultas com o plugin Data Explorer.
Nível de usuário necessário: Administrador
Virtualmente qualquer ação que possa ser realizada através da interface do usuário do Discourse também pode ser acionada com a API do Discourse.
Este documento fornece uma visão geral abrangente para utilizar a API especificamente em conjunto com o plugin Data Explorer.
Para uma visão geral de como encontrar a solicitação de API correta para uma ação, consulte: Reverse engineer the Discourse API .
Executando uma consulta do Data Explorer
Para executar uma consulta do Data Explorer via API, faça uma solicitação POST para /admin/plugins/explorer/queries/<query-id>/run. Você pode encontrar o ID da consulta visitando-a através do seu site Discourse e verificando o parâmetro id na barra de endereço.
Abaixo está uma consulta de exemplo com um ID de 20 que retorna tópicos por visualizações em uma data 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 pode ser executada a partir de um terminal com:
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"}'
Note que você precisará substituir <api-key> e <your-site-url> pela sua chave de API e domínio.
Lidando com grandes conjuntos de dados
O plugin Data Explorer limita os resultados a 1000 linhas por padrão. Para paginar através de conjuntos de dados maiores, você pode usar a consulta de exemplo abaixo:
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
Para buscar os resultados página por página, incremente o parâmetro page na solicitação:
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"}'
Pare quando result_count for zero.
Para informações adicionais sobre como lidar com grandes conjuntos de dados, consulte: Result Limits and Exporting Queries
Removendo dados de relations dos resultados
Quando as consultas do Data Explorer são executadas através da interface do usuário, um objeto relations é adicionado aos resultados. Estes dados são usados para renderizar o usuário nos resultados da interface, mas é improvável que você precise deles ao executar consultas via API.
Para remover esses dados dos resultados, adicione um parâmetro download=true à sua solicitação:
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"
Autenticação da API
Detalhes sobre como gerar uma chave de API para as solicitações podem ser encontrados aqui: Create and configure an API key .
Se a chave de API for usada apenas para executar consultas do Data Explorer, você pode selecionar “Granular” no menu suspenso de Escopo (Scope) e, em seguida, selecionar o escopo “run queries”.
FAQs
Existe algum endpoint de api que eu possa usar para obter a lista de relatórios e os números de ID? Eu quero criar um menu suspenso com a lista nele?
Sim, você pode fazer uma solicitação GET autenticada para /admin/plugins/explorer/queries.json para obter uma lista de todas as consultas no site.
É possível criar consultas através da api?
Sim. A documentação sobre como fazer isso está em Create a Data Explorer query using the API
É possível enviar parâmetros com a solicitação post?
Sim, inclua parâmetros SQL usando a opção -F, como mostrado nos exemplos.
A exportação CSV para consultas é suportada pela API?
Embora a saída JSON seja o padrão, você pode converter manualmente os resultados para CSV. A exportação CSV nativa não é mais suportada.