Webhooks钩子¶

警告

It is highly recommended to consult with a developer, solution architect, or another technical role when deciding to use webhooks and throughout the implementation process. If not properly configured, webhooks may disrupt the Odoo database and can take time to revert.

在 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 （内部链接）。技术名称可在模型字段中找到。例如，销售订单网络钩子使用的是*销售订单*模型，但在数据负载中使用的则是其技术名称 sale.order。

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

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

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

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

小技巧

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

测试网络钩子¶

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

小技巧

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

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

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

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

小技巧

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

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

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

Webhook use cases¶

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

Update a sales order’s currency¶

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

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

创建网络钩子¶

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

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

Test the webhook¶

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

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

Create a new contact¶

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

创建网络钩子¶

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

打开**联系人**应用，然后打开定制 <studio/access>`并点击 :guilabel:`Webhooks 。系统默认已选择*联系人*模型。
点击新建。默认情况下，触发器设置为通过网络钩子。
将目标记录设置为 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'")

点击保存并关闭。

Test the webhook¶

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

在 Postman 中，创建一个新的 HTTP 请求，并将其方法设置为 POST 。
使用 :guilabel:`(链接)`图标复制 Odoo 网络钩子的 URL，并将其粘贴到 Postman 的 URL 字段中。
点击 Body 标签页并选择 raw 。

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

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

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