Вебхуки

Попередження

Наполегливо рекомендується проконсультуватися з розробником, архітектором рішень або іншим фахівцем з технічних питань, приймаючи рішення про використання вебхуків і протягом усього процесу впровадження. Якщо вебхуки налаштовані неправильно, вони можуть порушити роботу бази даних Odoo, і на їх відновлення може знадобитися час.

Вебхуки, які можна створити в Odoo Studio, дозволяють автоматизувати дію у вашій базі даних Odoo, коли відбувається певна подія в іншій зовнішній системі.

На практиці це працює так: коли подія відбувається у зовнішній системі, файл даних («корисне навантаження») надсилається на URL-адресу вебхука Odoo через API-запит POST, і у вашій базі даних Odoo виконується попередньо визначена дія.

На відміну від запланованих дій, які виконуються через визначені інтервали, або ручних API-запитів, які потрібно явно викликати, вебхуки забезпечують комунікацію та автоматизацію в реальному часі, керовану подіями. Наприклад, ви можете налаштувати вебхук для автоматичного оновлення даних складу Odoo, коли замовлення на продаж підтверджується у зовнішній системі точки продажу.

Налаштування вебхука в Odoo не вимагає програмування під час з’єднання двох баз даних Odoo, але тестування вебхука вимагає зовнішнього інструменту. Спеціальні цільові записи або дії можуть вимагати навичок програмування.

Примітка

Ця стаття охоплює створення вебхука, який отримує дані із зовнішнього джерела. Однак також можливо створити автоматичну дію, яка надсилає дані на зовнішній вебхук, коли відбувається зміна у вашій базі даних Odoo.

Створити вебхук в Odoo

Важливо

Перед впровадженням вебхука в робочу базу даних налаштуйте та протестуйте його за допомогою дублікату бази даних, щоб переконатися, що вебхук працює належним чином.

Порада

Активація режиму розробника перед створенням вебхука надає більшу гнучкість у виборі моделі, на яку спрямоване правило автоматизації. Це також дозволяє знайти технічну назву моделі та полів, що може знадобитися для налаштування корисного навантаження.

Щоб знайти технічну назву моделі, з активованим режимом розробника, наведіть курсор на назву моделі, а потім натисніть (Внутрішнє посилання). Технічну назву можна знайти в полі Модель. Наприклад, вебхук замовлення на продаж використовує модель Замовлення на продаж, але в корисному навантаженні використовується технічна назва sale.order.

Щоб створити вебхук у Studio, виконайте такі дії:

  1. Відкрийте Studio і натисніть Вебхуки, потім Створити.

  2. Дайте вебхуку зрозумілу, значущу назву, яка визначає його призначення.

  3. Якщо потрібно, і за умови активації режиму розробника, виберіть відповідну Модель зі спадного меню. Якщо режим розробника не активовано, правило автоматизації за замовчуванням спрямоване на поточну модель.

  4. URL-адреса вебхука генерується автоматично, але за потреби її можна змінити, натиснувши Rotate Secret. Це URL-адреса, яку слід використовувати при впровадженні вебхука у зовнішній системі, що надсилатиме оновлення до бази даних.

    Попередження

    URL-адреса є конфіденційною і з нею слід поводитися обережно. Публікація її в мережі або без застережень може надати небажаний доступ до бази даних Odoo. Якщо URL-адресу оновлено після початкового впровадження, обов’язково оновіть її у зовнішній системі.

  5. За бажання увімкніть Log Calls, щоб відстежувати історію API-запитів до URL-адреси вебхука, наприклад, для усунення несправностей.

  6. Якщо система, що надсилає вебхук, не є Odoo, налаштуйте код Target Record, щоб шукати запис JSON, включений у корисне навантаження, коли виконується API-запит до URL-адреси вебхука. Якщо система, що надсилає вебхук, є базою даних Odoo, переконайтеся, що id і model присутні в корисному навантаженні.

    Якщо вебхук використовується для створення записів у базі даних Odoo, використовуйте model.browse(i) або model.search(i) замість стандартного формату Target Record.

  7. Натисніть Add an action на вкладці Actions To Do, щоб визначити дії, які потрібно виконати.

  8. Перед впровадженням вебхука у зовнішній системі протестуйте його, щоб переконатися, що він працює належним чином.

