Webhooks¶

警告

webhookの使用を決定する際、および実装プロセス全体を通じて、開発者、ソリューションアーキテクト、またはその他の技術的役割を持つ人に相談することを*強く推奨*します。適切に設定されていない場合、webhookはOdooデータベースを中断させる可能性があり、元に戻すのに時間がかかることがあります。

**Odoo ワンルーム**で作成できるWebhookを使用すると、別の外部システムで特定のイベントが発生したときに、Odoo データベース内のアクションを自動化できます。

実際には、次のように機能します: 外部システムでイベントが発生すると、データファイル（「ペイロード」）が`POST` APIリクエストを介してOdoo WebhookのURLに送信され、Odoo データベースで事前定義されたアクションが実行されます。

事前定義された間隔で実行されるスケジュール済アクションや、明示的に呼び出す必要がある手動APIリクエストとは異なり、Webhookはリアルタイムのイベント駆動型通信と自動化を可能にします。たとえば、外部POSシステムで販売オーダが確定されたときに、Odoo 在庫データが自動的に更新されるようにWebhookを設定できます。

Odoo でWebhookを設定する場合、2つのOdoo データベースを接続するときはコーディングは必要ありませんが、:ref:`Webhookのテスト <studio/webhooks/test-webhook>`には外部ツールが必要です。:ref:`カスタムターゲットレコードまたはアクション <studio/webhooks/webhook-example>`には、プログラミングスキルが必要な場合があります。

注釈

この記事では、外部ソースからデータを*受信*するWebhookの作成について説明します。ただし、Odoo データベースで変更が発生したときに、:ref:`外部Webhookにデータを送信する <studio/automated-actions/action-webhook>`自動アクションを作成することも可能です。

Odoo でWebhookを作成¶

重要

本番のデータベースでWebhookを実装する前に、:ref:`複製データベース <odoo-online/duplicate>`を使用して設定とテストを行い、Webhookが意図したとおりに動作することを確認してください。

ちなみに

Webhookを作成する前に:ref:`開発者モードを有効化 <developer-mode>`すると、自動化ルールがターゲットとする:doc:`モデル <../models_modules_apps>`を選択する際の柔軟性が高まります。また、モデルとフィールドの技術名を確認できるため、ペイロードの設定に必要になる場合があります。

モデルの技術名を確認するには、開発者モードを有効化した状態で、モデル名にカーソルを合わせてから:icon:fa-arrow-right :guilabel:`(内部リンク)`をクリックします。技術名は:guilabel:`モデル`フィールドで確認できます。たとえば、販売オーダWebhookは*販売オーダ*モデルを使用しますが、ペイロードでは技術名`sale.order`が使用されます。

**ワンルーム**でWebhookを作成するには、次の手順に従います:

ワンルームを開き、:guilabel:`Webhook`をクリックしてから、:guilabel:`新規`をクリックします。
Webhookに、その目的を識別する明確で意味のある名前を付けます。
必要に応じて、開発者モードが有効化されている場合は、ドロップダウンから適切な:guilabel:`モデル`を選択します。開発者モードが有効化されていない場合、自動化ルールはデフォルトで現在のモデルを対象とします。
webhookのURLは自動的に生成されますが、必要に応じて:guilabel:`シークレットをローテーション`をクリックして変更できます。これは、データベースに更新を送信する外部システムでwebhookを実装する際に使用すべきURLです。

警告
このURLは**機密情報**であり、慎重に取り扱う必要があります。オンラインで共有したり、不用意に扱ったりすると、Odooデータベースへの意図しないアクセスを許可する可能性があります。初期実装後にURLが更新された場合は、外部システムでも必ず更新してください。
必要に応じて、:guilabel:`呼び出しをログ記録`を有効にして、webhookのURLに対して行われたAPIリクエストの履歴を追跡します(例:トラブルシューティング目的)。
webhookを送信するシステムがOdooでない場合は、:guilabel:`対象レコード`のコードを調整して、webhookのURLに対してAPIリクエストが行われた際にペイロードに含まれるJSONレコードを検索するようにします。webhookを送信するシステムがOdooデータベースの場合は、ペイロードに`id`と`model`が含まれていることを確認してください。

