Odoo 15开发手册第九章 外部 API - 集成第三方系统

Odoo 服务端提供有外部 API，可供网页客户端和其它客户端应用使用。本章中我们将学习如何Odoo 的外部 API来实现将其Odoo服务端作为后端的外部应用。

可通过编写脚本来加载或修改Odoo数据，或是集成Odoo现有的业务应用，作为对Odoo应用一种补充。

我们将描述如何使用Odoo RPC调用，然后根据所学知识使用 Python为图书应用创建一个简单的命令行应用。

本章的主要内容有：

• 介绍学习项目：图书目录的客户端应用
• 在客户端机器上配置 Python
• 探索Odoo的外部API
• 实现客户端应用的XML-RPC接口
• 实现客户端应用的用户界面
• 使用OdooRPC库

学完本章后，读者可以创建一个简单的Python应用，使用Odoo作为后端进行查询和数据存储。

开发准备

本文基于​​第三章 Odoo 15开发之创建第一个 Odoo 应用​​创建的代码，具体代码请参见​​ GitHub 仓库​​。应将library_app模块放在addons路径下并进行安装。为保持前后一致，我们将使用​​第二章 Odoo 15开发之开发环境准备​​中的安装操作。本章完成后的代码请参见 ​​GitHub 仓库​​。

学习项目-图书目录客户端

本文中，我们将开发一个简单的客户端应用来管理图书目录。这是一个命令行接口(CLI) 应用，使用 Odoo 来作为后端。应用的功能很基础，核心放在用于与 Odoo服务端交互的技术。

这个简单CLI应用可以完成如下功能：

• 通过标题搜索并列出图书
• 向目录添加新书籍
• 编辑图书标题

我们的主要目标是使用Odoo对外API，因此不希望引用其它读者可能不太熟悉的编程语言。有了这一出发点，最好的方式是就是使用Python来实现客户端应用。不过只要掌握了一种语言的XML-RPC库，相关处理RPC的技术同样适用于其它语言。

这个应用是一个 Python 脚本，等待输入命令来执行操作。示例如下：

$ python3 library.py add "Moby-Dick"
$ python3 library.py list "moby"
60 Moby-Dick
$ python3 library.py set 60 "Moby Dick"

这个示例会话演示了如何使用客户端应用添加、列出及修改图书标题。

该客户端应用通过Python运行，在开始编写客户端应用代码之前，应确保在客户端机器上安装有Python。

在客户端机器上安装 Python

Odoo API 可以在外部通过两种协议访问：XML-RPC和JSON-RPC。任何外部程序，只要是能实现其中一种协议的客户端，就可以与 Odoo 服务端进行交互。为避免引入其它编程语言，我们将保持使用 Python 来探讨外部 API。

到目前为止我们仅在服务端运行了 Python 代码。现在我们要在客户端上使用 Python，所以你可能需要在电脑上做一些额外设置。

要学习本文的示例，你需要能在操作电脑上运行 Python 3 代码。如果在前面已按前面章节配置过开发环境，应该已经就绪了，否则请安装Python。

可通过在命令行终端运行​​python3 --version​​命令来进行确认。如果没有安装，请参考官方网站找到所使用的平台的​​安装包​​。

Ubuntu中通常预安装了 Python 3，如果没有安装，可通过以下命令进行安装：

sudo apt-get install python3 python3-pip

如果你使用的是 Windows 10，可通过微软应用商店进行安装。

在PowerShell中运行python3会直接引导你去相应的下载页面（这算是龟叔去微软后增加的福利吗？）。

通过一键安装包安装了Odoo的Windows用户可能会奇怪为什么Python解释器没有准备就绪。这时需要进行额外的安装。简单地说是因为 Odoo一键安装包内置了Python解析器，在操作系统层面无法直接使用。

现在读者已经安装好了Python，就可以开始使用Odoo对外API了。

学习Odoo外部 API

在实现客户端应用前应当先熟悉下Odoo外部API。以下小节中使用Python解释器一探XML-RPC API。

使用XML-RPC连接 Odoo API

访问Odoo服务最简单的方法是使用XML-RPC，我们可以使用 Python 标准库中的​​xmlrpclib​​来实现。

不要忘记我们是要编写客户端程序连接服务端，因此需运行 Odoo 服务端实例来供连接。本例中我们假设 Odoo 服务端实例在同一台机器上运行，​​http://localhost:8069​​，但读者可以使用任意运行着服务的其它机器，只需能连接其IP地址或服务器名。

