Автоматизация синхронизации запросов Discourse с Google Sheets

Документация Интеграции
, ,
1

Синхронизация запросов Discourse Data Explorer с Google Sheets

:bookmark: В этом руководстве объясняется, как автоматизировать импорт результатов запросов Discourse Data Explorer в Google Sheets с помощью Google Apps Script.

:person_raising_hand: Требуемый уровень пользователя: Администратор

Обзор

Подключив Google Sheets к плагину Data Explorer вашего сайта Discourse, вы можете автоматически получать результаты запросов по расписанию. Это полезно для создания панелей управления, отслеживания метрик или обмена отчетами с членами команды, у которых нет доступа администратора к Discourse.

Предварительные требования

Перед началом убедитесь, что у вас есть:

  • Включенный плагин Data Explorer на вашем сайте Discourse
  • Сохраненный запрос Data Explorer, который вы хотите синхронизировать
  • Доступ администратора к вашему сайту Discourse
  • Учетная запись Google с доступом к Google Sheets

Шаг 1: Подготовка Discourse

Получите ID запроса

  1. Перейдите на панель администратора вашего сайта Discourse
  2. Перейдите в раздел Плагины → Data Explorer
  3. Откройте запрос, который хотите синхронизировать
  4. Посмотрите на URL в адресной строке браузера — он будет выглядеть как .../queries/123. Цифра в конце — это ваш ID запроса

Сгенерируйте API-ключ

  1. Перейдите в раздел Администрирование → Дополнительно → API-ключи

  2. Нажмите Создать новый API-ключ

  3. Настройте ключ:

    • Описание: Введите описательное название, например «Синхронизация с Google Sheets»
    • Уровень пользователя: Выберите «Один пользователь» и укажите администратора или выберите «Все пользователи»
    • Область действия: Выберите «Точная настройка», затем отметьте галочкой запуск запросов в разделе Data Explorer

    :information_source: Использование точной области действия «запуск запросов» ограничивает этот API-ключ только выполнением запросов Data Explorer, что безопаснее использования глобального ключа.

  4. Нажмите Сохранить и немедленно скопируйте API-ключ — вы больше не сможете его увидеть

Для получения дополнительной информации об API-ключах см.: Создание и настройка API-ключа

Шаг 2: Настройка Google Apps Script

Google Apps Script включает встроенную службу UrlFetchApp — ничего устанавливать не нужно. Просто введите её в редактор кода, и движок скриптов автоматически распознает её.

  1. Откройте вашу Google Таблицу
  2. Перейдите в Расширения → Apps Script
  3. Удалите любой существующий код в файле Code.gs и вставьте следующий:
function syncDiscourseData() {
  // ============ КОНФИГУРАЦИЯ ============
  const DISCOURSE_URL = "https://your-forum.com"; // URL вашего Discourse (без завершающего слэша)
  const QUERY_ID = "123";                         // ID вашего запроса Data Explorer
  const API_KEY = "your_api_key_here";            // Ваш API-ключ
  const API_USERNAME = "system";                  // Имя пользователя для API-запросов
  // ========================================
  
  const url = `${DISCOURSE_URL}/admin/plugins/discourse-data-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("Последнее обновление: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Успешно синхронизировано строк: " + (data.length - 1));
    
  } catch (e) {
    Logger.log("Ошибка: " + e.toString());
  }
}
  1. Обновите значения конфигурации в начале скрипта:
    • Замените https://your-forum.com на URL вашего Discourse
    • Замените 123 на ваш ID запроса
    • Замените your_api_key_here на ваш API-ключ

Шаг 3: Запуск и авторизация скрипта

  1. Нажмите значок Сохранить (:floppy_disk:) и назовите ваш проект (например, «Discourse Sync»)

  2. Нажмите кнопку Запустить (:play_button:)

  3. Появится всплывающее окно с запросом на авторизацию:

    • Нажмите Проверить разрешения
    • Выберите вашу учетную запись Google
    • Если вы видите сообщение «Google не проверил это приложение», нажмите Дополнительно → Перейти к [Название проекта] (небезопасно)
    • Нажмите Разрешить

  4. Проверьте вашу Google Таблицу — данные должны появиться

:bulb: Если возникнут ошибки, нажмите Вид → Журналы в редакторе Apps Script, чтобы увидеть подробные сообщения об ошибках.

Шаг 4: Настройка автоматической синхронизации (опционально)

Чтобы запускать синхронизацию автоматически по расписанию:

  1. В редакторе Apps Script нажмите значок Триггеры (:one_o_clock:) в левой боковой панели

  2. Нажмите + Добавить триггер (в правом нижнем углу)

  3. Настройте триггер:

    • Функция для запуска: syncDiscourseData
    • Источник события: По времени
    • Тип триггера по времени: Выберите желаемую частоту (например, Таймер дня, Таймер часа)
    • Время суток/интервал: Укажите, когда вы хотите запускать синхронизацию

  4. Нажмите Сохранить

Обработка запросов с параметрами

Если ваш запрос 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"
    })
  }
};

:warning: Все значения параметров должны быть строками, даже для числовых параметров.

Для получения дополнительной информации о запуске параметризованных запросов см.: Запуск запросов Data Explorer через API Discourse

Обработка больших наборов данных

Экспорт в CSV по умолчанию ограничен максимальным количеством 10 000 строк. Для больших наборов данных реализуйте пагинацию в вашем запросе, используя параметры LIMIT и OFFSET:

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

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

Затем измените ваш скрипт так, чтобы он перебирал страницы, пока не будут получены все результаты.

Устранение неполадок

Проблема Решение
Ошибка 403 Forbidden Убедитесь, что ваш API-ключ имеет область действия «запуск запросов», а у пользователя есть права администратора
Ошибка 404 Not Found Проверьте правильность ID запроса и наличие самого запроса
Пустые результаты Убедитесь, что запрос возвращает данные при запуске непосредственно в Data Explorer
Ошибки ограничения скорости Discourse по умолчанию ограничивает запросы к API Data Explorer до 2 в 10 секунд. При необходимости добавьте задержки между запросами

Дополнительные ресурсы

4 лайка