Webhooks¶

警告

*强烈建议*在决定使用网络钩子和整个实施过程中咨询开发人员、解决方案架构师或其他技术人员。如果配置不当，网络钩子可能会扰乱 Odoo 数据库，并可能需要一段时间才能恢复。

在 Odoo 定制 中创建的网络钩子（Webhooks）允许您在外部系统发生特定事件时，自动触发 Odoo 数据库中的相应动作。

其实际运作流程如下：当外部系统发生事件时，会通过 POST API 请求将一个数据文件（即“数据负载”）发送至 Odoo 网络钩子的 URL，随后在您的 Odoo 数据库中执行预定义的操作。

与按预定间隔运行的定时动作，或需显式调用的手动 API 请求不同，网络钩子实现了实时、事件驱动的通信与自动化。例如，您可以设置一个网络钩子，以便在外部销售点系统中确认销售订单时，自动更新您的 Odoo 库存数据。

在 Odoo 中设置网络钩子时，若连接的是两个 Odoo 数据库则无需编写代码；但测试网络钩子需要使用外部工具。如需实现自定义目标记录或操作，则可能需要编程技能。

注解

本文主要介绍如何创建用于*接收*外部数据源数据的网络钩子。当然，您同样可以创建自动化动作，在 Odoo 数据库发生变更时将数据发送至外部网络钩子。

在 Odoo 中创建网络钩子¶

重要

Before implementing a webhook in a live database, configure and test it using a duplicate database to ensure the webhook performs as intended.

小技巧

在创建网络钩子前启用开发者模式，可让您在选择自动化规则目标的模型时更加灵活。同时，您也能借此查看模型和字段的技术名称，这些信息在配置数据负载时可能会用到。

要查找模型的技术名称，需在启用开发者模式后，将鼠标悬停于模型名称上并点击 :icon:fa-arrow-right （内部链接）。技术名称可在 :guilabel:`模型`字段中找到。例如，销售订单网络钩子使用的是*销售订单*模型，但在数据负载中使用的则是其技术名称 sale.order。

若要在**定制**中创建网络钩子，请按以下步骤操作：

打开定制，点击网络钩子，然后选择新建。
为网络钩子设定一个清晰、有意义的名称，以明确其用途。
如有需要，并在已启用开发者模式的前提下，从下拉菜单中选择相应的模型。若未启用开发者模式，则自动化规则默认以当前模型为目标。
网络钩子的 URL 将自动生成，但必要时可点击 :guilabel:`重置密钥`进行更改。此 URL 需在向数据库发送更新的外部系统中配置网络钩子时使用。

警告
该 URL 为**机密**，务必妥善保管。在网络上或不加谨慎地分享此 URL，可能导致对 Odoo 数据库的未经授权的访问。若在初次部署后更新了此 URL，请确保同步在外部系统中进行更新。
如需要，可启用 :guilabel:`记录调用`功能来追踪向网络钩子 URL 发起的 API 请求历史，例如用于故障排除。
若发送网络钩子的系统非 Odoo，请调整 :guilabel:`目标记录`代码，以查找向网络钩子 URL 发起 API 请求时数据负载中包含的 JSON 记录。若发送网络钩子的系统为 Odoo 数据库，请确保数据负载中包含`id`和`模型`字段。

若网络钩子用于在 Odoo 数据库中创建记录，请使用 model.browse(i) 或 model.search(i) 替代默认的 :guilabel:`目标记录`格式。
点击 :guilabel:` 待执行操作`标签页中的添加操作来定义需执行的操作。
在外部系统中部署网络钩子前，请先对其进行测试，以确保其按预期工作。

小技巧

网络钩子也可通过**定制**中的 :guilabel:`自动化`菜单创建，只需选择 :guilabel:`通过网络钩子`作为触发器。
如需查看已启用记录调用功能的 API 请求历史，请点击自动化规则表单顶部的日志智能按钮。
若网络钩子的用途并非更新现有记录（例如需创建新记录），则必须选择 :guilabel:`执行代码`操作。

测试网络钩子¶

测试网络钩子需要准备测试数据负载，并使用外部工具或系统，如`Postman <https://www.postman.com/>_`，通过`POST` API 请求发送数据负载。本节介绍在 Postman 测试网络钩子的步骤。

小技巧

关于如何使用测试数据负载测试网络钩子的逐步说明，请参阅网络钩子用例部分。
如需获取使用 Postman 测试网络钩子的具体帮助，请联系其支持团队。

