ويب هوكس¶

تحذير

من المستحسن بشدة التشاور مع مطور أو مهندس حلول أو دور تقني آخر عند اتخاذ قرار استخدام الـwebhooks وطوال عملية التنفيذ. إذا لم يتم تكوينها بشكل صحيح، قد تعطل الـwebhooks قاعدة بيانات Odoo ويمكن أن تستغرق وقتًا للتراجع.

تسمح لك خطافات الويب، التي يمكن إنشاؤها في الاستوديو، بأتمتة إجراء في قاعدة بيانات Odoo الخاصة بك عندما يحدث حدث معين في نظام خارجي آخر.

عمليًا، يعمل هذا على النحو التالي: عندما يحدث الحدث في النظام الخارجي، يتم إرسال ملف بيانات ("الحمولة") إلى عنوان URL لخطاف الويب في Odoo عبر طلب واجهة برمجة تطبيقات POST، ويتم تنفيذ إجراء محدد مسبقًا في قاعدة بيانات Odoo الخاصة بك.

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

لا يتطلب إعداد خطاف ويب في Odoo أي برمجة عند ربط قاعدتي بيانات Odoo، لكن اختبار خطاف الويب يتطلب أداة خارجية. قد يتطلب تخصيص السجلات أو الإجراءات المستهدفة مهارات برمجية.

ملاحظة

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

إنشاء خطاف ويب في Odoo¶

مهم

قبل تنفيذ webhook في قاعدة بيانات حية، قم بتكوينه واختباره باستخدام قاعدة بيانات مكررة للتأكد من أن webhook يعمل كما هو مقصود.

نصيحة

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

للعثور على الاسم التقني للنموذج، مع تنشيط وضع المطور، مرر مؤشر الماوس فوق اسم النموذج ثم انقر فوق (رابط داخلي). يمكن العثور على الاسم التقني في حقل النموذج. على سبيل المثال، يستخدم خطاف ويب أمر البيع نموذج أمر البيع، ولكن يتم استخدام الاسم التقني sale.order في الحمولة.

لإنشاء خطاف ويب في الاستوديو، اتبع الخطوات التالية:

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

تحذير
عنوان URL سري ويجب التعامل معه بحذر. مشاركته عبر الإنترنت أو دون احتياط يمكن أن يوفر وصولاً غير مقصود إلى قاعدة بيانات Odoo. إذا تم تحديث عنوان URL بعد التطبيق الأولي، فتأكد من تحديثه في النظام الخارجي.
إذا رغبت في ذلك، قم بتفعيل تسجيل المكالمات لتتبع سجل طلبات واجهة برمجة التطبيقات المقدمة إلى عنوان URL لخطاف الويب، على سبيل المثال، لأغراض استكشاف الأخطاء وإصلاحها.
إذا لم يكن النظام الذي يرسل خطاف الويب هو Odoo، فاضبط كود السجل المستهدف للبحث عن سجل JSON المضمن في الحمولة عند تقديم طلب واجهة برمجة التطبيقات إلى عنوان URL لخطاف الويب. إذا كان النظام الذي يرسل خطاف الويب هو قاعدة بيانات Odoo، فتأكد من ظهور id و model في الحمولة.

إذا تم استخدام خطاف الويب لإنشاء سجلات في قاعدة بيانات Odoo، استخدم model.browse(i) أو model.search(i) بدلاً من تنسيق السجل المستهدف الافتراضي.
انقر فوق إضافة إجراء في علامة التبويب الإجراءات المطلوبة لتحديد الإجراءات المراد تنفيذها.
قبل تطبيق خطاف الويب في النظام الخارجي، اختبره للتأكد من أنه يعمل على النحو المنشود.

نصيحة

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

اختبار webhook¶

يتطلب اختبار webhook حمولة اختبار وأداة أو نظام خارجي، مثل Postman، لإرسال الحمولة عبر طلب واجهة برمجة تطبيقات POST. يعرض هذا القسم خطوات اختبار webhook في Postman.

نصيحة