Порада

  • Вебхуки також можна створювати через меню Automations у Studio, вибравши тригер On webhook.

  • Щоб отримати доступ до історії API-запитів, якщо ввімкнено Log Calls, натисніть розумну кнопку Logs у верхній частині форми Automation rules.

  • Якщо метою вебхука є щось інше, ніж оновлення наявного запису, наприклад, створення нового запису, необхідно вибрати дію Execute Code.

Тестування вебхука

Тестування вебхука вимагає тестового корисного навантаження та зовнішнього інструменту або системи, як-от Postman, для надсилання корисного навантаження через API-запит POST. У цьому розділі наведено кроки для тестування вебхука в Postman.

Порада

  • Дивіться розділ прикладів використання вебхуків для покрокових пояснень, як тестувати вебхуки з використанням тестових корисних навантажень.

  • Щоб отримати конкретну допомогу з тестування вебхука в Postman, зверніться до їхньої служби підтримки.

  1. У Postman створіть новий HTTP-запит і встановіть його метод на POST.

  2. Скопіюйте URL-адресу вебхука з вашої бази даних Odoo за допомогою піктограми (link) і вставте її в поле URL у Postman.

  3. Натисніть вкладку Body і виберіть raw.

  4. Встановіть тип файлу на JSON, потім скопіюйте код з тестового корисного навантаження та вставте його в редактор коду.

  5. Натисніть Send.

У переглядачі Response внизу екрана в Postman відображаються деталі, включно з кодом відповіді HTTP, що вказують на те, чи правильно функціонує вебхук.

  • Повідомлення 200 OK або status: ok вказує на те, що вебхук правильно функціонує з боку Odoo. Звідси можна розпочати впровадження з іншою системою для автоматичної відправки API-запитів на URL вебхука Odoo.

  • Якщо повертається будь-яка інша відповідь, пов’язане з нею число допомагає визначити проблему. Наприклад, повідомлення 500 Internal Server Error означає, що Odoo не змогла правильно інтерпретувати виклик. У цьому випадку переконайтеся, що поля, знайдені у файлі JSON, правильно зіставлені в конфігурації вебхука та в системі, яка надсилає тестовий виклик.

Порада

Увімкнення журналювання викликів у конфігурації вебхука в Odoo надає журнали помилок, якщо вебхук не функціонує належним чином.

Впровадження вебхука у зовнішній системі

Коли вебхук успішно створено в Odoo та протестовано, впровадьте його в системі, яка надсилає дані до бази даних Odoo, переконавшись, що POST API-запити надсилаються на URL вебхука.

Випадки використання вебхуків

Нижче наведено два приклади використання вебхуків в Odoo. Для кожного прикладу надається тестове навантаження, яке можна знайти в розділі про тестування вебхука. Для надсилання тестового навантаження використовується Postman.

Оновлення валюти замовлення на продаж

Цей вебхук оновлює замовлення на продаж у застосунку Продажі на USD, коли зовнішня система надсилає POST API-запит на URL вебхука, що включає номер цього замовлення на продаж (який ідентифікується записом id навантаження).

Це може бути корисним для дочірніх компаній за межами Сполучених Штатів з материнською компанією, розташованою в Сполучених Штатах, або під час злиття при консолідації даних в одну базу даних Odoo.

Створення вебхука

