إذا كان لديك موقع ويب أو تطبيق قائم وترغب في تشجيع النقاش في منتدى Discourse الخاص بك، فقد يكون من المفيد عرض إشعارات Discourse داخل تطبيقك. سيوضح لك هذا الدليل كيفية استخدام واجهة برمجة تطبيقات Discourse (Discourse API) لجلب الإشعارات لمستخدم معين وكيفية وضع علامة عليها كـ “مقروءة”.
الطريقة الموصى بها لاستخدام واجهة برمجة التطبيقات هي أن يقوم تطبيقك بإجراء طلبات من جانب الخادم (back-end) إلى Discourse ثم تمرير تلك البيانات إلى طبقة الواجهة الأمامية/العرض (front-end/presentation layer) في تطبيقك.
تحقق من وثائق واجهة برمجة التطبيقات للحصول على معلومات حول كيفية استخدام واجهة برمجة تطبيقات Discourse.
جلب الإشعارات لمستخدم
للحصول على الإشعارات عبر واجهة برمجة التطبيقات، يمكنك إجراء طلب GET موثَّق (authenticated) إلى نقطة النهاية /notifications. يمكنك تحديد اسم المستخدم الذي تجلب الإشعارات له إما في ترويسة Api-Username أو كمعامل استعلام (query parameter): /notifications?username=<username>.
معاملات الاستعلام الاختيارية
| المعامل | الوصف |
|---|---|
username |
اسم المستخدم الذي يتم جلب الإشعارات له |
filter |
التصفية حسب حالة القراءة: read أو unread |
filter_by_types |
قائمة مفصولة بفواصل لأسماء أنواع الإشعارات للتصفية حسبها (مثال: mentioned,replied) |
offset |
الإزاحة (Offset) لصفحات النتائج |
limit |
عدد الإشعارات المطلوب إرجاعها (الحد الأقصى 60) |
مثال على الطلب
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
سيُرجع هذا استجابة JSON التالية:
{
"notifications": [
{
"id": 3,
"user_id": 5,
"external_id": null,
"notification_type": 12,
"read": true,
"high_priority": false,
"created_at": "2019-06-17T20:26:05.670Z",
"post_number": null,
"topic_id": null,
"slug": null,
"data": {
"badge_id": 41,
"badge_name": "First Emoji",
"badge_slug": "first-emoji",
"badge_title": false,
"username": "blake"
}
},
{
"id": 2,
"user_id": 5,
"external_id": null,
"notification_type": 6,
"read": true,
"high_priority": true,
"created_at": "2019-06-17T20:26:04.305Z",
"post_number": 1,
"topic_id": 10,
"fancy_title": "Greetings!",
"slug": "greetings",
"data": {
"topic_title": "Greetings!",
"original_post_id": 14,
"original_post_type": 1,
"original_username": "discobot",
"revision_number": null,
"display_username": "discobot"
}
}
],
"total_rows_notifications": 2,
"seen_notification_id": 3,
"load_more_notifications": "/notifications?offset=60&username=blake"
}
يُرجع هذا مصفوفة إشعارات. إذا كنت مهتمًا فقط بعرض الإشعارات غير المقروءة، يمكنك تمرير معامل الاستعلام filter=unread لكي يقوم الخادم بإرجاع الإشعارات غير المقروءة فقط. على سبيل المثال:
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson&filter=unread" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
يمكنك زيارة هذه الصفحة للاطلاع على قائمة بأنواع الإشعارات. على سبيل المثال، النوع 12 من الإشعارات يطابق “granted_badge” (تم منح شارة).
وضع علامة على الإشعارات كمقروءة
الآن بعد أن قمت بجلب إشعارات المستخدم، يمكنك وضع علامة عليها كمقروءة عن طريق إرسال طلب PUT إلى /notifications/mark-read مع تضمين id الإشعار في نص الطلب وتحديد اسم المستخدم في ترويسة الطلب.
مثال على الطلب
curl -X PUT "http://localhost:8080/notifications/mark-read" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: blake.erickson" \
-F "id=4"
يمكنك أيضًا حذف معرف الإشعار وسيؤدي ذلك إلى وضع علامة على جميع الإشعارات لهذا المستخدم كمقروءة.
سيُرجع هذا استجابة JSON بسيطة “OK”:
{
"success": "OK"
}