第三十七章 外部 API

篇别：第九篇 API 与系统集成

本章学习目标

• 使用 XML-RPC、JSON-RPC 从 Python / 其他语言 调用 ORM 方法（execute_kw 等）。
• 理解 会话认证 与 API Key / 外部令牌（若部署启用）的 适用边界。
• 了解 External JSON-2 API 的 设计目标（结构化请求响应、认证、事务），并能对照 官方文档 草拟请求。
• 能制定 从 XML-RPC/JSON-RPC 迁移 的 清单（认证、错误、批处理、分页、字段）。

导读：集成接口是「长期合同」

外部 ERP、电商中台、RPA 常通过 远程 RPC 读写 Odoo。URL、db、uid、认证方式 一旦写死在客户端，升级与灾备切换 成本很高。本章强调：幂等、分页、显式字段列表、错误语义；与 第三十章（安全）、第三十八章（REST/Webhook） 互补——不是所有集成都适合走 RPC。

37.1 XML-RPC

37.1.1 知识要点

• 端点：/xmlrpc/2/common（authenticate、version）、/xmlrpc/2/object（execute_kw）。
• execute_kw(db, uid, password, model, method, args, kwargs)：args 为 位置参数列表；kwargs 为 关键字参数字典。
• 权限：等同 所 impersonate 用户的 ACL + 记录规则；勿 在脚本里硬编码 admin 密码。
• 性能：大列表 用 search + read 分批` 或 search_read + limit/offset；避免 单次拉 全表。
• TLS：生产 必须 HTTPS；证书校验 勿随意 verify=False。

37.1.2 案例

import xmlrpc.client

url = "https://odoo.example.com"
db = "prod"
user = "api_user"
pwd = "***"  # 建议用密钥管理 / API 专用用户 + 强密码轮换

common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, user, pwd, {})
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

rows = models.execute_kw(
    db, uid, pwd,
    "library.book",
    "search_read",
    [[["active", "=", True]]],
    {"fields": ["name", "isbn"], "limit": 5},
)

37.1.3 截图占位

37.1.4 本节练习

1. 实操：在 测试库 用 XML-RPC 创建 并 删除 一条 图书记录（create / unlink）。
2. 简答：为何 execute_kw 的 args 常写成 [[domain]] 双层列表？

参考答案提示：2. 外层是 Python 位置参数列表，内层是 search 的第一个参数 domain。

37.2 JSON-RPC

37.2.1 知识要点

• 端点：常见 /jsonrpc 或 与 Web 客户端相同通道（以版本与部署为准）；请求体为 JSON-RPC 2.0。
• 会话：先 authenticate 拿 session（Cookie 或 头），后续 call_kw。
• 调试：Postman / curl 构造 jsonrpc、method、params；注意 CSRF 与 路由 type（第三十六章）。
• 与 XML-RPC：语义等价 时 择一；浏览器同源 场景多走 JSON-RPC / 内置 rpc。

37.2.2 案例

Postman 思路：POST → Content-Type: application/json → body 含 jsonrpc":"2.0"、method":"call"、params：{service, method, args}（具体字段以 当前 Odoo JSON-RPC 文档 为准）。

37.2.3 截图占位

37.2.4 本节练习

1. 简答：浏览器会话 Cookie 与 API Key（若启用）各自适用场景？
2. 判断：JSON-RPC 天然免疫 CSRF。（ ）

参考答案提示：2. 错；同源策略与 Cookie 仍可能受 CSRF 影响，视 路由与中间件 而定。

37.3 External JSON-2 API（新增）

37.3.1 知识要点

• 目标：比 传统 RPC 更 结构化的请求/响应、更清晰的 认证（如 API Key）、事务/批处理语义（以 Odoo 19 官方文档 为准）。
• 适用：新集成、移动后端、BFF；旧系统可 并行运行 逐步切流。
• 安全：密钥轮换、最小权限用户、IP 允许列表；审计 记录 调用方、耗时、错误码。
• 版本：关注 文档中的版本前缀（如 /api/ 路径），避免 静默 breaking change。

37.3.2 案例（伪代码）

POST /api/v2/library/book/search
Authorization: Bearer <api_key>
Content-Type: application/json

{ "domain": [["active", "=", true]], "fields": ["name"], "limit": 10 }

（真实路径、头名、body 以官方 External API / JSON-2 文档为准。）

37.3.3 截图占位

37.3.4 本节练习

1. 拓展：将一条 read 从 XML-RPC 草拟 为 JSON-2 风格 请求（路径 + body 字段 即可）。
2. 简答：JSON-2 侧如何做 分页 比 offset 无限增大 更健康？

参考答案提示：2. cursor / id 范围（若 API 支持）或 稳定排序 + limit；大 offset 在 PG 上成本高。

37.4 从 XML-RPC/JSON-RPC 迁移指南（新增）

37.4.1 知识要点

37.4.2 案例

并行期：双写读旧 → 灰度读新 → 下线旧端点；监控错误率 与 P95 延迟。

37.4.3 本节练习

1. 清单：列出迁移需改的 5 类 客户端代码（上表扩展亦可）。
2. 简答：幂等 create 在外部重试场景如何实现？

参考答案提示：2. 外部唯一键 映射 ir.model.data 或自定义 UUID 字段 + create 前 search。

本章综合练习

1. 幂等：外部系统重试 create 如何避免 重复单据？（写出 一种 数据模型策略。）
2. 审计：设计 API 调用日志 的 字段（调用方、模型、方法、耗时、状态码 等 不少于 5 项）。
3. 综合：高吞吐同步 选 RPC 批处理 还是 REST + 队列？各写 一句 理由。
4. 安全：集成用户 应 禁止 哪些 UI 权限 仍能通过 RPC 误操作？（举例说明。）

本章对应白皮书目录：第三十七章 外部 API。