قدم طلبات إلى واجهة برمجة تطبيقات Discourse باستخدام Zapier

[Discourse]

يمكن أتمتة الطلبات المرسلة إلى واجهة برمجة تطبيقات Discourse من خلال إنشاء Zap يستخدم Webhook الخاص بـ Zapier كخطوة إجراء. ستصف هذه الموضوع كيفية تنفيذ الطلبات للإجراءات التالية:

• إضافة مستخدم إلى مجموعة
• منح شارة مخصصة

لمعرفة كيفية تنفيذ أنواع أخرى من طلبات واجهة برمجة التطبيقات باستخدام Zapier، اقرأ الموضوع ثم ابحث في وثائق واجهة برمجة تطبيقات Discourse عن الإجراء الذي ترغب في تنفيذه. يمكنك أيضًا معرفة كيفية إنشاء طلب واجهة برمجة تطبيقات لإجراء معين من خلال قراءة Reverse engineer the Discourse API.

إعداد خطوة الزناد (Trigger)

يجب أن يحتوي كل Zap على خطوة زناد (Trigger) وخطوة إجراء (Action). يُستخدم الزناد لنقل البيانات من تطبيق ما إلى خطوة الإجراء في Zap. في بعض الحالات، يمكن استخدام الزناد أيضًا لمنع Zap من إكمال خطوة الإجراء ما لم تستوفِ بياناته شروطًا معينة.

لإعداد خطوة الإجراء، انتقل إلى لوحة تحكم Zapier واضغط على زر “إنشاء Zap” (Make a Zap). ستفتح نافذة بحث تطلب منك اختيار تطبيق الزناد.

بالنسبة للأمثلة في هذا الموضوع، سأستخدم حدث “مستخدم جديد” في WordPress كخطوة إجراء. والسبب في ذلك هو سهولة إعداده لاختبار مكالمات واجهة برمجة التطبيقات.

تتيح لك عقدة “اختبار هذه الخطوة” (Test This Step) في خطوة الزناد اختيار عينة من البيانات من تطبيق الزناد التي سيتم تمريرها إلى خطوة الإجراء في Zap. ستكون هذه البيانات مفيدة لإعداد خطوة الإجراء.

إضافة خطوة اختيارية لاسترجاع التفاصيل من Discourse

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

لحصول على تفاصيل مستخدم في Discourse من عنوان بريده الإلكتروني، أضف خطوة إجراء إلى Zap الخاص بك. اختر “GET” من قائمة إجراءات Webhook.

في خطوة تحرير قالب Webhook، أدخل الرابط الأساسي لموقع Discourse الخاص بك، متبوعًا بـ /admin/users/list/all.json في قسم الرابط (URL). على سبيل المثال، الرابط الأساسي لموقعي هو https://demo.scossar.com، لذا أدخلت https://demo.scossar.com/admin/users/list/all.json في حقل الرابط.

في قسم معلمات سلسلة الاستعلام (Query String Params)، أدخل “email” كمفتاح، ثم انقر على أيقونة “إدراج حقل” لفتح القائمة المنسدلة. اختر القيمة التي تم تمريرها بواسطة خطوة الزناد الخاصة بك والتي تحتوي على عنوان البريد الإلكتروني للمستخدم.

مصادقة الطلب

قم بالتمرير لأسفل النموذج إلى قسم الرؤوس (Headers). يُستخدم هذا القسم لمصادقة الطلب. يتطلب ثلاثة أزواج من المفاتيح/القيم:

• Api-Username : اسم مستخدم لمدير موقعك. في معظم الحالات، سيكون مستخدم ‘system’ خيارًا جيدًا لهذا الغرض.
• Api-Key : مفتاح API المرتبط باسم المستخدم الذي استخدمته في الزوج الأول من المفاتيح/القيم.
• Content-Type : multipart/form-data

يجب أن يبدو قسم الرؤوس المكتمل مشابهًا لهذا، ولكن بمفتاح API الخاص بمستخدمك:

انقر على زر “متابعة” (Continue) لعرض البيانات المسترجعة من Discourse لهذا الطلب.

إضافة خطوة الإجراء النهائية

بمجرد إعداد الزناد والخطوة الاختيارية لاسترجاع البيانات من Discourse، انقر على رابط “إضافة خطوة” (Add a Step) واختر “Webhooks by Zapier” من قائمة الإجراءات. سيُطلب منك بعد ذلك اختيار طريقة الطلب التي ترغب في استخدامها في طلب واجهة برمجة التطبيقات الخاص بك إلى Discourse.

إليك أنواع الطلبات المطلوبة للأمثلة المستخدمة في هذا الموضوع:

• إضافة مستخدم إلى مجموعة: PUT
• منح شارة مخصصة: POST

