Webhooki¶

Ostrzeżenie

Zdecydowanie zaleca się konsultację z programistą, architektem rozwiązań lub inną osobą na stanowisku technicznym przy podejmowaniu decyzji o użyciu webhooków i w trakcie całego procesu implementacji. Jeśli nie są prawidłowo skonfigurowane, webhooki mogą zakłócić działanie bazy danych Odoo i ich cofnięcie może zająć dużo czasu.

Webhooki, które można utworzyć w Odoo Studio, pozwalają na automatyzację działania w bazie danych Odoo, gdy wystąpi określone zdarzenie w innym, zewnętrznym systemie.

W praktyce działa to następująco: gdy zdarzenie wystąpi w systemie zewnętrznym, plik danych („ładunek”) jest wysyłany na adres URL webhooka Odoo za pomocą żądania API POST, a w bazie danych Odoo wykonywana jest predefiniowana akcja.

W przeciwieństwie do zaplanowanych akcji, które uruchamiają się w określonych odstępach czasu, lub ręcznych żądań API, które muszą być jawnie wywołane, webhooki umożliwiają komunikację i automatyzację w czasie rzeczywistym, sterowaną zdarzeniami. Na przykład można skonfigurować webhook, aby dane magazynowe Odoo były automatycznie aktualizowane po potwierdzeniu zamówienia sprzedaży w zewnętrznym systemie punktu sprzedaży.

Konfiguracja webhooka w Odoo nie wymaga kodowania przy łączeniu dwóch baz danych Odoo, ale testowanie webhooka wymaga zewnętrznego narzędzia. Niestandardowe rekordy docelowe lub akcje mogą wymagać umiejętności programowania.

Informacja

Ten artykuł omawia tworzenie webhooka, który otrzymuje dane z zewnętrznego źródła. Możliwe jest jednak również utworzenie zautomatyzowanej akcji, która wysyła dane do zewnętrznego webhooka, gdy w bazie danych Odoo wystąpi zmiana.

Utwórz webhook w Odoo¶

Ważne

Przed wdrożeniem webhooka w aktywnej bazie danych skonfiguruj i przetestuj go przy użyciu zduplikowanej bazy danych, aby upewnić się, że webhook działa zgodnie z zamierzeniem.

Wskazówka

Aktywacja trybu programisty przed utworzeniem webhooka daje większą elastyczność w wyborze modelu, do którego odnosi się reguła automatyzacji. Pozwala również znaleźć nazwę techniczną modelu i pól, która może być potrzebna do skonfigurowania ładunku.

Aby znaleźć nazwę techniczną modelu, z aktywnym trybem programisty, najedź kursorem na nazwę modelu, a następnie kliknij (Wewnętrzny link). Nazwę techniczną można znaleźć w polu Model. Na przykład webhook zamówienia sprzedaży używa modelu Zamówienie sprzedaży, ale w ładunku używana jest nazwa techniczna sale.order.

Aby utworzyć webhook w Studio, postępuj następująco:

Otwórz Studio i kliknij Webhooki, następnie Nowy.
Nadaj webhookowi jasną, znaczącą nazwę identyfikującą jego cel.
Jeśli to konieczne i pod warunkiem, że tryb programisty jest aktywny, wybierz odpowiedni Model z menu rozwijanego. Jeśli tryb programisty nie jest aktywny, reguła automatyzacji domyślnie dotyczy bieżącego modelu.
Adres URL webhooka jest generowany automatycznie, ale w razie potrzeby można go zmienić, klikając Obróć sekret. Jest to adres URL, którego należy użyć podczas implementacji webhooka w systemie zewnętrznym, który będzie wysyłać aktualizacje do bazy danych.

Ostrzeżenie
Adres URL jest poufny i należy obchodzić się z nim ostrożnie. Udostępnianie go online lub bez ostrożności może zapewnić niezamierzony dostęp do bazy danych Odoo. Jeśli adres URL zostanie zaktualizowany po wstępnej implementacji, upewnij się, że został zaktualizowany w systemie zewnętrznym.
Jeśli chcesz, włącz Rejestruj wywołania, aby śledzić historię żądań API wykonanych na adres URL webhooka, np. w celu rozwiązywania problemów.
Jeśli system wysyłający webhook nie jest Odoo, dostosuj kod Rekord docelowy, aby wyszukać rekord JSON zawarty w ładunku podczas wykonywania żądania API na adres URL webhooka. Jeśli system wysyłający webhook jest bazą danych Odoo, upewnij się, że id i model pojawiają się w ładunku.

