وب‌هوک‌ها

هشدار

به‌شدت توصیه می‌شود با یک توسعه‌دهنده، solution architect یا یک نقش فنی دیگر هنگام تصمیم به استفاده از webhook‌ها و در سراسر فرآیند پیاده‌سازی مشورت کنید. اگر به‌درستی پیکربندی نشود، webhook‌ها ممکن است پایگاه دادهٔ Odoo را مختل کنند و می‌توانند زمان زیادی برای برگرداندن نیاز داشته باشند.

Webhook‌ها، که می‌توانند در Odoo Studio ایجاد شوند، به شما اجازه می‌دهند یک اقدام در پایگاه دادهٔ Odoo خود را زمانی که یک رویداد خاص در یک سامانهٔ دیگر، خارجی رخ می‌دهد خودکار کنید.

در عمل، این به‌صورت زیر کار می‌کند: هنگامی که رویداد در سامانهٔ خارجی رخ می‌دهد، یک فایل داده ("payload") به URL webhook Odoo از طریق یک درخواست API POST ارسال می‌شود و یک اقدام از پیش تعریف‌شده در پایگاه دادهٔ Odoo شما انجام می‌شود.

برخلاف اقدامات برنامه‌ریزی‌شده، که در فواصل از پیش تعریف‌شده اجرا می‌شوند، یا درخواست‌های API دستی، که نیاز به فراخوانی صریح دارند، webhook‌ها ارتباط و automation رویداد-محور بلادرنگ را فعال می‌کنند. برای مثال، می‌توانید یک webhook راه‌اندازی کنید تا داده‌های موجودی Odoo شما به‌طور خودکار به‌روزرسانی شوند هنگامی که یک سفارش فروش در یک سامانهٔ point-of-sale خارجی تأیید می‌شود.

راه‌اندازی یک webhook در Odoo هنگام اتصال دو پایگاه دادهٔ Odoo نیاز به کدنویسی ندارد، اما تست یک webhook نیاز به یک ابزار خارجی دارد. رکوردهای هدف سفارشی یا اقدامات ممکن است نیاز به مهارت‌های برنامه‌نویسی داشته باشند.

توجه

این مقاله ایجاد یک webhook که داده را دریافت می‌کند از یک منبع خارجی را پوشش می‌دهد. با این حال، همچنین امکان ایجاد یک اقدام خودکار وجود دارد که داده را به یک webhook خارجی ارسال می‌کند هنگامی که یک تغییر در پایگاه دادهٔ Odoo شما رخ می‌دهد.

ایجاد یک وب‌هوک در Odoo

مهم

قبل از پیاده‌سازی یک webhook در یک پایگاه دادهٔ زنده، آن را با استفاده از یک duplicate database پیکربندی و تست کنید تا اطمینان حاصل شود webhook طبق نیت عمل می‌کند.

نکته

فعال‌سازی developer mode قبل از ایجاد یک webhook انعطاف‌پذیری بیشتری در انتخاب model که قانون automation هدف‌گذاری می‌کند می‌دهد. همچنین به شما اجازه می‌دهد نام فنی مدل و فیلدها را پیدا کنید، که ممکن است برای پیکربندی payload لازم باشد.

برای یافتن نام فنی یک مدل، با فعال بودن developer mode، ماوس را روی نام مدل نگه دارید و سپس روی (Internal link) کلیک کنید. نام فنی را می‌توان در فیلد مدل پیدا کرد. برای مثال، یک وب‌هوک سفارش فروش از مدل سفارش فروش استفاده می‌کند، اما نام فنی sale.order در payload استفاده می‌شود.