راجع قسم حالات استخدام webhook للحصول على شروحات تفصيلية خطوة بخطوة حول كيفية اختبار webhooks باستخدام حمولات الاختبار.
للحصول على مساعدة محددة حول اختبار webhook مع Postman، اتصل بفريق الدعم الخاص بهم.

في Postman، أنشئ طلب HTTP جديد واضبط طريقته على POST.
انسخ عنوان URL الخاص بـ webhook من قاعدة بيانات Odoo الخاصة بك باستخدام أيقونة (رابط) والصقه في حقل عنوان URL في Postman.
انقر على علامة التبويب Body وحدد raw.
اضبط نوع الملف على JSON، ثم انسخ الكود من حمولة الاختبار والصقه في محرر الكود.
Click Send.

في عارض Response في أسفل الشاشة في Postman، تشير التفاصيل، بما في ذلك كود استجابة HTTP، إلى ما إذا كان webhook يعمل بشكل صحيح أم لا.

تشير رسالة 200 OK أو status: ok إلى أن webhook يعمل بشكل صحيح على جانب Odoo. من هنا، يمكن البدء في التنفيذ مع النظام الآخر لإرسال طلبات واجهة برمجة التطبيقات تلقائيًا إلى عنوان URL الخاص بـ webhook في Odoo.
إذا تم إرجاع أي استجابة أخرى، فإن الرقم المرتبط بها يساعد في تحديد المشكلة. على سبيل المثال، تعني رسالة 500 Internal Server Error أن Odoo لم يتمكن من تفسير المكالمة بشكل صحيح. في هذه الحالة، تأكد من أن الحقول الموجودة في ملف JSON مُربوطة بشكل صحيح في إعدادات webhook وفي النظام الذي يرسل مكالمة الاختبار.

نصيحة

يوفر تشغيل تسجيل المكالمات في إعدادات webhook في Odoo سجلات الأخطاء إذا لم يكن webhook يعمل كما هو مقصود.

تنفيذ webhook في نظام خارجي¶

عندما يتم إنشاء webhook بنجاح في Odoo واختباره، قم بتنفيذه في النظام الذي يرسل البيانات إلى قاعدة بيانات Odoo، مع التأكد من إرسال طلبات واجهة برمجة التطبيقات POST إلى عنوان URL الخاص بـ webhook.

حالات استخدام webhook¶

فيما يلي مثالان على كيفية استخدام webhooks في Odoo. يتم توفير حمولة اختبار لكل مثال، ويمكن العثور عليها في القسم الخاص باختبار webhook. يُستخدم Postman لإرسال حمولة الاختبار.

تحديث عملة أمر البيع¶

يقوم webhook هذا بتحديث أمر بيع في تطبيق المبيعات إلى USD عندما يرسل النظام الخارجي طلب واجهة برمجة تطبيقات POST إلى عنوان URL الخاص بـ webhook يتضمن رقم أمر البيع هذا (والذي يتم تحديده بواسطة سجل id الخاص بالحمولة).

قد يكون هذا مفيدًا للشركات التابعة خارج الولايات المتحدة مع شركة أم موجودة داخل الولايات المتحدة أو أثناء عمليات الدمج عند دمج البيانات في قاعدة بيانات Odoo واحدة.

إنشاء webhook¶

لإنشاء webhook هذا، تابع كما يلي:

افتح تطبيق المبيعات، ثم افتح الاستوديو وانقر على Webhooks. نموذج أمر البيع محدد افتراضيًا.
انقر على جديد. المشغل معين على On webhook افتراضيًا.
اضبط السجل المستهدف على model.env[payload.get('model')].browse(int(payload.get('id')))، حيث:
- payload.get('model') يسترجع القيمة المرتبطة بمفتاح model في الحمولة، أي sale.order، وهو الاسم التقني لنموذج أمر البيع.
- payload.get('id') يسترجع القيمة المرتبطة بمفتاح id في الحمولة، أي رقم أمر البيع المستهدف في قاعدة بيانات Odoo الخاصة بك مع إزالة S والأصفار البادئة.
- int يحول المعرف المسترجع إلى عدد صحيح لأن الأسلوب browse() لا يمكن استخدامه إلا مع عدد صحيح.
انقر على إضافة إجراء.
في قسم النوع، انقر على تحديث السجل.
في قسم تفاصيل الإجراء، حدد تحديث، واختر الحقل العملة، وحدد USD.
انقر على حفظ وإغلاق.