在 Postman 中创建新的 HTTP 请求，并将其方法设置为:guilabel:POST
使用:icon:fa-link:guilabel:` （链接）` 图标从您的 Odoo 数据库复制网络钩子 URL，并将其粘贴到 Postman 的URL字段中。
点击 Body`标签页并选择 :guilabel:`raw。
将文件类型设置为 JSON，然后从测试数据负载中复制代码并粘贴到代码编辑器中。
点击发送。

在 Postman 屏幕底部的响应查看器中，包括 HTTP 响应代码在内的详细信息会显示网络钩子是否正常运行。

收到 200 OK 或 status: ok 响应消息，表明网络钩子在 Odoo 端运行正常。至此，可以开始与另一系统进行实施，以自动向 Odoo 网络钩子的 URL 发送 API 请求。
若返回任何其他响应，其关联的状态码有助于识别问题。例如，500 内部服务器错误 消息表示 Odoo 无法正确解析该调用。遇到此情况，请确保 JSON 文件中的字段已在网络钩子配置及发送测试调用的系统中正确映射。

小技巧

若网络钩子未按预期运行，在 Odoo 的网络钩子配置中开启调用日志记录功能可提供错误日志。

在外部系统中实施网络钩子¶

当网络钩子在 Odoo 中成功创建并测试通过后，即可在向 Odoo 数据库发送数据的系统中实施，确保将`POST`API 请求发送至网络钩子的 URL。

网络钩子使用案例¶

以下是两个在 Odoo 中使用网络钩子的示例。每个示例均提供了测试数据负载，可在测试网络钩子的相关章节找到。示例中使用`Postman <https://www.postman.com/>`_ 发送测试数据负载。

更新销售订单币种¶

当外部系统向网络钩子 URL 发送包含特定**销售**订单编号（由数据负载的 id 记录标识）的`POST`API 请求时，此网络钩子会将销售应用中的对应销售订单更新为 USD。

这对于位于美国境外但母公司在美国境内的子公司，或在合并过程中将数据整合至一个 Odoo 数据库时非常有用。

创建网络钩子¶

要创建此网络钩子，请按以下步骤操作：

打开销售应用程序，然后打开定制并点击网络钩子。默认选择*销售订单*模型。
点击新建。默认情况下，触发器`设置为:guilabel:`通过网络钩子。
将目标记录设置为 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() 方法仅能接收整型参数。
点击添加操作
在类型部分，点击更新记录。
在操作详情部分，选择更新，选取字段货币，并选择美元。
点击保存并关闭。

测试网络钩子¶

测试网络钩子的步骤如下：

打开 Postman <https://www.postman.com/>，创建一个新的 HTTP 请求并将其方法设置为 POST。
使用 :guilabel:`(链接)`图标复制 Odoo 网络钩子的 URL，并将其粘贴到 Postman 的 URL 字段中。
点击 Body`标签页并选择 :guilabel:`raw。
将文件类型设置为 JSON，然后复制以下代码（即数据负载）并粘贴到代码编辑器中：
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
在您的 Odoo 数据库中选择一个销售订单来测试网络钩子。在粘贴的代码中，将`SALES ORDER NUMBER`替换为销售订单的编号（需移除字母 S 及数字前的所有零）。例如，编号为`S00007`的销售订单在 Postman 中应输入为`7`。
点击发送。
查看 Postman 中的回复查看器以确定 webhook 是否正常运行。如果返回的信息不是`200 OK`或`status: ok`，则与信息相关的编号有助于确定问题所在。

新建联系人¶

当外部系统向网络钩子 URL 发送包含联系人信息的`POST`API 请求时，此网络钩子使用自定义代码在 Odoo 数据库中创建一个新联系人。这有助于自动创建新的供应商或客户。

创建网络钩子¶

要创建此网络钩子，请按以下步骤操作：

打开**联系人**应用，然后打开定制 <studio/access>`并点击:guilabel:`Webhooks。系统默认已选择*联系人*模型。
点击新建。默认情况下，触发器`设置为:guilabel:`通过网络钩子。
将目标记录设置为 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 <https://www.postman.com/>`_中，创建一个新的 HTTP 请求，并将其方法设置为 :guilabel:`POST。
使用 :guilabel:`(链接)`图标复制 Odoo 网络钩子的 URL，并将其粘贴到 Postman 的 URL 字段中。
点击 Body`标签页并选择 :guilabel:`raw。

将文件类型设置为 JSON，然后复制以下代码（即数据负载）并粘贴到代码编辑器中：

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

在粘贴的代码中，用新联系人的信息替换 联系人姓名、CONTACTEMAIL@EMAIL.COM 和 联系人电话号码。
点击发送。
查看 Postman 中的回复查看器以确定 webhook 是否正常运行。如果返回的信息不是`200 OK`或`status: ok`，则与信息相关的编号有助于确定问题所在。

Edit on GitHub