وب‌هوک‌ها¶

هشدار

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

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

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

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

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

توجه

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

ایجاد وب‌هوک در سازمان‌یار¶

مهم

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

نکته

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

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

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

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

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

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

نکته

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

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

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

نکته

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

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

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

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

نکته

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

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

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

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

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

به‌روزرسانی واحد پول سفارش فروش¶

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

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

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

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

برنامه فروش را باز کنید، سپس استودیو را باز کنید و روی وب‌هوک‌ها کلیک کنید. مدل سفارش فروش به‌صورت پیش‌فرض انتخاب شده است.
روی جدید کلیک کنید. محرک به‌صورت پیش‌فرض روی هنگام وب‌هوک تنظیم شده است.
رکورد هدف را روی model.env[payload.get('_model')].browse(int(payload.get('_id'))) تنظیم کنید، که در آن:
- payload.get('_model') مقدار مرتبط با کلید model در بارِ داده را بازیابی می‌کند، یعنی sale.order، که نام فنی مدل سفارش فروش است.
- payload.get('_id') مقدار مرتبط با کلید id در بارِ داده را بازیابی می‌کند، یعنی شماره سفارش فروش هدف در پایگاه داده سازمان‌یار شما با حذف S و صفرهای ابتدایی.
- int شناسه بازیابی شده را به عدد صحیح (یعنی عدد کامل) تبدیل می‌کند زیرا متد browse() تنها می‌تواند با عدد صحیح استفاده شود.
روی افزودن اقدام کلیک کنید.
در بخش نوع، روی به‌روزرسانی رکورد کلیک کنید.
در بخش جزئیات اقدام، به‌روزرسانی را انتخاب کنید، فیلد ارز را انتخاب کرده و USD را برگزینید.
روی ذخیره و بستن کلیک کنید.

تست وب‌هوک¶

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

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

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

این وب‌هوک از کد سفارشی برای ایجاد مخاطب جدید در پایگاه داده سازمان‌یار استفاده می‌کند زمانی که سیستم خارجی درخواست 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 وب‌هوک سازمان‌یار را با استفاده از آیکون (لینک) کپی کرده و در فیلد URL در Postman جایگذاری کنید.
روی تب Body کلیک کرده و raw را انتخاب کنید.
نوع فایل را روی JSON تنظیم کنید، سپس این کد، یعنی بارِ داده را کپی کرده و در ویرایشگر کد جایگذاری کنید:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
در کد جایگذاری شده، CONTACT NAME، CONTACTEMAIL@EMAIL.COM، و CONTACT PHONE NUMBER را با اطلاعات مخاطب جدید جایگزین کنید.
روی Send کلیک کنید.
به نمایشگر پاسخ در Postman مراجعه کنید تا مشخص شود آیا وب‌هوک به‌درستی کار می‌کند یا خیر. اگر پیامی غیر از 200 OK یا status: ok بازگردانده شود، شماره مرتبط با پیام به شناسایی مشکل کمک می‌کند.