اختبار webhook¶

لاختبار webhook هذا، تابع كما يلي:

مع فتح Postman، أنشئ طلب HTTP جديد واضبط طريقته على POST.
انسخ عنوان URL الخاص بـ webhook في Odoo باستخدام أيقونة (رابط) والصقه في حقل URL في Postman.
انقر على علامة التبويب Body وحدد raw.
اضبط نوع الملف على JSON، ثم انسخ هذا الكود، أي البيانات، والصقه في محرر الكود:
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
في قاعدة بيانات Odoo الخاصة بك، اختر أمر بيع لاختبار webhook عليه. في الكود الملصق، استبدل SALES ORDER NUMBER برقم أمر البيع بدون S أو أي أصفار قبل الرقم. على سبيل المثال، أمر بيع برقم S00007 يجب إدخاله كـ 7 في Postman.
Click Send.
راجع عارض الاستجابة في Postman لتحديد ما إذا كان webhook يعمل بشكل صحيح أم لا. إذا تم إرجاع رسالة غير 200 OK أو status: ok، فإن الرقم المرتبط بالرسالة يساعد في تحديد المشكلة.

إنشاء عقد جديد¶

يستخدم webhook هذا كودًا مخصصًا لإنشاء جهة اتصال جديدة في قاعدة بيانات Odoo عندما يرسل النظام الخارجي طلب API من نوع POST إلى عنوان URL الخاص بـ webhook يتضمن معلومات جهة الاتصال. قد يكون هذا مفيدًا لإنشاء موردين أو عملاء جدد تلقائيًا.

إنشاء webhook¶

لإنشاء webhook هذا، تابع كما يلي:

افتح تطبيق جهات الاتصال، ثم افتح الاستوديو وانقر على Webhooks. نموذج جهة الاتصال محدد افتراضيًا.
انقر على جديد. المشغل معين على On webhook افتراضيًا.
اضبط السجل المستهدف على model.browse([2]). هذا في الأساس عنصر نائب حيث أن الكود في الإجراء الآلي يخبر webhook بما يجب استرجاعه من البيانات وفي أي نموذج يجب إنشاء السجل.
انقر على إضافة إجراء.
في قسم النوع، انقر فوق تنفيذ الكود.

انسخ هذا الكود والصقه في محرر الكود في علامة التبويب الكود في قسم تفاصيل الإجراء:

# variables to retrieve and hold data from the payload
contact_name = payload.get('name')
contact_email = payload.get('email')
contact_phone = payload.get('phone')

# a Python function to turn the variables into a contact in Odoo
if contact_name and contact_email:
    new_partner = env['res.partner'].create({
        'name': contact_name,
        'email': contact_email,
        'phone': contact_phone,
        'company_type':'person',
        'customer_rank': 1,
    })
# an error message for missing required data in the payload
else:
    raise ValueError("Missing required fields: 'name' and 'email'")

انقر على حفظ وإغلاق.

اختبار webhook¶

لاختبار webhook هذا، تابع كما يلي:

في Postman، أنشئ طلب HTTP جديد واضبط طريقته إلى POST.
انسخ عنوان URL الخاص بـ webhook في Odoo باستخدام أيقونة (رابط) والصقه في حقل URL في Postman.
انقر على علامة التبويب Body وحدد raw.
اضبط نوع الملف على JSON، ثم انسخ هذا الكود، أي البيانات، والصقه في محرر الكود:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
في الكود الملصق، استبدل CONTACT NAME و CONTACTEMAIL@EMAIL.COM و CONTACT PHONE NUMBER بمعلومات جهة اتصال جديدة.
Click Send.
راجع عارض الاستجابة في Postman لتحديد ما إذا كان webhook يعمل بشكل صحيح أم لا. إذا تم إرجاع رسالة غير 200 OK أو status: ok، فإن الرقم المرتبط بالرسالة يساعد في تحديد المشكلة.

التحرير على GitHub