مزامنة استعلامات Discourse مع جداول بيانات Google

توثيق التكاملات
, ,
1

مزامنة بيانات مستكشف بيانات Discourse مع جداول بيانات Google

:bookmark: يشرح هذا الدليل الإرشادي كيفية أتمتة استيراد نتائج استعلامات مستكشف بيانات Discourse إلى جداول بيانات Google باستخدام Google Apps Script.

:person_raising_hand: مستوى المستخدم المطلوب: مسؤول (Administrator)

نظرة عامة

من خلال ربط جداول بيانات Google بمكون الإضافة Data Explorer في موقع Discourse الخاص بك، يمكنك سحب نتائج الاستعلام تلقائيًا وفقًا لجدول زمني. هذا مفيد لإنشاء لوحات معلومات، أو تتبع المقاييس، أو مشاركة التقارير مع أعضاء الفريق الذين ليس لديهم وصول إداري إلى Discourse.

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

  • تم تمكين مكون الإضافة Data Explorer الإضافي على موقع Discourse الخاص بك
  • استعلام Data Explorer محفوظ تريد مزامنته
  • وصول إداري إلى موقع Discourse الخاص بك
  • حساب Google لديه إمكانية الوصول إلى جداول بيانات Google

الخطوة 1: إعداد Discourse

الحصول على معرّف الاستعلام الخاص بك

  1. انتقل إلى لوحة تحكم المسؤول (Admin panel) في موقع Discourse الخاص بك
  2. انتقل إلى المكونات الإضافية (Plugins) ← مستكشف البيانات (Data Explorer)
  3. افتح الاستعلام الذي تريد مزامنته
  4. انظر إلى عنوان URL في شريط عنوان المتصفح الخاص بك - سيبدو كـ .../queries/123. الرقم الموجود في النهاية هو معرّف الاستعلام (query ID) الخاص بك

إنشاء مفتاح API

  1. انتقل إلى مسؤول (Admin) ← متقدم (Advanced) ← مفاتيح API (API Keys)

  2. انقر فوق مفتاح API جديد (New API Key)

  3. قم بتهيئة المفتاح:

    • الوصف (Description): أدخل شيئًا وصفيًا مثل “مزامنة جداول بيانات Google (Google Sheets Sync)”
    • مستوى المستخدم (User Level): حدد “مستخدم واحد (Single User)” واختر مستخدمًا مسؤولًا، أو حدد “جميع المستخدمين (All Users)”
    • النطاق (Scope): حدد “مفصل (Granular)”، ثم حدد تشغيل الاستعلامات (run queries) ضمن قسم مستكشف البيانات (Data Explorer)

    :information_source: استخدام النطاق المفصل “تشغيل الاستعلامات” يقصر مفتاح API هذا على تشغيل استعلامات مستكشف البيانات فقط، وهو أكثر أمانًا من استخدام مفتاح عام.

  4. انقر فوق حفظ (Save) و انسخ مفتاح API فورًا - لن تتمكن من رؤيته مرة أخرى

لمزيد من التفاصيل حول مفاتيح API، راجع: إنشاء مفتاح API وتهيئته

الخطوة 2: إعداد Google Apps Script

يتضمن Google Apps Script خدمة مدمجة تسمى UrlFetchApp - لا تحتاج إلى تثبيت أي شيء. ما عليك سوى كتابتها في محرر التعليمات البرمجية وسيتعرف عليها محرك البرمجة النصية تلقائيًا.

  1. افتح جدول بيانات Google الخاص بك
  2. انتقل إلى الإضافات (Extensions) ← برنامج Apps Script (Apps Script)
  3. احذف أي تعليمات برمجية موجودة في Code.gs والصق ما يلي:
function syncDiscourseData() {
  // ============ CONFIGURATION ============
  const DISCOURSE_URL = "https://your-forum.com"; // عنوان URL الخاص بـ Discourse الخاص بك (بدون علامة / لاحقة)
  const QUERY_ID = "123";                         // معرّف مستكشف البيانات (Data Explorer query ID) الخاص بك
  const API_KEY = "your_api_key_here";            // مفتاح API الخاص بك
  const API_USERNAME = "system";                  // اسم المستخدم لطلبات 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();
    
    // مسح البيانات الموجودة وكتابة البيانات الجديدة
    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("Last Updated: " + Utilities.formatDate(now, Session.getScriptTimeZone(), "yyyy-MM-dd HH:mm:ss"));
    timestampCell.setFontWeight("bold");
    
    Logger.log("Successfully synced " + (data.length - 1) + " rows");
    
  } catch (e) {
    Logger.log("Error: " + e.toString());
  }
}
  1. قم بتحديث قيم التهيئة في الجزء العلوي من البرنامج النصي:
    • استبدل https://your-forum.com بعنوان URL الخاص بـ Discourse
    • استبدل 123 بمعرّف الاستعلام الخاص بك
    • استبدل your_api_key_here بمفتاح API الخاص بك