Odoo的 xmlrpc/2/common端点暴露了公共方法，无需登录即可访问。可用于查看服务端版本及检测登录信息。我们使用xmlrpc库来研究对外可访问的Odoo API common。

首先打开 Python 3终端并输入如下代码：

>>> from xmlrpc import client
>>> srv = "http://localhost:8069"
>>> common = client.ServerProxy("%s/xmlrpc/2/common" % srv)
>>> common.version()
{'server_version': '15.0', 'server_version_info': [15, 0, 0, 'final', 0, ''], 'server_serie': '15.0', 'protocol_version': 1}

以上代码导入了xmlrpc库，然后创建了一个包含服务端地址和监听端口信息的变量。请根据自身状况进行修改（如 Alan 使用srv = 'http://192.168.0.12:8069'）。

下一步访问服务端公共服务（无需登录），在/xmlrpc/2/common端点上暴露。其中一个可用方法是version()，用于查看服务端版本。我们使用它来确认可与服务端进行通讯。

另一个公共方法是authenticate()。该方法确认用户名和密码可被接受，返回的用户 ID可用于后续请求。示例如下：

>>> db, user, password = "odoo-dev", "admin", "admin"
>>> uid = common.authenticate(db, user, password, {})
>>> print(uid)
2

authenticate()方法接收4个参数：数据库名、用户名、密码以及user agent。些前的代码通过变量存储这些信息，然后将使用这些变量传参。

ODOO 14中发生的改变

Odoo 14支持API密钥，可使用它来获取Odoo API外部访问权限。API密钥可在用户的首选项（Preferences）表单中进行设置，位于账号安全（Account Security）标签下。

用户代理(User Agent)环境用于提供有关客户端的元信息。为必填项，至少应传一个空字典{}。

若验证失败，返回值为False。

common公共端点内容非常有限，要访问ORM API或是其它端点则需要先进行账号验证。

使用XML-RPC运行服务器端方法

要访问Odoo的模型及方法，需要使用xmlrpc/2/object。该端点要求先登录才能请求。

这个端点暴露了一个通用的execute_kw方法，接收模型名称、要调用的方法以及传递给方法的参数列表。

下面有一个演示execute_kw的示例。它调用了search_count方法，返回匹配域过滤器的记录数：

>>> api = client.ServerProxy('%s/xmlrpc/2/object' % srv)
>>> api.execute_kw(db, uid, password, 'res.users', 'search_count', [[]])
3

此处我们使用了xmlrpc/2/endpoint对象访问服务端 API。调用的方法名为execute_kw()，接收如下参数：

• 连接的数据库名
• 连接用户ID
• 用户密码（或API密钥）
• 目标模型名称
• 调用的方法
• 位置参数列表
• 可选的关键字参数字典(本例中未使用)

可调用所有的模型方法，以下划线(_)开头的除外，这些是私有方法。有些的方法的返回值如果无法通过XML-RPC发送，则无法使用XML-RPC协议调用。browse()方法就属于这种情况，它返回的是一个记录集对象。使用XML-RPC调用browse()会返回TypeError: cannot marshal objects的报错。在进行XML-RPC调用时应将browse()换成read或是search_read，所返回的数据格式可通过XML-RPC协议发送给客户端。

下面我们就来看看如何通过search和read查询Odoo数据。

使用API方法search和read

Odoo的服务端使用browse来查询记录。在RPC客户端中无法使用它，因为记录集对象无法通过RPC协议进行传输。这时应当使用read方法。

