يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات Discourse لإنشاء الاستعلامات وتشغيلها وإدارتها باستخدام المكون الإضافي Data Explorer.
مستوى المستخدم المطلوب: مسؤول
يمكن تشغيل أي إجراء يمكن تنفيذه من خلال واجهة مستخدم Discourse تقريبًا باستخدام واجهة برمجة تطبيقات Discourse.
توفر هذه الوثيقة نظرة عامة شاملة لاستخدام واجهة برمجة التطبيقات بالتحديد بالاقتران مع المكون الإضافي Data Explorer.
للحصول على نظرة عامة عامة حول كيفية العثور على طلب واجهة برمجة التطبيقات الصحيح لإجراء ما، راجع: Reverse engineer the Discourse API .
تشغيل استعلام Data Explorer
لتشغيل استعلام Data Explorer عبر واجهة برمجة التطبيقات، قم بإجراء طلب POST إلى /admin/plugins/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/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 من النتائج بـ 1000 صف افتراضيًا. للتنقل عبر مجموعات البيانات الأكبر، يمكنك استخدام الاستعلام المثال أدناه:
--[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/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/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"
مصادقة واجهة برمجة التطبيقات
يمكن العثور على تفاصيل حول إنشاء مفتاح واجهة برمجة تطبيقات للطلبات هنا: Create and configure an API key .
إذا كان سيتم استخدام مفتاح واجهة برمجة التطبيقات فقط لتشغيل استعلامات Data Explorer، يمكنك تحديد “Granular” من القائمة المنسدلة Scope، ثم تحديد نطاق “run queries”.
الأسئلة الشائعة
هل هناك أي نقطة نهاية لواجهة برمجة التطبيقات يمكنني استخدامها للحصول على قائمة التقارير وأرقام المعرّفات؟ أريد إنشاء قائمة منسدلة تحتوي على القائمة؟
نعم، يمكنك إجراء طلب GET مصادق عليه إلى /admin/plugins/explorer/queries.json للحصول على قائمة بجميع الاستعلامات على الموقع.
هل من الممكن إنشاء استعلامات عبر واجهة برمجة التطبيقات؟
نعم. توجد وثائق حول كيفية القيام بذلك على Create a Data Explorer query using the API
هل من الممكن إرسال معلمات مع طلب النشر؟
نعم، قم بتضمين معلمات SQL باستخدام الخيار -F، كما هو موضح في الأمثلة.
هل يتم دعم تصدير CSV للاستعلامات بواسطة واجهة برمجة التطبيقات؟
على الرغم من أن إخراج JSON هو المعيار، يمكنك تحويل النتائج يدويًا إلى CSV. لم يعد تصدير CSV الأصلي مدعومًا.