Jeśli webhook jest używany do tworzenia rekordów w bazie danych Odoo, użyj model.browse(i) lub model.search(i) zamiast domyślnego formatu Rekord docelowy.
Kliknij Dodaj akcję w zakładce Akcje do wykonania, aby zdefiniować akcje do wykonania.
Przed wdrożeniem webhooka w systemie zewnętrznym przetestuj go, aby upewnić się, że działa zgodnie z zamierzeniem.

Wskazówka

Webhooki można również tworzyć za pomocą menu Automatyzacje w Studio, wybierając wyzwalacz Na webhook.
Aby uzyskać dostęp do historii żądań API, jeśli włączono opcję Rejestruj wywołania, kliknij przycisk inteligentny Dzienniki u góry formularza Reguły automatyzacji.
Jeśli celem webhooka jest coś innego niż aktualizacja istniejącego rekordu, np. utworzenie nowego rekordu, należy wybrać akcję Wykonaj kod.

Testowanie webhooka¶

Testowanie webhooka wymaga testowego ładunku oraz zewnętrznego narzędzia lub systemu, takiego jak Postman, do wysłania ładunku za pomocą żądania API POST. Ta sekcja przedstawia kroki testowania webhooka w Postmanie.

Wskazówka

Zobacz sekcję przykładów użycia webhooków, aby uzyskać szczegółowe wyjaśnienia dotyczące testowania webhooków przy użyciu testowych ładunków.
Aby uzyskać konkretną pomoc w testowaniu webhooka za pomocą Postmana, skontaktuj się z ich zespołem wsparcia.

W Postmanie utwórz nowe żądanie HTTP i ustaw jego metodę na POST.
Skopiuj adres URL webhooka z bazy danych Odoo, używając ikony (link), i wklej go w pole adresu URL w Postmanie.
Kliknij zakładkę Body i wybierz raw.
Ustaw typ pliku na JSON, a następnie skopiuj kod z testowego ładunku i wklej go do edytora kodu.
Kliknij Wyślij.

W przeglądarce Odpowiedź u dołu ekranu w Postmanie szczegóły, w tym kod odpowiedzi HTTP, wskazują, czy webhook działa poprawnie.

Komunikat 200 OK lub status: ok wskazuje, że webhook działa prawidłowo po stronie Odoo. Od tego momentu można rozpocząć implementację z innym systemem, aby automatycznie wysyłać żądania API na adres URL webhooka Odoo.
Jeśli zostanie zwrócona jakakolwiek inna odpowiedź, powiązany z nią numer pomaga zidentyfikować problem. Na przykład komunikat 500 Internal Server Error oznacza, że Odoo nie mogło prawidłowo zinterpretować wywołania. W takim przypadku upewnij się, że pola znajdujące się w pliku JSON są prawidłowo zmapowane w konfiguracji webhooka oraz w systemie wysyłającym wywołanie testowe.

Wskazówka

Włączenie rejestrowania wywołań w konfiguracji webhooka w Odoo dostarcza dzienniki błędów, jeśli webhook nie działa zgodnie z zamierzeniem.

Wdrażanie webhooka w systemie zewnętrznym¶

Gdy webhook zostanie pomyślnie utworzony w Odoo i przetestowany, zaimplementuj go w systemie, który wysyła dane do bazy danych Odoo, upewniając się, że żądania API POST są wysyłane na adres URL webhooka.

Przypadki użycia webhooków¶

Poniżej znajdują się dwa przykłady użycia webhooków w Odoo. Dla każdego przykładu udostępniono testowy ładunek, który można znaleźć w sekcji dotyczącej testowania webhooka. Do wysłania testowego ładunku używany jest Postman.

Aktualizacja waluty zamówienia sprzedaży¶

Ten webhook aktualizuje zamówienie sprzedaży w aplikacji Sprzedaż na USD, gdy system zewnętrzny wysyła żądanie API POST na adres URL webhooka zawierające numer tego zamówienia sprzedaży (który jest identyfikowany przez rekord id w ładunku).

Może to być przydatne dla spółek zależnych poza Stanami Zjednoczonymi z firmą macierzystą znajdującą się w Stanach Zjednoczonych lub podczas fuzji, gdy konsolidowane są dane w jednej bazie danych Odoo.

Utwórz webhook¶

Aby utworzyć ten webhook, wykonaj następujące kroki:

Otwórz aplikację Sprzedaż, następnie otwórz Studio i kliknij Webhooks. Model Zamówienie sprzedaży jest domyślnie wybrany.
Kliknij Nowy. Wyzwalacz jest domyślnie ustawiony na Na webhook.
Ustaw Rekord docelowy na model.env[payload.get('_model')].browse(int(payload.get('_id'))), gdzie:
- payload.get('_model') pobiera wartość powiązaną z kluczem model w ładunku, tj. sale.order, który jest nazwą techniczną modelu Zamówienie sprzedaży.
- payload.get('_id') pobiera wartość powiązaną z kluczem id w ładunku, tj. numer docelowego zamówienia sprzedaży w bazie danych Odoo z usuniętym S i zerami wiodącymi.
- int konwertuje pobrany id na liczbę całkowitą, ponieważ metoda browse() może być używana tylko z liczbą całkowitą.
Kliknij Dodaj akcję.
W sekcji Typ kliknij Aktualizuj rekord.
W sekcji Szczegóły akcji wybierz Aktualizuj, wybierz pole Waluta i wybierz USD.
Kliknij Zapisz i zamknij.

Przetestuj webhook¶

Aby przetestować ten webhook, wykonaj następujące kroki:

Mając otwarty Postman, utwórz nowe żądanie HTTP i ustaw jego metodę na POST.
Skopiuj adres URL webhooka Odoo używając ikony (link) i wklej go do pola URL w Postman.
Kliknij zakładkę Body i wybierz raw.
Ustaw typ pliku na JSON, następnie skopiuj ten kod, tj. ładunek, i wklej go do edytora kodu:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
W bazie danych Odoo wybierz zamówienie sprzedaży, na którym chcesz przetestować webhook. W wklejonym kodzie zamień SALES ORDER NUMBER na numer zamówienia sprzedaży bez litery S i bez zer przed numerem. Na przykład zamówienie sprzedaży o numerze S00007 należy wprowadzić jako 7 w Postman.
Kliknij Wyślij.
Sprawdź przeglądarkę odpowiedzi w Postman, aby ustalić, czy webhook działa prawidłowo. Jeśli zwrócony zostanie komunikat inny niż 200 OK lub status: ok, numer powiązany z komunikatem pomaga zidentyfikować problem.

Stwórz nowy kontakt¶

Ten webhook wykorzystuje niestandardowy kod do tworzenia nowego kontaktu w bazie danych Odoo, gdy system zewnętrzny wysyła żądanie API POST na adres URL webhooka zawierające informacje o kontakcie. Może to być przydatne do automatycznego tworzenia nowych dostawców lub klientów.

Utwórz webhook¶

Aby utworzyć ten webhook, wykonaj następujące kroki:

Otwórz aplikację Kontakty, następnie otwórz Studio i kliknij Webhooks. Model Kontakt jest domyślnie wybrany.
Kliknij Nowy. Wyzwalacz jest domyślnie ustawiony na Na webhook.
Ustaw Rekord docelowy na model.browse([2]). Jest to zasadniczo symbol zastępczy, ponieważ kod w akcji automatycznej informuje webhook, co należy pobrać z ładunku i w jakim modelu należy utworzyć rekord.
Kliknij Dodaj akcję.
W sekcji Typ kliknij Wykonaj kod.

Skopiuj ten kod i wklej go do edytora kodu w zakładce Kod sekcji Szczegóły akcji:

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

Kliknij Zapisz i zamknij.

Przetestuj webhook¶

Aby przetestować ten webhook, wykonaj następujące kroki:

W Postman utwórz nowe żądanie HTTP i ustaw jego metodę na POST.
Skopiuj adres URL webhooka Odoo używając ikony (link) i wklej go do pola URL w Postman.
Kliknij zakładkę Body i wybierz raw.

Ustaw typ pliku na JSON, następnie skopiuj ten kod, tj. ładunek, i wklej go do edytora kodu:

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

W wklejonym kodzie zamień CONTACT NAME, CONTACTEMAIL@EMAIL.COM i CONTACT PHONE NUMBER na informacje nowego kontaktu.
Kliknij Wyślij.
Sprawdź przeglądarkę odpowiedzi w Postman, aby ustalić, czy webhook działa prawidłowo. Jeśli zwrócony zostanie komunikat inny niż 200 OK lub status: ok, numer powiązany z komunikatem pomaga zidentyfikować problem.

Edytuj na GitHub