برای ایجاد یک webhook در Studio، به‌صورت زیر عمل کنید:

  1. Studio را باز کنید و روی Webhooks کلیک کنید، سپس جدید.

  2. به webhook یک نام واضح و معنادار بدهید که هدف آن را شناسایی کند.

  3. در صورت لزوم و اگر developer mode فعال باشد، مدل مناسب را از dropdown انتخاب کنید. اگر developer mode فعال نباشد، قانون automation به‌صورت پیش‌فرض مدل فعلی را هدف‌گذاری می‌کند.

  4. URL webhook به‌طور خودکار تولید می‌شود، اما در صورت لزوم می‌تواند با کلیک روی چرخش رمزعبور تغییر کند. این URL است که باید هنگام پیاده‌سازی webhook در سامانهٔ خارجی که به‌روزرسانی‌ها را به پایگاه داده ارسال می‌کند استفاده شود.

    هشدار

    URL محرمانه است و باید با احتیاط رفتار شود. به اشتراک‌گذاری آن به‌صورت آنلاین یا بدون احتیاط می‌تواند دسترسی ناخواسته به پایگاه دادهٔ Odoo را فراهم کند. اگر URL پس از پیاده‌سازی اولیه به‌روزرسانی شود، اطمینان حاصل کنید آن را در سامانهٔ خارجی به‌روزرسانی کنید.

  5. در صورت تمایل، ثبت تماس‌ها را فعال کنید تا تاریخچهٔ درخواست‌های API انجام‌شده به URL webhook را پیگیری کنید، مثلاً، برای اهداف عیب‌یابی.

  6. اگر سامانه‌ای که webhook را ارسال می‌کند Odoo نیست، کد رکورد هدف را تنظیم کنید تا به دنبال رکورد JSON گنجانده‌شده در payload هنگامی که درخواست API به URL webhook انجام می‌شود بگردد. اگر سامانه‌ای که webhook را ارسال می‌کند یک پایگاه دادهٔ Odoo است، اطمینان حاصل کنید که id و model در payload ظاهر می‌شوند.

    اگر webhook برای ایجاد رکوردها در پایگاه دادهٔ Odoo استفاده می‌شود، از model.browse(i) یا model.search(i) به‌جای فرمت پیش‌فرض رکورد هدف استفاده کنید.

  7. روی اقدامی را اضافه کنید در زبانهٔ عملیات که باید انجام شود کلیک کنید تا actions برای اجرا تعریف شوند.

  8. قبل از پیاده‌سازی webhook در سامانهٔ خارجی، آن را test کنید تا اطمینان حاصل شود طبق نیت کار می‌کند.

نکته

  • Webhook‌ها همچنین می‌توانند از طریق منوی Automations در Studio با انتخاب trigger در وب هوک ایجاد شوند.

  • برای دسترسی به تاریخچهٔ درخواست‌های API اگر ثبت تماس‌ها فعال شده باشد، روی دکمهٔ هوشمند گزارش ها در بالای فرم عملیات خودکار کلیک کنید.

  • اگر هدف webhook هر چیزی غیر از به‌روزرسانی یک رکورد موجود باشد، مثلاً، ایجاد یک رکورد جدید، اقدام اجرای کد پایتون باید انتخاب شود.

تست یک وب‌هوک

تست یک webhook نیاز به یک test payload و یک ابزار یا سامانهٔ خارجی، مانند Postman، برای ارسال payload از طریق یک درخواست API POST دارد. این بخش مراحل تست یک webhook در Postman را ارائه می‌دهد.

نکته

  • webhook use cases section را برای توضیحات گام‌به‌گام نحوهٔ تست webhook‌ها با استفاده از test payload‌ها ببینید.

  • برای دریافت کمک خاص با تست یک webhook با Postman، با تیم پشتیبانی آنها تماس بگیرید.

  1. در Postman، یک درخواست HTTP جدید ایجاد کنید و method آن را به ارسال تنظیم کنید.

  2. URL webhook را از پایگاه دادهٔ Odoo خود با استفاده از آیکون (link) کپی کنید و آن را در فیلد URL در Postman پیست کنید.

  3. روی زبانهٔ بدنه کلیک کنید و raw را انتخاب کنید.

  4. نوع فایل را به JSON تنظیم کنید، سپس کد را از test payload کپی کنید و آن را در ویرایشگر کد پیست کنید.

  5. روی ارسال کلیک کنید.

