Webhooks¶

警告

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

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

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

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

当连接两个 Odoo 数据库时，在 Odoo 中设置网络钩子无需编码，但测试网络钩子需要外部工具。自定义目标记录或操作可能需要编程技能。

注解

本文涉及创建一个可从外部来源*接收*数据的网络钩子。然而，也可以创建一个自动操作，当 Odoo 数据库发生变化时，该操作向外部网络钩子发送数据。

在 Odoo 中创建网络钩子¶

重要

在实时数据库中实施网络钩子之前，请使用重复数据库对其进行配置和测试，以确保网络钩子按预期运行。

小技巧

:ref:` 在创建网络钩子之前激活开发者模式 <developer-mode>`，可以更灵活地选择自动化规则的目标模型。它还支持您找到模型和字段的技术名称，这可能是配置有效载荷所需要的。

要查找模型的技术名称，请在激活开发者模式后将鼠标悬停在模型名称上，然后点击（内部链接）。技术名称可在模型字段中找到。例如，销售订单网络钩子使用 销售订单 模型，但在有效载荷中使用了技术名称 sale.order。

在**Studio**中创建网络钩子的步骤如下：

打开 Studio 并点击网络钩子，然后点击新建。
给网络钩子起一个清晰、有意义的名字，以明确其目的。
如果需要，并已激活开发者模式，请从下拉菜单中选择相应的模型。如果未激活开发者模式，自动化规则默认以当前模型为目标。
网络钩子的 URL 会自动生成，但可根据需要通过点击轮换密钥进行更改。这是在外部系统中实施网络钩子时应使用的 URL，该系统将向数据库发送更新。

警告
此 URL 具有**机密性**，需谨慎处理。在网络上或不加防范地分享可能会导致意外访问 Odoo 数据库。如果 URL 在初始部署后有更新，请务必在外部系统中同步更新。
如需要，请启用记录调用以追踪向网络钩子的 URL 发送的 API 请求的历史记录，例如，用于故障排除。
如果发送网络钩子的系统并非 Odoo，请调整 :guilabel:`目标记录`的代码，使其能在 API 请求发送至网络钩子 URL 时，从有效负载中寻找相应的 JSON 记录。如果发送网络钩子的系统是 Odoo 数据库，请确保 id 和 model 出现在有效负载中。

如果该网络钩子用于在 Odoo 数据库中创建记录，请使用 model.browse(i) 或 model.search(i)，而不是默认的 :guilabel:`目标记录`格式。
点击待办操作选项卡中的添加操作以定义要执行的操作。
在外部系统中实施网络钩子之前，请测试以确保其按预期运行。

小技巧

网络钩子也可通过**Studio**中的 :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:`通过网络钩子。
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() 方法仅能接收整型参数。
点击添加操作。
在类型部分，点击更新记录。
在操作详情部分，选择更新，选取字段货币，并选择美元。
点击保存并关闭。

测试网络钩子¶

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

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

新建联系人¶

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

创建网络钩子¶

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

打开**联系人**应用，然后打开定制 <studio/access>`并点击:guilabel:`Webhooks。系统默认已选择*联系人*模型。
点击新建。默认情况下，触发器`设置为:guilabel:`通过网络钩子。
将目标记录设置为 model.browse([2])。这基本上是一个占位符，因为自动操作中的代码会告诉网络钩子需要从有效负载中检索什么，以及需要在哪个模型中创建记录。
点击添加操作。
In the Type section, click Execute Code.

复制此代码并将其粘贴到操作详情部分代码选项卡的代码编辑器中：

# 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 中的回应查看器以确定网络钩子是否正常运行。如果返回的信息不是 200 OK`或 `status: ok，则与信息相关的编号有助于确定问题所在。

Edit on GitHub