Щоб створити цей вебхук, виконайте наступні дії:

  1. Відкрийте застосунок Продажі, потім відкрийте Studio і натисніть Вебхуки. Модель Замовлення на продаж вибрана за замовчуванням.

  2. Натисніть Створити. Тригер встановлено на При вебхуку за замовчуванням.

  3. Встановіть Цільовий запис на model.env[payload.get('_model')].browse(int(payload.get('_id'))), де:

    • payload.get('_model') отримує значення, пов’язане з ключем model у навантаженні, тобто sale.order, яке є технічною назвою моделі Замовлення на продаж.

    • payload.get('_id') отримує значення, пов’язане з ключем id у навантаженні, тобто номер цільового замовлення на продаж у вашій базі даних Odoo з видаленими S та провідними нулями.

    • int перетворює отриманий id на ціле число (тобто на число без дробової частини), оскільки метод browse() може використовуватися лише з цілим числом.

  4. Натисніть Додати дію.

  5. У розділі Тип натисніть Оновити запис.

  6. У розділі Деталі дії виберіть Оновити, оберіть поле Валюта і виберіть USD.

  7. Натисніть Зберегти та закрити.

Тестувати вебхук

Щоб протестувати цей вебхук, виконайте наступне:

  1. Відкривши Postman, створіть новий HTTP-запит і встановіть його метод на POST.

  2. Скопіюйте URL вебхука Odoo за допомогою піктограми (посилання) і вставте його в поле URL у Postman.

  3. Натисніть вкладку Body і виберіть raw.

  4. Встановіть тип файлу на JSON, потім скопіюйте цей код (корисне навантаження) і вставте його в редактор коду:

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

  5. У вашій базі даних Odoo оберіть замовлення на продаж для тестування вебхука. У вставленому коді замініть SALES ORDER NUMBER на номер замовлення на продаж без S і будь-яких нулів перед номером. Наприклад, замовлення на продаж з номером S00007 слід ввести як 7 у Postman.

  6. Натисніть Send.

  7. Перегляньте Переглядач відповідей у Postman, щоб визначити, чи правильно функціонує вебхук. Якщо повертається повідомлення, відмінне від 200 OK або status: ok, номер, пов’язаний з повідомленням, допомагає визначити проблему.

Створити новий контакт

Цей вебхук використовує власний код для створення нового контакту в базі даних Odoo, коли зовнішня система надсилає API-запит POST на URL вебхука, що містить інформацію про контакт. Це може бути корисним для автоматичного створення нових постачальників або клієнтів.

Створення вебхука

Щоб створити цей вебхук, виконайте наступні дії:

  1. Відкрийте застосунок Контакти, потім відкрийте Studio і натисніть Вебхуки. Модель Контакт вибрано за замовчуванням.

  2. Натисніть Створити. Тригер встановлено на При вебхуку за замовчуванням.

  3. Встановіть Цільовий запис на model.browse([2]). По суті, це заповнювач, оскільки код в автоматизованій дії вказує вебхуку, що потрібно отримати з корисного навантаження і в якій моделі потрібно створити запис.

  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. Натисніть Зберегти та закрити.

Тестувати вебхук

Щоб протестувати цей вебхук, виконайте наступне:

  1. У Postman створіть новий HTTP-запит і встановіть його метод на POST.

  2. Скопіюйте URL вебхука Odoo за допомогою піктограми (посилання) і вставте його в поле URL у Postman.

  3. Натисніть вкладку Body і виберіть raw.

  4. Встановіть тип файлу на JSON, потім скопіюйте цей код (корисне навантаження) і вставте його в редактор коду:

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

  5. У вставленому коді замініть CONTACT NAME, CONTACTEMAIL@EMAIL.COM і CONTACT PHONE NUMBER на інформацію нового контакту.

  6. Натисніть Send.

  7. Перегляньте Переглядач відповідей у Postman, щоб визначити, чи правильно функціонує вебхук. Якщо повертається повідомлення, відмінне від 200 OK або status: ok, номер, пов’язаний з повідомленням, допомагає визначити проблему.