در viewer Response در پایین صفحه در Postman، جزئیات، شامل یک کد پاسخ HTTP، نشان می‌دهد آیا webhook به‌درستی عمل می‌کند یا نه.

  • یک پیام 200 OK یا status: ok نشان می‌دهد که webhook به‌درستی در سمت Odoo کار می‌کند. از اینجا، پیاده‌سازی می‌تواند با سامانهٔ دیگر شروع شود تا درخواست‌های API را به‌طور خودکار به URL webhook Odoo ارسال کند.

  • اگر هر پاسخ دیگری بازگردانده شود، عدد مرتبط با آن کمک می‌کند مشکل را شناسایی کنید. برای مثال، یک پیام 500 Internal Server Error به این معنی است که Odoo نتوانست فراخوانی را به‌درستی تفسیر کند. در این صورت، اطمینان حاصل کنید فیلدهای موجود در فایل JSON به‌درستی در پیکربندی webhook و در سامانه‌ای که فراخوانی تست را ارسال می‌کند نگاشت شده‌اند.

نکته

روشن کردن log فراخوانی در پیکربندی webhook در Odoo log‌های خطا را ارائه می‌دهد اگر webhook طبق نیت کار نکند.

پیاده‌سازی یک webhook در یک سامانهٔ خارجی

هنگامی که webhook با موفقیت در Odoo ایجاد و تست شد، آن را در سامانه‌ای که داده را به پایگاه دادهٔ Odoo ارسال می‌کند پیاده‌سازی کنید، با اطمینان از اینکه درخواست‌های API POST به URL webhook ارسال می‌شوند.

موارد کاربرد وب‌هوک

در زیر دو مثال از نحوهٔ استفاده از webhook‌ها در Odoo آمده است. یک test payload برای هر مثال ارائه شده است و می‌توان آن را در بخش تست webhook یافت. Postman برای ارسال test payload استفاده می‌شود.

به‌روزرسانی ارز یک سفارش فروش

این webhook یک سفارش فروش در اپ Sales را به USD به‌روزرسانی می‌کند هنگامی که سامانهٔ خارجی یک درخواست API POST به URL webhook ارسال می‌کند که شامل آن شمارهٔ سفارش فروش است (که توسط رکورد id payload شناسایی می‌شود).

این می‌تواند برای شعبه‌های خارج از ایالات متحده با یک شرکت مادر واقع در داخل ایالات متحده یا در طول ادغام‌ها هنگام consolidating داده‌ها به یک پایگاه دادهٔ Odoo مفید باشد.

ایجاد وب‌هوک

برای ایجاد این webhook، به‌صورت زیر عمل کنید:

  1. اپ Sales را باز کنید، سپس Studio را باز کنید و روی Webhooks کلیک کنید. مدل سفارش فروش به‌صورت پیش‌فرض انتخاب شده است.

  2. روی جدید کلیک کنید. راه اندازی به‌صورت پیش‌فرض روی در وب هوک تنظیم می‌شود.

  3. رکورد هدف را به model.env[payload.get('_model')].browse(int(payload.get('_id'))) تنظیم کنید، که در آن:

    • payload.get('_model') مقدار مرتبط با کلید model در payload را بازیابی می‌کند، یعنی، sale.order، که نام فنی مدل سفارش فروش است.

    • payload.get('_id') مقدار مرتبط با کلید id در payload را بازیابی می‌کند، یعنی، شمارهٔ سفارش فروش هدف در پایگاه دادهٔ Odoo شما با S و صفرهای پیشرو حذف‌شده.

    • int id بازیابی‌شده را به یک integer (یعنی، یک عدد صحیح) تبدیل می‌کند زیرا method browse() فقط می‌تواند با یک integer استفاده شود.

  4. روی اقدامی را اضافه کنید کلیک کنید.

  5. در بخش نوع، روی بروزرسانی رکورد کلیک کنید.

  6. در بخش جزئیات عملیات، بروزرسانی را انتخاب کنید، فیلد ارز را انتخاب کنید و USD را انتخاب کنید.

  7. روی ذخیره و بستن کلیک کنید.

تست وب‌هوک

