Synchroniser les requêtes Discourse avec Google Sheets

Documentation Intégrations
, ,
1

Synchroniser les données de Discourse Data Explorer avec Google Sheets

:bookmark: Ce guide pratique explique comment automatiser l’importation des résultats des requêtes de Discourse Data Explorer dans Google Sheets à l’aide de Google Apps Script.

:person_raising_hand: Niveau d’utilisateur requis : Administrateur

Vue d’ensemble

En connectant Google Sheets au plugin Data Explorer de votre site Discourse, vous pouvez importer automatiquement les résultats des requêtes selon un calendrier défini. Ceci est utile pour créer des tableaux de bord, suivre des métriques ou partager des rapports avec des membres de l’équipe qui n’ont pas d’accès administrateur à Discourse.

Prérequis

Avant de commencer, assurez-vous de disposer :

  • Du plugin Data Explorer activé sur votre site Discourse
  • D’une requête Data Explorer enregistrée que vous souhaitez synchroniser
  • D’un accès Administrateur à votre site Discourse
  • D’un compte Google avec accès à Google Sheets

Étape 1 : Préparer Discourse

Obtenir votre ID de requête

  1. Accédez au panneau d’administration de votre site Discourse
  2. Allez dans Plugins → Data Explorer
  3. Ouvrez la requête que vous souhaitez synchroniser
  4. Regardez l’URL dans la barre d’adresse de votre navigateur — elle ressemblera à .../queries/123. Le nombre à la fin est votre ID de requête

Générer une clé API

  1. Allez dans Admin → Avancé → Clés API

  2. Cliquez sur Nouvelle clé API

  3. Configurez la clé :

    • Description : Entrez quelque chose de descriptif comme « Synchronisation Google Sheets »
    • Niveau d’utilisateur : Sélectionnez « Utilisateur unique » et choisissez un utilisateur administrateur, ou sélectionnez « Tous les utilisateurs »
    • Portée (Scope) : Sélectionnez « Granulaire », puis cochez exécuter des requêtes sous la section Data Explorer

    :information_source: L’utilisation de la portée granulaire « exécuter des requêtes » limite cette clé API à l’exécution des requêtes Data Explorer uniquement, ce qui est plus sûr que d’utiliser une clé globale.

  4. Cliquez sur Enregistrer et copiez immédiatement la clé API — vous ne pourrez plus la voir

Pour plus de détails sur les clés API, consultez : Créer et configurer une clé API

Étape 2 : Configurer Google Apps Script

Google Apps Script inclut UrlFetchApp comme service intégré — vous n’avez rien à installer. Tapez-le simplement dans l’éditeur de code et le moteur de script le reconnaît automatiquement.

  1. Ouvrez votre Google Sheet
  2. Allez dans Extensions → Apps Script
  3. Supprimez tout code existant dans Code.gs et collez ce qui suit :
function syncDiscourseData() {
  // ============ CONFIGURATION ============
  const DISCOURSE_URL = "https://your-forum.com"; // Votre URL Discourse (sans barre oblique finale)
  const QUERY_ID = "123";                         // Votre ID de requête Data Explorer
  const API_KEY = "your_api_key_here";            // Votre clé API
  const API_USERNAME = "system";                  // Nom d'utilisateur pour les requêtes 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();
    
    // Effacer les données existantes et écrire les nouvelles données
    sheet.clear(); 
    sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
    
    // Ajouter un horodatage "Dernière mise à jour" deux colonnes après les données
    const timestampCell = sheet.getRange(1, data[0].length + 2);
    const now = new Date();
    timestampCell.setValue("Dernière mise à jour : " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Synchronisation réussie de " + (data.length - 1) + " lignes");
    
  } catch (e) {
    Logger.log("Erreur : " + e.toString());
  }
}
  1. Mettez à jour les valeurs de configuration en haut du script :
    • Remplacez https://your-forum.com par votre URL Discourse
    • Remplacez 123 par votre ID de requête
    • Remplacez your_api_key_here par votre clé API

Étape 3 : Exécuter et autoriser le script

  1. Cliquez sur l’icône Enregistrer (:floppy_disk:) et nommez votre projet (par exemple, « Synchronisation Discourse »)

  2. Cliquez sur le bouton Exécuter (:play_button:)

  3. Une fenêtre contextuelle apparaîtra demandant l’autorisation :

    • Cliquez sur Examiner les autorisations
    • Sélectionnez votre compte Google
    • Si vous voyez « Google n’a pas vérifié cette application », cliquez sur Avancé → Accéder à [Nom du projet] (non sécurisé)
    • Cliquez sur Autoriser

  4. Vérifiez votre Google Sheet — les données devraient maintenant apparaître

:bulb: Si vous rencontrez des erreurs, cliquez sur Afficher → Journaux dans l’éditeur Apps Script pour voir les messages d’erreur détaillés.

Étape 4 : Configurer la synchronisation automatisée (facultatif)

Pour exécuter la synchronisation automatiquement selon un calendrier :

  1. Dans l’éditeur Apps Script, cliquez sur l’icône Déclencheurs (:one_o_clock:) dans la barre latérale gauche

  2. Cliquez sur + Ajouter un déclencheur (en bas à droite)

  3. Configurez le déclencheur :

    • Fonction à exécuter : syncDiscourseData
    • Source de l’événement : Basé sur le temps (Time-driven)
    • Type de déclencheur basé sur le temps : Choisissez votre fréquence préférée (par exemple, Minuteur journalier, Minuteur horaire)
    • Heure de la journée/intervalle : Sélectionnez quand vous souhaitez que la synchronisation s’exécute

  4. Cliquez sur Enregistrer

Gestion des requêtes avec paramètres

Si votre requête Data Explorer utilise des paramètres, ajoutez-les à la charge utile de la requête :

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: Toutes les valeurs de paramètre doivent être des chaînes de caractères, même pour les paramètres numériques.

Pour plus de détails sur l’exécution de requêtes paramétrées, consultez : Exécuter des requêtes Data Explorer avec l’API Discourse

Gestion des grands ensembles de données

Les exportations CSV sont limitées par défaut à un maximum de 10 000 lignes. Pour les ensembles de données plus volumineux, implémentez la pagination dans votre requête en utilisant les paramètres LIMIT et OFFSET :

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

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

Modifiez ensuite votre script pour boucler sur les pages jusqu’à ce qu’aucun autre résultat ne soit renvoyé.

Dépannage

Problème Solution
Erreur 403 Forbidden Vérifiez que votre clé API a la portée « exécuter des requêtes » et que le nom d’utilisateur a un accès administrateur
Erreur 404 Not Found Vérifiez que l’ID de la requête est correct et que la requête existe
Résultats vides Vérifiez que la requête renvoie des données lorsqu’elle est exécutée directement dans Data Explorer
Erreurs de limitation de débit (Rate limiting) Discourse limite les requêtes API Data Explorer à 2 toutes les 10 secondes par défaut. Ajoutez des délais entre les requêtes si nécessaire

Ressources supplémentaires

2 « J'aime »