وب‌هوک‌ها¶
هشدار
اکیداً توصیه می‌شود هنگام تصمیم‌گیری برای استفاده از وب‌هوک‌ها و در طول فرآیند پیاده‌سازی با یک توسعه‌دهنده، معمار راه‌حل یا نقش فنی دیگری مشورت کنید. اگر به‌درستی پیکربندی نشوند، وب‌هوک‌ها ممکن است پایگاه داده سازمان‌یار را مختل کرده و بازگرداندن آنها زمان‌بر باشد.
وب‌هوک‌ها، که می‌توانند در استودیو ایجاد شوند، قوانین اتوماسیونی هستند که توسط رویدادهای خارجی از طریق فراخوان‌های HTTP تعریف شده توسط کاربر فعال می‌شوند. هنگامی که یک سیستم خارجی داده‌ها را به URL وب‌هوک سازمان‌یار (محرک) با یک فایل داده (بار مفید) ارسال می‌کند، سازمان‌یار با یک اقدام از پیش تعریف شده در پایگاه داده پاسخ می‌دهد.
برخلاف عملیات زمان‌بندی شده یا فراخوان‌های API دستی، وب‌هوک‌ها ارتباط و اتوماسیون آنی را امکان‌پذیر می‌کنند. برای مثال، اگر یک سفارش فروش در یک سیستم POS خارجی تأیید شود، یک وب‌هوک می‌تواند فوراً موجودی سازمان‌یار را به‌روز کند و از همگام‌سازی سیستم اطمینان حاصل کند.
توجه
این مقاله ایجاد یک وب‌هوک را که داده‌ها را از یک منبع خارجی دریافت می‌کند پوشش می‌دهد. با این حال، می‌توان یک عملیات خودکار را نیز ایجاد کرد که یک فراخوان API به یک وب‌هوک خارجی ارسال می‌کند.
ایجاد وب‌هوک در استودیو¶
وب‌هوک‌ها در استودیو پیکربندی می‌شوند و راه‌اندازی از دو مرحله راه‌انداز و عملیات تشکیل می‌شود.
نکته
راه‌اندازی یک وب‌هوک در سازمان‌یار هنگام اتصال پایگاه‌های داده سازمان‌یار نیازی به کدنویسی ندارد، اما تست نیازمند ابزار خارجی مانند Postman است. رکوردهای هدف سفارشی یا عملیات ممکن است به مهارت‌های برنامه‌نویسی نیاز داشته باشند.
حالت توسعه‌دهنده را فعال کنید تا مدل مورد هدف وب‌هوک (مثلاً سفارش‌های فروش یا اطلاعات تماس) را اصلاح کرده و نام فنی مدل را پیدا کنید (که ممکن است برای پیکربندی صحیح بار مفید مورد نیاز باشد).
تنظیم راه‌انداز وب‌هوک¶
برای ایجاد یک وب‌هوک با استودیو، استودیو را باز کنید، وب‌هوک‌ها را کلیک کنید، سپس جدید را بزنید. سپس وب‌هوک را نام‌گذاری کنید، در صورت نیاز مدل وب‌هوک (نوع ورودی پایگاه داده مورد هدف) را اصلاح کنید و تعیین کنید که آیا فراخوان‌های انجام شده به URL وب‌هوک باید ثبت سوابق شوند (که تاریخچه فراخوان وب‌هوک را برای عیب‌یابی ردیابی می‌کند).
URL وب‌هوک به‌طور خودکار تولید می‌شود. این URL باید برای آزمایش وب‌هوک و اتصال آن به سیستم خارجی که به‌روزرسانی‌ها را به پایگاه داده ارسال می‌کند، استفاده شود.
خطر
URL وب‌هوک محرمانه است و باید با دقت با آن رفتار شود. به اشتراک گذاشتن آن به‌صورت آنلاین یا بدون احتیاط می‌تواند دسترسی ناخواسته به پایگاه داده سازمان‌یار را فراهم کند. در صورت نیاز، برای تغییر URL، چرخش رمز را کلیک کنید.
در نهایت، اگر سیستم ارسال‌کننده وب‌هوک سازمان‌یار نیست، عملیات رکورد هدف را تنظیم کنید تا به دنبال رکورد JSON باشد که در بار (payload) فراخوان API هنگام انجام فراخوان به URL وب‌هوک گنجانده شده است. اگر سیستم ارسال‌کننده وب‌هوک یک پایگاه داده سازمان‌یار است، مطمئن شوید که id و model در بار مفید ظاهر می‌شوند.
نکته
اگرچه مدل در سازمان‌یار تنظیم شده است، اما نام فنی مدل باید در payload گنجانده شود. ماوس را روی نام مدل ببرید، سپس آیکون :icon:`fa-arrow-right` (لینک داخلی) را کلیک کنید تا نام فنی را در فیلد مدل پیدا کنید. برای مثال، وب‌هوک سفارش فروش از مدل سفارش فروش استفاده می‌کند، اما در payload از نام فنی sale.order استفاده می‌شود.
توجه
هنگام ایجاد یک رکورد در پایگاه داده سازمان‌یار، فرمت پیش‌فرض رکورد هدف نباید استفاده شود. به جای آن، از model.browse(i) یا model.search(i) استفاده کنید.
تنظیم عملیات وب‌هوک¶
برای تنظیم عملیات وب‌هوک هنگام پیکربندی، افزودن عملیات را در تب عمل‌های قابل انجام کلیک کنید. نوع عمل را کلیک کرده و فیلدها را در صورت نیاز تنظیم کنید.
تست وب‌هوک¶
توجه
تست وب‌هوک مستلزم راه‌اندازی وب‌هوک، payload آزمایشی برای ارسال به وب‌هوک و یک ابزار یا سیستم خارجی برای ارسال payload از طریق یک درخواست API از نوع POST است. اگر باید به مهارت‌های فنی کمتری نیاز باشد، استفاده از ابزاری مانند Postman را در نظر بگیرید.
اگر در حین تست پیامی با مضمون 200 OK یا status: ok بازگردانده شود، وب‌هوک به‌درستی در سمت سازمان‌یار کار می‌کند. در ادامه، پیاده‌سازی با ابزار دیگر برای ارسال خودکار فراخوان‌های وب‌هوک به سازمان‌یار با استفاده از URL وب‌هوک می‌تواند آغاز شود.
اگر پاسخ‌های دیگری بازگردانده شوند، شماره ارسال شده در پاسخ به شناسایی مشکل کمک می‌کند. برای مثال، یک 500 Internal Server Error به این معنی است که سازمان‌یار نتوانسته است فراخوان را به‌درستی تفسیر کند. اگر این پاسخ بازگردانده شود، اطمینان حاصل کنید که فیلدهای موجود در فایل JSON به‌درستی در پیکربندی وب‌هوک و در سیستم ارسال‌کننده فراخوان آزمایشی نگاشت شده‌اند. فعال کردن ثبت سوابق فراخوان در پیکربندی وب‌هوک، در صورتی که وب‌هوک مطابق انتظار کار نکند، گزارش‌های خطا را ارائه می‌دهد.
پیاده‌سازی وب‌هوک¶
پس از پیکربندی کامل وب‌هوک، شروع به اتصال آن به سیستمی کنید که داده‌ها را از طریق این وب‌هوک به پایگاه داده سازمان‌یار ارسال می‌کند. هنگام راه‌اندازی آن سیستم، مطمئن شوید که فراخوان‌های API به URL وب‌هوک ارسال می‌شوند.
موارد استفاده وب‌هوک¶
در ادامه دو نمونه از نحوه استفاده از وب‌هوک‌ها در سازمان‌یار آورده شده است. این وب‌هوک‌ها به ابزارهای خارجی نیاز دارند (که همراه با مثال ذکر شده‌اند).
هشدار
هنگام تصمیم‌گیری برای پیاده‌سازی وب‌هوک‌ها، با یک توسعه‌دهنده، معمار راه‌حل یا نقش فنی دیگری مشورت کنید. اگر وب‌هوک‌ها به‌درستی پیکربندی نشوند، ممکن است پایگاه داده سازمان‌یار را مختل کرده و بازگرداندن آنها زمان‌بر باشد.
به‌روزرسانی واحد پول سفارش فروش¶
این وب‌هوک یک سفارش فروش را در برنامه فروش به USD به‌روز می‌کند. این کار برای شرکت‌های تابعه خارج از ایالات متحده با یک شرکت مادر مستقر در داخل ایالات متحده یا در یکپارچه‌سازی‌ها به هنگام یکپارچه‌سازی داده‌ها در یک پایگاه داده سازمان‌یار مفید است.
تنظیم راه‌انداز وب‌هوک¶
برای راه‌اندازی این وب‌هوک، برنامه فروش را باز کنید. سپس، راه‌انداز را تنظیم کنید به‌طوری که مدل روی سفارش فروش تنظیم شود. همچنین، رکورد هدف را روی model.env[payload.get('model')].browse(int(payload.get('id'))) تنظیم کنید. این ادامه جزئیات بیشتر توضیح داده شده است.
مدل: آنچه در سازمان‌یار به‌روز می‌شود (در این مورد، سفارشات فروش). این با مدل تنظیم شده قبلی مطابقت دارد.
env: جایی که اقدام انجام می‌شود. در این مورد، سازمان‌یار است.
payload: آنچه به URL وب‌هوک ارسال می‌شود. این شامل اطلاعاتی است که سفارش فروش را به‌روز می‌کند.
get('model'): به وب‌هوک می‌گوید به کدام رکورد پایگاه داده نگاه کند. در این مورد، وب‌هوک داده‌های مرتبط با یک
مدلخاص را دریافت (get) می‌کند. در این مثال، مدل سفارش فروش است.browse: به وب‌هوک می‌گوید در
مدل(سفارش فروش) تنظیم شده توسط payload برای آنچه باید به‌روز شود، جستجو کند.int: هدف را به یک
عدد صحیح(یک عدد کامل) تبدیل می‌کند. این در صورتی مهم است که برخی کلمات (یکرشته) یا یک عدد اعشاری در رکورد هدف بار مفید گنجانده شده باشد.get('id'): شماره سفارش فروشی را که در سازمان‌یار در حال به‌روزرسانی است، شناسایی می‌کند.
تنظیم عملیات وب‌هوک¶
پس از تنظیم راه‌انداز، عملیات وب‌هوک را با کلیک بر روی افزودن عملیات تنظیم کنید. برای نوع، به‌روزرسانی رکورد را کلیک کنید. سپس، به‌روزرسانی را انتخاب کنید، فیلد واحد پول را انتخاب کرده و USD را انتخاب کنید تا فیلد واحد پول به USD به‌روز شود. در نهایت، ذخیره و بستن را کلیک کنید.
خلاصه راه‌اندازی وب‌هوک¶
وب‌هوک سفارشات فروش را هدف قرار می‌دهد، که با شماره سفارش فروش آنها شناسایی می‌شوند و هنگامی که یک درخواست POST به URL وب‌هوک ارسال می‌شود که شامل آن شماره سفارش فروش است (که با رکورد id بار مفید شناسایی می‌شود) واحد پول آنها را به USD به‌روز می‌کند.
تست وب‌هوک¶
راه‌اندازی وب‌هوک را آزمایش کنید تا مطمئن شوید همه چیز درست است. این فرآیند از ابزاری به نام Postman برای ارسال محرک شبیه‌سازی شده استفاده می‌کند.
این بخش مراحل آزمایش این وب‌هوک را در Postman توضیح می‌دهد، اما در صورت بروز مشکل در آن ابزار، کمکی ارائه نمی‌دهد. برای دریافت کمک خاص در مورد Postman با تیم پشتیبانی آنها تماس بگیرید.
پس از باز شدن Postman، یک درخواست HTTP جدید ایجاد کرده و متد آن را روی POST تنظیم کنید. سپس، URL وب‌هوکی را که در حال آزمایش است کپی کرده و در فیلد URL در Postman جای‌گذاری کنید. پس از آن، تب Body را کلیک کرده و گزینه raw را انتخاب کنید. نوع فایل را روی JSON تنظیم کنید، سپس این کد را کپی کرده و در فایل جای‌گذاری کنید.
{
"model": "sale.order",
"id": "SALES ORDER NUMBER"
}
سپس یک سفارش فروش را برای آزمایش وب‌هوک انتخاب کنید. اگر آزمایش در یک پایگاه داده سازمان‌یار زنده امکان‌پذیر نیست، ایجاد پایگاه داده دمو با یک سفارش فروش نمونه و وب‌هوکی که پیکربندی شده است را در نظر بگیرید. SALES ORDER NUMBER را با شماره سفارش فروش بدون S یا هرگونه صفر قبل از شماره جایگزین کنید. برای مثال، یک سفارش فروش با شماره S00007 باید در Postman به شکل 7 وارد شود. در نهایت، ارسال را در Postman کلیک کنید.
اگر پیامی با مضمون 200 OK یا status: ok بازگردانده شود، وب‌هوک به‌درستی در سمت سازمان‌یار کار می‌کند. واحد پول سفارش فروش آزمایشی به‌روز می‌شود. سپس، پیاده‌سازی با ابزار دیگر برای ارسال خودکار آن فراخوان‌های وب‌هوک به سازمان‌یار با استفاده از URL وب‌هوک می‌تواند آغاز شود.
اگر پاسخ‌های دیگری بازگردانده شوند، شماره مرتبط با آنها به شناسایی مشکل کمک می‌کند. برای مثال، 500 Internal Server Error به این معنی است که سازمان‌یار نتوانسته است فراخوان را به‌درستی تفسیر کند. اگر این پاسخ بازگردانده شود، اطمینان حاصل کنید که فیلدهای model و id به‌درستی در پیکربندی وب‌هوک و در Postman نگاشت شده‌اند.
ایجاد مخاطب جدید¶
این وب‌هوک از کد سفارشی برای ایجاد یک مخاطب جدید در یک پایگاه داده سازمان‌یار استفاده می‌کند. این می‌تواند برای ایجاد خودکار فروشندگان یا مشتریان جدید مفید باشد.
تنظیم راه‌انداز وب‌هوک¶
برای راه‌اندازی این وب‌هوک، برنامه مخاطبان را باز کنید. سپس، محرک را تنظیم کنید به‌طوری که مدل روی مخاطب تنظیم شود. همچنین، رکورد هدف را روی model.browse([2]) تنظیم کنید. این مورد در زیر توضیح داده شده است.
مدل: آنچه در سازمان‌یار به‌روز می‌شود (در این مورد، یک مخاطب). این با مدل تنظیم شده قبلی مطابقت دارد.
browse: به وب‌هوک می‌گوید در
مدل(مخاطبان) تنظیم شده توسط بار مفید برای آنچه باید ایجاد شود، جستجو کند.
تنظیم عملیات وب‌هوک¶
پس از تنظیم راه‌انداز، عملیات وب‌هوک را با کلیک بر روی افزودن عمل تنظیم کنید. برای نوع، اجرای کد را کلیک کنید، سپس کد را بر اساس کد نمونه زیر تنظیم کنید. در نهایت، ذخیره و بستن را کلیک کنید.
# 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'")
خلاصه راه‌اندازی وب‌هوک¶
به‌طور خلاصه، وب‌هوک هنگامی که یک فراخوان API به URL وب‌هوک ارسال می‌شود که شامل اطلاعات مخاطب است، یک مخاطب ایجاد می‌کند.
تست وب‌هوک¶
راه‌اندازی وب‌هوک را آزمایش کنید تا مطمئن شوید همه چیز درست است. این فرآیند از ابزاری به نام Postman برای ارسال محرک شبیه‌سازی شده استفاده می‌کند.
این بخش مراحل آزمایش این وب‌هوک را در Postman توضیح می‌دهد، اما در صورت بروز مشکل در آن ابزار، کمکی ارائه نمی‌دهد. برای دریافت کمک خاص در مورد Postman با تیم پشتیبانی آنها تماس بگیرید.
پس از باز شدن Postman، یک درخواست جدید ایجاد کرده و متد آن را روی POST تنظیم کنید. سپس، URL وب‌هوکی را که در حال آزمایش است کپی کرده و در فیلد URL در Postman جای‌گذاری کنید. پس از آن، تب Body را کلیک کرده و raw را کلیک کنید. نوع فایل را روی JSON تنظیم کنید، سپس این کد را کپی کرده و در فایل جای‌گذاری کنید.
{
"name": "CONTACT NAME",
"email": "CONTACTEMAIL@EMAIL.COM",
"phone": "CONTACT PHONE NUMBER"
}
فیلدهای بالا را با اطلاعات یک مخاطب جدید در Postman جایگزین کنید و سپس ارسال را کلیک کنید.
اگر پیامی با مضمون 200 OK یا status: ok بازگردانده شود، وب‌هوک به‌درستی در سمت سازمان‌یار کار می‌کند. مخاطب تستی جدید در برنامه مخاطبان ظاهر می‌شود. از اینجا، پیاده‌سازی با ابزار دیگر برای ارسال خودکار آن فراخوان‌های وب‌هوک به سازمان‌یار با استفاده از URL وب‌هوک می‌تواند آغاز شود.
اگر پاسخ‌های دیگری بازگردانده شوند، شماره مرتبط با آنها به شناسایی مشکل کمک می‌کند. برای مثال، یک 500 Internal Server Error به این معنی است که سازمان‌یار نتوانسته است فراخوان را به‌درستی تفسیر کند. اگر این پاسخ بازگردانده شود، اطمینان حاصل کنید که فیلدهای موجود در فایل JSON به‌درستی در پیکربندی وب‌هوک و در Postman نگاشت شده‌اند.