read([, [])和browse方法类似，但它返回的不是记录集，而是记录列表。每条记录都是包含请求字段及数据的字典。

下面来看如何通过read()从Odoo获取数据：

>>> api = client.ServerProxy("%s/xmlrpc/2/object" % srv)
>>> api.execute_kw(db, uid, password, "res.users", "read", [2, ["login", "name", "company_id"]])
[{'id': 2, 'login': 'admin', 'name': 'Mitchell Admin', 'company_id': [1, 'YourCompany']}]

上例对res.users模型调用了read方法，传入了两个位置参数：记录ID 2 （也可以使用ID列表）以及获取字段的列表["login", "name", "company_id"]，没传递关键字参数。

得到结果是一个字典列表，其中每个字典对应一条记录。对多字段的值有一种具体的表现形式。由记录ID和记录显示名组成的一对。例如，上例中返回的company_id的值为[1, 'YourCompany']。

可能会不知道记录ID，这时需要使用search调用来查找到匹配域过滤器的那些记录ID。

例如，想要查找管理员用户时，可使用[("login", "=", "admin")]。这一RPC调用如下：

>>> domain = [("login", "=", "admin")]
>>> api.execute_kw(db, uid, password, "res.users", "search", [domain])
[2]

其结果是仅有一个元素（2）的列表，元素为admin用户的ID。

经常会使用search结合read方法查找符合域过滤器条件的ID，然后再获取它们的数据。在客户端应用中，这会反复调用服务端。可通过search_read方法进行简化，它可以一步就执行以上两个操作。

下例为使用search_read来查找admin用户并返回其名称：

>>> api.execute_kw(db, uid, password, "res.users", "search_read", [domain, ["login", "name"]])
[{'id': 2, 'login': 'admin', 'name': 'Mitchell Admin'}]

这个search_read方法使用了两个位置参数：包含域过滤器的列表，以及另一个包含需获取字段的列表。

search_read的参数如下：

• domain：域过滤器表达式列表
• fields：待获取字段名称列表
• offset：跳过的记录数或用于分页
• limit：返回的最大记录数
• order：用于ORDER BY语句的字符串

对read和search_read，fields均为可选参数。如未提供，会获取所有的模型字段。但这可能会使用到大开销的字段计算并且会返回大量无需使用的数据。因此建议显式地提供字段列表。

execute_kw调用既可使用位置参数也可使用关键字参数。以下是把位置参数换成关键字参数的示例：

>>> api.execute_kw(db, uid, password, "res.users", "search_read", [], {"domain": domain, "fields": ["login", "name"]})
[{'id': 2, 'login': 'admin', 'name': 'Mitchell Admin'}]

获取数据时最常使用的就是search_read，但还存在其它方法用于写入数据或触发其它业务逻辑。

调用其它API方法

所有的其它模型方法也通过RPC对外暴露，那以下划线开头的私有方法除外。也就是说可以调用create、write和unlink来修改服务端的数据。

我们来看一个例子。以下代码新建一条partner记录，然后修改记录，再读取记录确定是否写入了修改，最后进行了删除：

>>> x = api.execute_kw(db, uid, password, "res.partner",
... "create",
... [{'name': 'Packt Pub'}])
>>> print(x)
63
>>> api.execute_kw(db, uid, password, "res.partner",
... "write",
... [[x], {'name': 'Packt Publishing'}])
True
>>> api.execute_kw(db, uid, password, "res.partner",
... "read",
... [[x], ["name"]])
[{'id': 63, 'name': 'Packt Publishing'}]
>>> api.execute_kw(db, uid, password, "res.partner",
... "unlink",
... [[x]])
True
>>> api.execute_kw(db, uid, password, "res.partner",
... "read",
... [[x]])
[]

XML-RPC的一个限制是它不支持None值。有一个XML-RPC插件可支持None值，但这取决于客户端使用的XML-RPC库。没有返回值的方法可能无法使用XML-RPC，因为这些方法隐式地返回None。这也是为什么方法的最佳实践要求有返回值，至少应返回True。另一个选择是使用JSON-RPC。OdooRPC库支持该协议，本文的使用OdooRPC库一节中会用到它。

模型中以下划线开头的方法被看作私有方法，无法通过XML-RPC对外暴露。

小贴士：通常客户端应用希望复制用户在Odoo表单中输入的内容。调用create()方法可能还不够，因为表单可能会使用onchange方法自动化操作一些字段，这通过表单交互触发，没经过create()。解决方案是在Odoo中创建一个自定义方法，其中使用create()方法并运行onchange方法中的操作。

有必须反复说明一下，Odoo的对外API大部分编程语言都可以使用。​​官方文档​​中包含有Ruby、PHP和Java使用示例。

至此，我们已学习到如何使用XML-RPC协议调用Odoo方法。接下来我们使用它来构建图书目录客户端应用。

实现图书客户端XML-RPC 接口

下面就来实现图书目录客户端应用。

可分为两个文件：一个是包含服务端后台的Odoo后台接口，library_xmlrpc.py，另一个用于用户界面，library.py。这让我们可以对后台接口使用替代的实现。

先从Odoo后台组件开始，LibraryAPI类用于配置与Odoo服务端之间连接，以支持与Odoo交互所需的方法。所要实现的方法有：

• search_read(