يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات Discourse لإنشاء الاستعلامات وتشغيلها وإدارتها باستخدام المكوّن الإضافي Data Explorer.
مستوى المستخدم المطلوب: مسؤول (Administrator)
يمكن تشغيل أي إجراء يمكن إجراؤه عبر واجهة مستخدم Discourse تقريبًا باستخدام واجهة برمجة تطبيقات Discourse.
توفر هذه الوثيقة نظرة عامة شاملة لاستخدام واجهة برمجة التطبيقات بالاشتراك تحديدًا مع المكوّن الإضافي Data Explorer.
للحصول على نظرة عامة حول كيفية العثور على طلب واجهة برمجة التطبيقات الصحيح لإجراء ما، راجع: Reverse engineer the Discourse API .
تشغيل استعلام Data Explorer
لتشغيل استعلام Data Explorer عبر واجهة برمجة التطبيقات، قم بإجراء طلب POST إلى /admin/plugins/discourse-data-explorer/queries/<query-id>/run. يمكنك العثور على معرّف الاستعلام عن طريق زيارته عبر موقع Discourse الخاص بك والتحقق من المعامل id في شريط العنوان.
أدناه مثال على استعلام بمعرّف 20 يُرجع المواضيع حسب المشاهدات في تاريخ محدد:
--[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
يمكن تشغيل هذا الاستعلام من الطرفية باستخدام:
curl -X POST "https://your-site-url/admin/plugins/discourse-data-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"}'
لاحظ أنك ستحتاج إلى استبدال <api-key> و <your-site-url> بمفتاح واجهة برمجة التطبيقات والنطاق الخاصين بك.
التعامل مع مجموعات البيانات الكبيرة
يحد المكوّن الإضافي Data Explorer من نتائج JSON بـ 1000 صف بشكل افتراضي (يتم التحكم فيه بواسطة إعداد الموقع المخفي data_explorer_query_result_limit). يمكنك تجاوز هذا لكل طلب عن طريق تمرير المعامل limit، بحد أقصى 10,000:
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F "limit=5000"
بالنسبة لمجموعات البيانات التي يزيد حجمها عن 10,000 صف، ستحتاج إلى التصفح على مستوى SQL. يمكنك استخدام مثال الاستعلام أدناه:
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
لجلب النتائج صفحة بصفحة، قم بزيادة المعامل page في الطلب:
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}'
توقف عندما يكون result_count صفرًا.
للحصول على معلومات إضافية حول التعامل مع مجموعات البيانات الكبيرة، راجع: Result Limits and Exporting Queries
إزالة بيانات relations من النتائج
عندما يتم تشغيل استعلامات Data Explorer من خلال واجهة المستخدم، تتم إضافة كائن relations إلى النتائج. تُستخدم هذه البيانات لعرض المستخدم في نتائج واجهة المستخدم، ولكن من غير المرجح أن تحتاج إليها عند تشغيل الاستعلامات عبر واجهة برمجة التطبيقات.
لإزالة هذه البيانات من النتائج، أضف المعامل download=true مع طلبك:
curl -X POST "https://your-site-url/admin/plugins/discourse-data-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"
مصادقة واجهة برمجة التطبيقات (API authentication)
يمكن العثور على تفاصيل حول إنشاء مفتاح واجهة برمجة تطبيقات للطلبات هنا: Create and configure an API key .
إذا كان سيتم استخدام مفتاح واجهة برمجة التطبيقات فقط لتشغيل استعلامات Data Explorer، يمكنك اختيار “Granular” من القائمة المنسدلة “Scope” (النطاق)، ثم تحديد نطاق “run queries” (تشغيل الاستعلامات).
الأسئلة الشائعة (FAQs)
هل هناك أي نقطة نهاية لواجهة برمجة التطبيقات يمكنني استخدامها للحصول على قائمة التقارير وأرقام المعرّفات؟ أريد إنشاء قائمة منسدلة تحتوي على القائمة؟
نعم، يمكنك إجراء طلب GET مصادق عليه إلى /admin/plugins/discourse-data-explorer/queries.json للحصول على قائمة بجميع الاستعلامات على الموقع.
هل من الممكن إنشاء استعلامات عبر واجهة برمجة التطبيقات؟
نعم. الوثائق حول كيفية القيام بذلك موجودة في Create a Data Explorer query using the API
هل من الممكن إرسال معلمات مع طلب النشر (post request)؟
نعم، قم بتضمين معلمات SQL باستخدام الخيار -F، كما هو موضح في الأمثلة.
هل تصدير CSV للاستعلامات مدعوم من واجهة برمجة التطبيقات؟
نعم. أضف .csv إلى عنوان URL لنقطة نهاية التشغيل للحصول على النتائج بتنسيق CSV:
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run.csv" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
تُرجع استجابات CSV افتراضيًا ما يصل إلى 10,000 صف. يمكنك تمرير المعامل limit لتقليل هذا العدد.