لإعداد طلبات واجهة برمجة التطبيقات غير المذكورة في أمثلة هذا الموضوع، اطلع على توثيق واجهة برمجة تطبيقات Discourse لمعرفة ما إذا كان هناك مثال للطلب الذي ترغب في إجراؤه. إذا لم تجد مثالًا هناك، اقرأ كيفية عكس هندسة واجهة برمجة تطبيقات Discourse لتعلم كيفية العثور على الرابط وطريقة الطلب للإجراء الذي ترغب في تنفيذه. بمجرد العثور على طريقة الطلب، اخترها من قائمة الإجراءات.

ملاحظة: إذا كان طلبك يستخدم طريقة DELETE، فاختر “طلب مخصص” (Custom Request) من قائمة الإجراءات.

إعداد خطوة الإجراء النهائية

يمكن إعداد قسم الرؤوس (Headers) للإجراء بنفس الطريقة لجميع طلبات واجهة برمجة التطبيقات. راجع قسم “مصادقة الطلب” في هذا الموضوع للحصول على التفاصيل. إذا أضفت الخطوة الاختيارية لاسترجاع التفاصيل من Discourse، فيمكنك إعداد قسم الرؤوس في الإجراء النهائي بنفس الطريقة تمامًا التي فعلتها في تلك الخطوة.

بمجرد إضافة أزواج المفاتيح/القيم للرؤوس، ستحتاج إلى ملء حقلي الرابط (URL) والبيانات (Data) في النموذج لطلب واجهة برمجة التطبيقات الخاص بك.

إضافة مستخدم إلى مجموعة

لإضافة مستخدم إلى مجموعة، يتم إجراء طلب PUT إلى /groups/<group_id>/members.json. أسهل طريقة للعثور على معرف المجموعة هي زيارة صفحة المجموعة عبر واجهة مستخدم Discourse، ثم إدخال .json في الرابط الموجود في شريط عناوين المتصفح. على سبيل المثال، يحتوي موقعي على مجموعة “دعم” (support) في https://demo.scossar.com/g/support. بالانتقال إلى https://demo.scossar.com/g/support.json، يمكنني رؤية أن معرف المجموعة هو 41. الرابط الأساسي لموقعي هو https://demo.scossar.com. يتم ضبط الرابط في خطوة الإجراء النهائية لإضافة المستخدمين إلى مجموعة على https://demo.scossar.com/groups/41/members.json.

يتطلب طلب إضافة المستخدمين إلى مجموعة معلمة واحدة - وهي قائمة مفصولة بفواصل بأسماء المستخدمين. في قسم البيانات (Data) في النموذج، أدخل “usernames” كمفتاح. ثم انقر على أيقونة “إدراج حقل” للبحث عن خاصية اسم المستخدم التي تم تمريرها إما من الزناد أو من خطوة الإجراء الاختيارية GET.

في حالتي، أريد اسم المستخدم الذي تم استرجاعه بواسطة خطوة GET، لذا أقوم بتوسيع قائمة “GET” وأختار “Username” من القائمة المنسدلة.

يمكن ترك جميع الأقسام الأخرى في النموذج بقيمتها الافتراضية.

انقر على زر “متابعة” (Continue) ثم اختبر خطوتك. إذا كان المستخدم الذي تم تمريره عبر الخطوات السابقة موجودًا على موقع Discourse الخاص بك، ولم يكن عضوًا بالفعل في المجموعة التي اخترتها، فيجب إضافته إلى المجموعة عند اختبار الخطوة.

إذا عمل كل شيء كما هو متوقع، فعّل Zap الخاص بك.

منح شارة مخصصة

لمنح شارة مخصصة لمستخدم، يتم إجراء طلب POST إلى الرابط الأساسي لموقعك + /user_badges. لموقعي، الرابط الخاص بمنح الشارات هو https://demo.scossar.com/user_badges. يبدو حقل الرابط المكتمل في Zapier كما يلي:

يتطلب قسم البيانات (Data) في النموذج زوجين من المفاتيح/القيم. أضف مفتاحًا “username” واضبطه على الحقل الذي يعيد اسم المستخدم. أضف مفتاحًا “badge_id” واضبطه على معرف الشارة التي ترغب في منحها. يمكنك العثور على معرف الشارة بالانتقال إلى صفحة Admin / Badges واختيار الشارة من القائمة الجانبية اليسرى. سترى معرف الشارة كآخر قيمة في الرابط الموجود في شريط عناوين المتصفح.

الشارة التي أقوم بمنحها لها معرف 105، لذا يبدو قسم البيانات المكتمل كما يلي:

تأكد من إعداد قسم الرؤوس (Headers) في النموذج، ثم انقر على “متابعة”. بعد ذلك، انقر على زر “إرسال اختبار” (Send Test) لاختبار Zap الخاص بك. يجب منح الشارة للمستخدم الذي تم تمريره عبر الخطوات السابقة.

إذا كان كل شيء يعمل بشكل صحيح، فعّل Zap.

[aj_silvers]

هل يمكن استخدام هذه العملية لإنشاء حساب تلقائيًا لمستخدم جديد وإضافته إلى مجموعة محددة في ديسكورش؟

الحالة الاستخدامية هنا هي أن شخصًا ما يشتري منتجًا تدريبيًا، وأرغب في إضافته تلقائيًا إلى منتدى ديسكورش الفرعي ذي الصلة لذلك المنتج.

يمكنني جلب بيانات العميل الجديد إلى Zapier، لكن عملية Zap العادية الخاصة بديسكورش لا تتضمن إمكانيات إنشاء الحسابات. فقط أتساءل عما إذا كان بإمكاني القيام بذلك عبر واجهة برمجة التطبيقات (API) ورابط الويب هوك كما أوضحت في هذا المثال.

شكرًا لك!

[simon]

@aj_silvers

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

الأسهل هو إرسال دعوة بالبريد الإلكتروني للشخص بعد إتمام عملية الشراء. يمكنك إعداد الدعوة بحيث يتم إضافة المستخدم تلقائيًا إلى مجموعة ديسكوس عند قبوله الدعوة. راجع التفاصيل في Automate sending Discourse invite emails with Zapier.

إذا لم يكن إرسال الدعوات خيارًا متاحًا لك، فيمكن استخدام ويب هوك من زابير لإنشاء مستخدم في ديسكوس. توفر Discourse API Docs تفاصيل حول الطلب اللازم لإنشاء مستخدم.

[aj_silvers]

شكرًا لك @simon، سأجرب دعوة البريد الإلكتروني. لا شك أن بعض الأشخاص لن يستلموها/يجدوها/يفتحوها، لكنها بالتأكيد الخيار الأسهل.

أقدر أيضًا استجابتك السريعة!

[pfaffman (Jay Pfaffman)]

غالبًا ما يكون من الأسهل أن يقوم من يبيع المنتج بإجراء مكالمات واجهة برمجة التطبيقات الخاصة بالمنتدى مباشرةً.

[Nacho_Caballero]

هل هناك سبب يجعل هذا يعمل معي عند استخدامه في Zapier، بينما أحصل على استجابة فارغة عند محاولة إجراء طلب fetch خاص بي؟

أنا أستخدم ObservableHQ، لكن الفكرة نفسها. ألا يجب أن يعمل هذا؟

fetch("https://mycommunity.com/g.json", {
  headers: {
    "Content-Type": "multipart/form-data",
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
  method: "GET",
  mode: "no-cors"
})

[simon]

هل يمكنك جعل أي طلبات API لـ Discourse تعمل مع الاستدعاءات بهذا التنسيق باستخدام ObservableHQ؟ يبدو أن هناك خطأ ما في تنسيق الطلب.

يمكنك أيضًا التحقق من الطلبات عن طريق إجراء استدعاءات curl من طرفك، أو باستخدام Postman.

[Nacho_Caballero]

حسناً، لقد اكتشفت ما كنت بحاجة لفعله:

1. قم بتثبيت cors-anywhere محلياً وشغّل الخادم.
2. عدّل الطلب ليشمل وكيل العكس قبل نقطة نهاية واجهة برمجة التطبيقات، ثم استدعِ الدالة json في كائن استجابة Fetch:

await (fetch("http://localhost:8080/mycommunity.com/g.json", {
  headers: {
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
})).json()

[markersocial]

سأترك هذا هنا، قد يستحق الاطلاع عليه:

n8n.io - AI workflow automation platform

GitHub - n8n-io/n8n: Fair-code workflow automation platform with native...

[Bernstein (Carey Bernstein)]

@سيمون، منشور:1، موضوع:122126

لإصدار شارة مخصصة لمستخدم، يتم إرسال طلب POST إلى الرابط الأساسي لموقعك الإلكتروني + /user_badges.

مرحبًا @سيمون، شكرًا لك على هذا الدليل. أقوم بإعداده في Zapier، لكن موقعي لا يحتوي على هذا الرابط لإصدار الشارات.

أتساءل، هل هذا ليس رابطًا قياسيًا لجميع تركيبات Discourse، أم أن الرابط قد تغير في تحديث حديث؟

[simon]

@Bernstein، منشور:10، موضوع:122126

منتدىي لا يحتوي على هذا الرابط لمنح الشارات.

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

[Bernstein (Carey Bernstein)]

لم يكن مفاجئاً، بل كان خطأي أنا.