الخطوة 3: تشغيل البرنامج النصي وتفويضه

  1. انقر فوق أيقونة حفظ (Save) (:floppy_disk:) وقم بتسمية مشروعك (على سبيل المثال: “مزامنة Discourse (Discourse Sync)”)

  2. انقر فوق زر تشغيل (Run) (:play_button:)

  3. ستظهر نافذة منبثقة تطلب التفويض:

    • انقر فوق مراجعة الأذونات (Review Permissions)
    • حدد حساب Google الخاص بك
    • إذا رأيت “لم يقم Google بالتحقق من هذا التطبيق”، فانقر فوق متقدم (Advanced) ← الانتقال إلى [اسم المشروع] (غير آمن) ([Project Name] (unsafe))
    • انقر فوق سماح (Allow)

  4. تحقق من جدول بيانات Google الخاص بك - يجب أن تظهر البيانات الآن

:bulb: إذا واجهت أخطاء، فانقر فوق عرض (View) ← السجلات (Logs) في محرر Apps Script للاطلاع على رسائل الخطأ التفصيلية.

الخطوة 4: إعداد المزامنة التلقائية (اختياري)

لتشغيل المزامنة تلقائيًا وفقًا لجدول زمني:

  1. في محرر Apps Script، انقر فوق أيقونة المشغلات (Triggers) (:one_o_clock:) في الشريط الجانبي الأيسر

  2. انقر فوق + إضافة مشغل (+ Add Trigger) (أسفل اليمين)

  3. قم بتهيئة المشغل:

    • الدالة المراد تشغيلها (Function to run): syncDiscourseData
    • مصدر الحدث (Event source): مدفوع بالوقت (Time-driven)
    • نوع المشغل المستند إلى الوقت (Type of time based trigger): اختر التكرار المفضل لديك (على سبيل المثال، مؤقت يومي، مؤقت ساعي)
    • الوقت من اليوم/الفاصل الزمني (Time of day/interval): حدد متى تريد تشغيل المزامنة

  4. انقر فوق حفظ (Save)

التعامل مع الاستعلامات ذات المعلمات

إذا كان استعلام مستكشف البيانات الخاص بك يستخدم معلمات، فقم بإضافتها إلى حمولة الطلب (request payload):

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: يجب أن تكون جميع قيم المعلمات سلاسل نصية (strings)، حتى بالنسبة للمعلمات الرقمية.

لمزيد من التفاصيل حول تشغيل الاستعلامات ذات المعلمات، راجع: تشغيل استعلامات مستكشف البيانات باستخدام واجهة برمجة تطبيقات Discourse

التعامل مع مجموعات البيانات الكبيرة

تقتصر عمليات التصدير بتنسيق CSV افتراضيًا على 10000 صف كحد أقصى. بالنسبة لمجموعات البيانات الأكبر، قم بتنفيذ التصفح (pagination) في الاستعلام الخاص بك باستخدام معلمات LIMIT و OFFSET:

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

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

ثم قم بتعديل البرنامج النصي الخاص بك للتكرار عبر الصفحات حتى لا يتم إرجاع المزيد من النتائج.

استكشاف الأخطاء وإصلاحها

المشكلة الحل
خطأ 403 Forbidden (محظور) تحقق من أن مفتاح API الخاص بك لديه نطاق “تشغيل الاستعلامات” وأن اسم المستخدم لديه وصول إداري
خطأ 404 Not Found (غير موجود) تحقق من أن معرّف الاستعلام صحيح وأن الاستعلام موجود
نتائج فارغة تحقق من أن الاستعلام يُرجع بيانات عند تشغيله مباشرة في مستكشف البيانات
أخطاء تحديد المعدل (Rate limiting errors) يحد Discourse من طلبات API الخاصة بمستكشف البيانات إلى 2 كل 10 ثوانٍ افتراضيًا. أضف تأخيرات بين الطلبات إذا لزم الأمر

موارد إضافية

إعجابَين (2)