برای تست این webhook، به‌صورت زیر عمل کنید:

  1. با Postman باز، یک درخواست HTTP جدید ایجاد کنید و method آن را به ارسال تنظیم کنید.

  2. URL webhook Odoo را با استفاده از آیکون (link) کپی کنید و آن را در فیلد URL در Postman پیست کنید.

  3. روی زبانهٔ بدنه کلیک کنید و raw را انتخاب کنید.

  4. نوع فایل را به JSON تنظیم کنید، سپس این کد، یعنی، payload را کپی کنید و آن را در ویرایشگر کد پیست کنید:

    {
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}

  5. در پایگاه دادهٔ Odoo خود، یک سفارش فروش را برای تست webhook انتخاب کنید. در کد پیست‌شده، SALES ORDER NUMBER را با شمارهٔ سفارش فروش بدون S یا هیچ صفر قبل از عدد جایگزین کنید. برای مثال، یک سفارش فروش با شمارهٔ S00007 باید به‌عنوان 7 در Postman وارد شود.

  6. روی ارسال کلیک کنید.

  7. با Response viewer در Postman مشورت کنید تا تعیین کنید آیا webhook به‌درستی کار می‌کند یا نه. اگر پیامی غیر از 200 OK یا status: ok بازگردانده شود، عدد مرتبط با پیام کمک می‌کند مشکل را شناسایی کنید.

ایجاد یک مخاطب جدید

این webhook از کد سفارشی برای ایجاد یک مخاطب جدید در یک پایگاه دادهٔ Odoo استفاده می‌کند هنگامی که سامانهٔ خارجی یک درخواست API POST به URL webhook ارسال می‌کند که شامل اطلاعات مخاطب است. این می‌تواند برای ایجاد خودکار فروشندگان یا مشتریان جدید مفید باشد.

ایجاد وب‌هوک

برای ایجاد این webhook، به‌صورت زیر عمل کنید:

  1. اپ Contacts را باز کنید، سپس Studio را باز کنید و روی Webhooks کلیک کنید. مدل مخاطب به‌صورت پیش‌فرض انتخاب شده است.

  2. روی جدید کلیک کنید. راه اندازی به‌صورت پیش‌فرض روی در وب هوک تنظیم می‌شود.

  3. رکورد هدف را به model.browse([2]) تنظیم کنید. این اساساً یک placeholder است زیرا کد در اقدام خودکار به webhook می‌گوید چه چیزی باید از payload بازیابی شود و در کدام مدل رکورد باید ایجاد شود.

  4. روی اقدامی را اضافه کنید کلیک کنید.

  5. در بخش نوع، روی اجرای کد پایتون کلیک کنید.

  6. این کد را کپی کنید و آن را در ویرایشگر کد در زبانهٔ کد بخش جزئیات عملیات پیست کنید:

    # 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'")

  7. روی ذخیره و بستن کلیک کنید.

تست وب‌هوک

برای تست این webhook، به‌صورت زیر عمل کنید:

  1. در Postman، یک درخواست HTTP جدید ایجاد کنید و method آن را به ارسال تنظیم کنید.

  2. URL webhook Odoo را با استفاده از آیکون (link) کپی کنید و آن را در فیلد URL در Postman پیست کنید.

  3. روی زبانهٔ بدنه کلیک کنید و raw را انتخاب کنید.

  4. نوع فایل را به JSON تنظیم کنید، سپس این کد، یعنی، payload را کپی کنید و آن را در ویرایشگر کد پیست کنید:

    {
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}

  5. در کد پیست‌شده، CONTACT NAME، CONTACTEMAIL@EMAIL.COM و CONTACT PHONE NUMBER را با اطلاعات یک مخاطب جدید جایگزین کنید.

  6. روی ارسال کلیک کنید.

  7. با Response viewer در Postman مشورت کنید تا تعیین کنید آیا webhook به‌درستی کار می‌کند یا نه. اگر پیامی غیر از 200 OK یا status: ok بازگردانده شود، عدد مرتبط با پیام کمک می‌کند مشکل را شناسایی کنید.