Sincronizar consultas do Discourse com o Google Sheets

Documentação Integrações
, ,
1

Sincronizar Consultas do Discourse Data Explorer com o Google Sheets

:bookmark: Este guia prático explica como automatizar a importação dos resultados de consultas do Data Explorer do Discourse para o Google Sheets usando o Google Apps Script.

:person_raising_hand: Nível de usuário necessário: Administrador

Visão Geral

Ao conectar o Google Sheets ao plugin Data Explorer do seu site Discourse, você pode importar automaticamente os resultados das consultas em uma programação. Isso é útil para criar painéis, rastrear métricas ou compartilhar relatórios com membros da equipe que não têm acesso de administrador do Discourse.

Pré-requisitos

Antes de começar, certifique-se de ter:

  • O plugin Data Explorer ativado no seu site Discourse
  • Uma consulta do Data Explorer salva que você deseja sincronizar
  • Acesso de administrador ao seu site Discourse
  • Uma conta Google com acesso ao Google Sheets

Passo 1: Preparar o Discourse

Obter seu ID de consulta

  1. Navegue até o painel de Administração do seu site Discourse
  2. Vá para Plugins → Data Explorer
  3. Abra a consulta que você deseja sincronizar
  4. Olhe o URL na barra de endereço do seu navegador — ele será parecido com .../queries/123. O número no final é o seu ID de consulta

Gerar uma chave de API

  1. Vá para Admin → Avançado → Chaves de API

  2. Clique em Nova Chave de API

  3. Configure a chave:

    • Descrição: Insira algo descritivo como “Sincronização Google Sheets”
    • Nível de Usuário: Selecione “Usuário Único” e escolha um usuário administrador, ou selecione “Todos os Usuários”
    • Escopo: Selecione “Granular” e marque executar consultas na seção Data Explorer

    :information_source: Usar o escopo granular “executar consultas” limita esta chave de API apenas a executar consultas do Data Explorer, o que é mais seguro do que usar uma chave global.

  4. Clique em Salvar e copie a chave de API imediatamente — você não poderá vê-la novamente

Para mais detalhes sobre chaves de API, consulte: Criar e configurar uma chave de API

Passo 2: Configurar o Google Apps Script

O Google Apps Script inclui o UrlFetchApp como um serviço integrado — você não precisa instalar nada. Basta digitá-lo no editor de código e o mecanismo de script o reconhece automaticamente.

  1. Abra sua Planilha Google
  2. Vá para Extensões → Apps Script
  3. Exclua qualquer código existente em Code.gs e cole o seguinte:
function syncDiscourseData() {
  // ============ CONFIGURAÇÃO ============
  const DISCOURSE_URL = "https://your-forum.com"; // Sua URL do Discourse (sem barra final)
  const QUERY_ID = "123";                         // Seu ID de consulta do Data Explorer
  const API_KEY = "your_api_key_here";            // Sua chave de API
  const API_USERNAME = "system";                  // Nome de usuário para solicitações de 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();
    
    // Limpa dados existentes e escreve novos dados
    sheet.clear(); 
    sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
    
    // Adiciona um carimbo de data/hora "Última Atualização" duas colunas após os dados
    const timestampCell = sheet.getRange(1, data[0].length + 2);
    const now = new Date();
    timestampCell.setValue("Última Atualização: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Sincronizado com sucesso " + (data.length - 1) + " linhas");
    
  } catch (e) {
    Logger.log("Erro: " + e.toString());
  }
}
  1. Atualize os valores de configuração no topo do script:
    • Substitua https://your-forum.com pela sua URL do Discourse
    • Substitua 123 pelo seu ID de consulta
    • Substitua your_api_key_here pela sua chave de API

Passo 3: Executar e autorizar o script

  1. Clique no ícone Salvar (:floppy_disk:) e nomeie seu projeto (ex: “Sincronização Discourse”)

  2. Clique no botão Executar (:play_button:)

  3. Um pop-up aparecerá solicitando autorização:

    • Clique em Revisar Permissões
    • Selecione sua conta Google
    • Se você vir “O Google não verificou este app”, clique em Avançado → Ir para \[Nome do Projeto\] (não seguro)
    • Clique em Permitir

  4. Verifique sua Planilha Google — os dados devem aparecer agora

:bulb: Se você encontrar erros, clique em Visualizar → Logs no editor do Apps Script para ver mensagens de erro detalhadas.

Passo 4: Configurar a sincronização automática (opcional)

Para executar a sincronização automaticamente em uma programação:

  1. No editor do Apps Script, clique no ícone Triggers (:one_o_clock:) na barra lateral esquerda

  2. Clique em + Adicionar Gatilho (canto inferior direito)

  3. Configure o gatilho:

    • Função a ser executada: syncDiscourseData
    • Fonte de evento: Baseado em tempo
    • Tipo de gatilho baseado em tempo: Escolha sua frequência preferida (ex: Timer diário, Timer por hora)
    • Hora do dia/intervalo: Selecione quando você deseja que a sincronização seja executada

  4. Clique em Salvar

Lidando com consultas com parâmetros

Se sua consulta do Data Explorer usar parâmetros, adicione-os ao payload da solicitação:

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"
    })
  }
};

:warning: Todos os valores de parâmetro devem ser strings, mesmo para parâmetros numéricos.

Para mais detalhes sobre a execução de consultas parametrizadas, consulte: Executar consultas do Data Explorer com a API do Discourse

Lidando com grandes conjuntos de dados

As exportações CSV têm como padrão um máximo de 10.000 linhas. Para conjuntos de dados maiores, implemente paginação em sua consulta usando os parâmetros LIMIT e OFFSET:

--[params]
-- integer :limit = 1000
-- integer :page = 0

SELECT *
FROM your_table
OFFSET :page * :limit
LIMIT :limit

Em seguida, modifique seu script para percorrer as páginas até que nenhum resultado adicional seja retornado.

Solução de problemas

Problema Solução
Erro 403 Forbidden Verifique se sua chave de API tem o escopo “executar consultas” e se o nome de usuário tem acesso de administrador
Erro 404 Not Found Verifique se o ID da consulta está correto e se a consulta existe
Resultados vazios Verifique se a consulta retorna dados quando executada diretamente no Data Explorer
Erros de limitação de taxa O Discourse limita as solicitações da API do Data Explorer a 2 a cada 10 segundos por padrão. Adicione atrasos entre as solicitações, se necessário

Recursos adicionais

2 curtidas