webhookを使用してOdooデータベースにレコードを作成する場合は、デフォルトの:guilabel:`対象レコード`形式ではなく、`model.browse(i)`または`model.search(i)`を使用してください。
:guilabel:`実行するアクション`タブで:guilabel:`アクションを追加`をクリックして、実行する:ref:`アクション <studio/automated-actions/action>`を定義します。
外部システムにwebhookを実装する前に、意図したとおりに動作することを確認するために:ref:`テスト <studio/webhooks/test-webhook>`してください。

ちなみに

webhookは、**ワンルーム**の:guilabel:`自動化`メニューからトリガー:guilabel:`webhookで`を選択して作成することもできます。
:guilabel:`呼び出しをログ記録`が有効化されている場合にAPIリクエストの履歴にアクセスするには、:guilabel:`自動化ルール`フォームの上部にある:guilabel:`ログ`スマートボタンをクリックします。
webhookの目的が既存のレコードの更新以外の場合(例:新しいレコードの作成)、:guilabel:`コードを実行`アクションを選択する必要があります。

webhookをテストする¶

webhookをテストするには、テストペイロードと、Postman<https://www.postman.com/>`_のような外部ツールまたはシステムが必要です。これらを使用して`POST APIリクエストでペイロードを送信します。このセクションでは、Postmanでwebhookをテストする手順を説明します。

ちなみに

テストペイロードを使用してwebhookをテストする方法の詳細な手順については、:ref:`webhookユースケースセクション <studio/webhooks/webhook-examples>`を参照してください。
Postmanでのwebhookテストに関する具体的なサポートが必要な場合は、Postmanのサポートチームにお問い合わせください。

Postmanで新しいHTTPリクエストを作成し、そのメソッドを:guilabel:`POST`に設定します。
Odooデータベースから:icon:fa-link :guilabel:`(リンク)`アイコンを使用してwebhookのURLをコピーし、PostmanのURLフィールドに貼り付けます。
:guilabel:`本文`タブをクリックし、:guilabel:`raw`を選択します。
ファイルタイプを:guilabel:`JSON`に設定してから、テストペイロードからコードをコピーしてコードエディタに貼り付けます。
:guilabel:`送信`をクリックします。

画面下部のPostmanの:guilabel:`Response`ビューアには、HTTPレスポンスコードを含む詳細が表示され、Webhookが正しく機能しているかどうかを示します。

`200 OK`または`status: ok`のメッセージは、WebhookがOdoo側で正常に機能していることを示します。ここから、他のシステムとの実装を開始して、OdooのWebhookのURLに自動的にAPIリクエストを送信できるようになります。
他のレスポンスが返された場合、それに関連付けられた番号が問題の特定に役立ちます。たとえば、`500 Internal Server Error`メッセージは、Odooが呼び出しを正しく解釈できなかったことを意味します。この場合、JSONファイル内のフィールドが、Webhookの設定とテスト呼び出しを送信するシステムで適切にマッピングされていることを確認してください。

ちなみに

OdooのWebhook設定で呼び出しログを有効にすると、Webhookが意図したとおりに機能していない場合にエラーログが提供されます。

外部システムでWebhookを実装する¶

OdooでWebhookが正常に作成され、テストされたら、Odooデータベースにデータを送信するシステムに実装し、POST APIリクエストがWebhookのURLに送信されるようにします。

webhookのユースケース¶

以下は、OdooでWebhookを使用する2つの例です。各例にはテストペイロードが用意されており、Webhookのテストに関するセクションで確認できます。テストペイロードの送信には`Postman <https://www.postman.com/>`_が使用されます。

販売オーダの通貨を更新する¶

このWebhookは、外部システムがその販売オーダ番号を含む`POST` APIリクエストをWebhookのURLに送信すると、**販売**アプリの販売オーダを`USD`に更新します(ペイロードの`id`レコードで識別されます)。

これは、米国内に母会社がある米国外の子会社や、合併時に1つのOdooデータベースにデータを統合する場合に役立つ可能性があります。

Webhookを作成する¶

このWebhookを作成するには、次の手順を実行します。

