وب‌هوک‌ها¶

هشدار

توصیه می‌شود که هنگام تصمیم‌گیری برای استفاده از وب‌هوک‌ها و در طول فرآیند پیاده‌سازی، با یک توسعه‌دهنده، معمار راه‌حل یا نقش فنی دیگری مشورت کنید. در صورت پیکربندی نادرست، وب‌هوک‌ها ممکن است باعث اختلال در پایگاه داده Odoo شوند و بازگرداندن آن‌ها زمان‌بر باشد.

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

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

برخلاف اقدامات زمان‌بندی‌شده که در فواصل زمانی از پیش تعیین‌شده اجرا می‌شوند، یا درخواست‌های API دستی که باید به‌صورت صریح فراخوانی شوند، وب‌هوک‌ها ارتباط و اتوماسیون بلادرنگ و مبتنی بر رویداد را امکان‌پذیر می‌کنند. به‌عنوان مثال، می‌توانید یک وب‌هوک تنظیم کنید تا داده‌های موجودی اودو شما به‌طور خودکار به‌روزرسانی شوند زمانی که یک سفارش فروش در یک سیستم فروش خارجی تأیید می‌شود.

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

توجه

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

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

مهم

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

نکته

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

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

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

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

هشدار
نشانی اینترنتی محرمانه است و باید با دقت مورد استفاده قرار گیرد. به اشتراک‌گذاری آن به صورت آنلاین یا بدون احتیاط می‌تواند دسترسی ناخواسته به پایگاه داده Odoo را فراهم کند. اگر نشانی اینترنتی پس از اجرای اولیه به‌روزرسانی شود، مطمئن شوید که آن را در سیستم خارجی نیز به‌روزرسانی کنید.
در صورت تمایل، ثبت تماس‌ها را فعال کنید تا تاریخچه درخواست‌های API ارسال‌شده به URL وب‌هوک، مثلاً برای اهداف رفع اشکال، ردیابی شود.
اگر سیستمی که وب‌هوک را ارسال می‌کند، اودو نیست، کد رکورد هدف را تنظیم کنید تا به دنبال رکورد JSON موجود در payload باشد زمانی که درخواست API به URL وب‌هوک ارسال می‌شود. اگر سیستمی که وب‌هوک را ارسال می‌کند یک پایگاه داده اودو است، اطمینان حاصل کنید که id و model در payload ظاهر شوند.

اگر وب‌هوک برای ایجاد رکوردها در پایگاه داده Odoo استفاده شود، به جای قالب پیش‌فرض Target Record از model.browse(i) یا model.search(i) استفاده کنید.
روی افزودن یک اقدام در زبانه اقدامات قابل انجام کلیک کنید تا اقدامات مورد نظر برای اجرا تعریف شوند.
قبل از پیاده‌سازی وب‌هوک در سیستم خارجی، آزمایش کنید تا اطمینان حاصل کنید که به درستی کار می‌کند.

نکته

وب‌هوک‌ها همچنین می‌توانند از طریق منوی اتوماسیون‌ها در استودیو با انتخاب محرک روی وب‌هوک ایجاد شوند.
برای دسترسی به تاریخچه درخواست‌های API در صورتی که ثبت تماس‌ها فعال شده باشد، روی دکمه هوشمند لاگ‌ها در بالای فرم قوانین اتوماسیون کلیک کنید.
اگر هدف وب‌هوک چیزی غیر از به‌روزرسانی یک رکورد موجود باشد، به عنوان مثال، ایجاد یک رکورد جدید، باید اقدام اجرای کد انتخاب شود.

آزمایش یک وب‌هوک¶

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

نکته

بخش موارد استفاده از وب‌هوک را برای توضیحات گام‌به‌گام در مورد نحوه آزمایش وب‌هوک‌ها با استفاده از داده‌های آزمایشی مشاهده کنید.
برای دریافت کمک خاص در مورد آزمایش یک وب‌هوک با Postman، با تیم پشتیبانی آن‌ها تماس بگیرید.

در Postman، یک درخواست HTTP جدید ایجاد کنید و روش آن را روی POST تنظیم کنید.
آدرس وب‌هوک را از پایگاه داده Odoo خود با استفاده از آیکون (لینک) کپی کرده و آن را در قسمت URL در Postman وارد کنید.
روی زبانه بدنه کلیک کنید و خام را انتخاب کنید.
نوع فایل را به JSON تنظیم کنید، سپس کد را از بار آزمایشی کپی کرده و در ویرایشگر کد جای‌گذاری کنید.
کلیک کنید: ارسال.

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

پیام 200 OK یا status: ok نشان‌دهنده این است که وب‌هوک در سمت اودو به‌درستی کار می‌کند. از اینجا، پیاده‌سازی می‌تواند با سیستم دیگر آغاز شود تا درخواست‌های API به‌صورت خودکار به URL وب‌هوک اودو ارسال شوند.
اگر هر پاسخ دیگری بازگردانده شود، شماره مرتبط با آن به شناسایی مشکل کمک می‌کند. به عنوان مثال، پیام 500 Internal Server Error به این معناست که Odoo نتوانسته تماس را به درستی تفسیر کند. در این حالت، اطمینان حاصل کنید که فیلدهای موجود در فایل JSON به درستی در تنظیمات وب‌هوک و در سیستمی که تماس آزمایشی را ارسال می‌کند، نقشه‌برداری شده‌اند.

نکته

فعال کردن ثبت تماس در تنظیمات وب‌هوک در Odoo، گزارش‌های خطا را در صورت عدم عملکرد صحیح وب‌هوک ارائه می‌دهد.

پیاده‌سازی یک وب‌هوک در یک سیستم خارجی¶

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

موارد استفاده از وب‌هوک¶

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

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

این وب‌هوک یک سفارش فروش را در برنامه فروش به USD به‌روزرسانی می‌کند، زمانی که سیستم خارجی یک درخواست API از نوع POST به URL وب‌هوک ارسال می‌کند که شامل شماره سفارش فروش (که با رکورد id در payload شناسایی می‌شود) باشد.

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

ایجاد وب‌هوک¶

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

برنامه فروش را باز کنید، سپس استودیو را باز کنید و روی وب‌هوک‌ها کلیک کنید. مدل سفارش فروش به‌صورت پیش‌فرض انتخاب شده است.
روی جدید کلیک کنید. تریگر به صورت پیش‌فرض روی بر اساس وب‌هوک تنظیم شده است.
رکورد هدف را به 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 شناسه بازیابی‌شده را به یک عدد صحیح (یعنی یک عدد کامل) تبدیل می‌کند، زیرا متد browse() فقط می‌تواند با یک عدد صحیح استفاده شود.
کلیک کنید افزودن یک اقدام.
در بخش نوع، روی به‌روزرسانی رکورد کلیک کنید.
در بخش جزئیات اقدام، گزینه به‌روزرسانی را انتخاب کنید، فیلد ارز را انتخاب کرده و USD را برگزینید.
کلیک کنید: ذخیره و بستن.

وب‌هوک را آزمایش کنید¶

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

با باز کردن Postman، یک درخواست HTTP جدید ایجاد کنید و روش آن را روی POST تنظیم کنید.
آدرس URL وب‌هوک Odoo را با استفاده از آیکون (لینک) کپی کرده و آن را در فیلد URL در Postman جای‌گذاری کنید.
روی زبانه بدنه کلیک کنید و خام را انتخاب کنید.
نوع فایل را به JSON تنظیم کنید، سپس این کد، یعنی payload، را کپی کرده و در ویرایشگر کد جای‌گذاری کنید:
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
در پایگاه داده Odoo خود، یک سفارش فروش را برای آزمایش وب‌هوک انتخاب کنید. در کدی که وارد کرده‌اید، شماره سفارش فروش را با شماره سفارش فروش بدون S یا هر صفر قبل از شماره جایگزین کنید. به عنوان مثال، یک سفارش فروش با شماره S00007 باید به صورت 7 در Postman وارد شود.
کلیک کنید: ارسال.
برای بررسی عملکرد صحیح وب‌هوک، به نمایشگر پاسخ در Postman مراجعه کنید. اگر پیامی غیر از 200 OK یا status: ok بازگردانده شود، شماره مرتبط با پیام به شناسایی مشکل کمک می‌کند.

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

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

ایجاد وب‌هوک¶

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

برنامه مخاطبین را باز کنید، سپس استودیو را باز کنید و روی وب‌هوک‌ها کلیک کنید. مدل مخاطب به صورت پیش‌فرض انتخاب شده است.
روی جدید کلیک کنید. تریگر به صورت پیش‌فرض روی بر اساس وب‌هوک تنظیم شده است.
رکورد هدف را به model.browse([2]) تنظیم کنید. این اساساً یک جایگزین است زیرا کد موجود در اقدام خودکار به وب‌هوک می‌گوید که چه چیزی باید از داده‌های ورودی بازیابی شود و رکورد در کدام مدل باید ایجاد شود.
کلیک کنید افزودن یک اقدام.
در بخش نوع، روی اجرای کد کلیک کنید.

این کد را کپی کرده و در ویرایشگر کد در برگه کد از بخش جزئیات اقدام جای‌گذاری کنید:

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

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

وب‌هوک را آزمایش کنید¶

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

در Postman، یک درخواست HTTP جدید ایجاد کنید و روش آن را به POST تنظیم کنید.
آدرس URL وب‌هوک Odoo را با استفاده از آیکون (لینک) کپی کرده و آن را در فیلد URL در Postman جای‌گذاری کنید.
روی زبانه بدنه کلیک کنید و خام را انتخاب کنید.
نوع فایل را به JSON تنظیم کنید، سپس این کد، یعنی payload، را کپی کرده و در ویرایشگر کد جای‌گذاری کنید:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
در کد جای‌گذاری‌شده، نام تماس، ایمیل‌تماس@ایمیل.کام و شماره‌تلفن‌تماس را با اطلاعات تماس جدید جایگزین کنید.
کلیک کنید: ارسال.
برای بررسی عملکرد صحیح وب‌هوک، به نمایشگر پاسخ در Postman مراجعه کنید. اگر پیامی غیر از 200 OK یا status: ok بازگردانده شود، شماره مرتبط با پیام به شناسایی مشکل کمک می‌کند.