**販売**アプリを開き、ワンルームを開き、:guilabel:`Webhooks`をクリックします。デフォルトで*販売オーダ*モデルが選択されています。
:guilabel:`新規`をクリックします。:guilabel:`トリガー`はデフォルトで:guilabel:`Webhook時`に設定されています。
Set the Target Record to model.env[payload.get('model')].browse(int(payload.get('id'))), where:
- payload.get('model') retrieves the value associated with the model key in the payload, i.e., sale.order, which is the technical name of the Sales Order model.
- payload.get('id') retrieves the value associated with the id key in the payload, i.e., the number of the target sales order in your Odoo database with the S and leading zeros removed.
- `int`は、取得したIDを整数(つまり、整数)に変換します。これは、`browse()`メソッドが整数でのみ使用できるためです。
:guilabel:`アクションを追加`をクリックします。
:guilabel:`タイプ`セクションで、:guilabel:`レコードを更新`をクリックします。
:guilabel:`アクションの詳細`セクションで、:guilabel:`更新`を選択し、:guilabel:`通貨`フィールドを選択して、:guilabel:`USD`を選択します。
:guilabel:`保存して閉じる`をクリックします。

webhookをテストする¶

このWebhookをテストするには、次の手順に従います:

`Postman <https://www.postman.com/>`_を開き、新しいHTTPリクエストを作成して、メソッドを:guilabel:`POST`に設定します。
:guilabel:`(リンク)`アイコンを使用してOdoo WebhookのURLをコピーし、PostmanのURLフィールドに貼り付けます。
:guilabel:`本文`タブをクリックし、:guilabel:`raw`を選択します。
ファイルタイプを:guilabel:`JSON`に設定し、次のコード(ペイロード)をコピーしてコードエディタに貼り付けます:
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
Odooデータベースで、Webhookをテストする販売オーダを選択します。貼り付けたコードで、`SALES ORDER NUMBER`を販売オーダの番号に置き換えます。その際、`S`や番号の前のゼロは含めません。たとえば、番号が`S00007`の販売オーダは、Postmanでは`7`と入力します。
:guilabel:`送信`をクリックします。
Postmanの:ref:`レスポンスビューア <studio/webhooks/test-webhook-response>`を確認して、Webhookが正常に機能しているかどうかを判断します。`200 OK`または`status: ok`以外のメッセージが返された場合、メッセージに関連付けられた番号が問題の特定に役立ちます。

新規連絡先を作成¶

このWebhookは、外部システムがWebhookのURLに連絡先情報を含む`POST` APIリクエストを送信したときに、Odooデータベースに新しい連絡先を作成するカスタムコードを使用します。これは、新しい仕入先や顧客を自動的に作成する際に役立ちます。

Webhookを作成する¶

このWebhookを作成するには、次の手順を実行します。

**連絡先**アプリを開き、ワンルームを開いて、:guilabel:`Webhooks`をクリックします。デフォルトで*連絡先*モデルが選択されています。
:guilabel:`新規`をクリックします。:guilabel:`トリガー`はデフォルトで:guilabel:`Webhook時`に設定されています。
:guilabel:`対象レコード`を`model.browse([2])`に設定します。これは本質的にプレースホルダであり、自動アクションのコードがペイロードから取得する必要があるものと、レコードを作成する必要があるモデルをWebhookに指示します。
:guilabel:`アクションを追加`をクリックします。
:guilabel:`タイプ`セクションで、:guilabel:`コードを実行`をクリックします。

このコードをコピーして、:guilabel:`アクションの詳細`セクションの:guilabel:`コード`タブのコードエディタに貼り付けます:

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

:guilabel:`保存して閉じる`をクリックします。

webhookをテストする¶

このWebhookをテストするには、次の手順に従います:

`Postman <https://www.postman.com/>`_で、新しいHTTPリクエストを作成して、メソッドを:guilabel:`POST`に設定します。
:guilabel:`(リンク)`アイコンを使用してOdoo WebhookのURLをコピーし、PostmanのURLフィールドに貼り付けます。
:guilabel:`本文`タブをクリックし、:guilabel:`raw`を選択します。
ファイルタイプを:guilabel:`JSON`に設定し、次のコード(ペイロード)をコピーしてコードエディタに貼り付けます:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
貼り付けたコードで、CONTACT NAME、CONTACTEMAIL@EMAIL.COM、および`CONTACT PHONE NUMBER`を新しい連絡先の情報に置き換えます。
:guilabel:`送信`をクリックします。
Postmanの:ref:`レスポンスビューア <studio/webhooks/test-webhook-response>`を確認して、Webhookが正常に機能しているかどうかを判断します。`200 OK`または`status: ok`以外のメッセージが返された場合、メッセージに関連付けられた番号が問題の特定に役立ちます。

GitHub で編集