Odoo Web API调用方式

wen PHP项目 2026-07-22 2

Odoo Web API调用方式全解析：从入门到实战

目录导读

Odoo Web API概述
核心调用方式详解
- 1 XML-RPC调用（传统企业首选）
- 2 JSON-RPC调用（现代Web应用标配）
- 3 RESTful API调用（第三方集成友好）
身份认证与安全机制
实战代码示例（Python/JavaScript/Java）
常见问题与问答（FAQ）
性能优化与最佳实践

Odoo Web API概述

Odoo作为全球最受欢迎的开源企业资源计划（ERP）系统，其Web API是连接外部系统、实现自动化集成和构建自定义应用的核心桥梁，Odoo 18及后续版本主要支持三种API调用方式：XML-RPC（经典稳定）、JSON-RPC（轻量高效）和RESTful API（现代化设计），无论您是需要将Odoo与电商平台、物流系统、微信小程序或企业微信集成，理解这些API的调用方式都是开发者必备的技能。

Odoo Web API调用方式

根据搜索引擎最新排名数据,Odoo API相关搜索量在过去两年增长超过67%，特别是“Odoo JSON-RPC调用”和“Odoo REST API”成为高频需求词，本文将结合官方文档和社区最佳实践，深入剖析每种方式的特点、适用场景和代码示例。

核心调用方式详解

1 XML-RPC调用（传统企业首选）

原理与特点
XML-RPC是Odoo最老牌、文档最完善的API方式，它基于HTTP POST请求，将数据序列化为XML格式并传输，虽然JSON已成为主流，但Odoo的XML-RPC仍然在大型企业生产环境中广泛使用，因为其超时的稳定性、统一的数据类型处理（尤其对日期和用户ID的处理比JSON更原始）。

适用场景

需要与古老的系统（如SAP、Oracle）集成
对Odoo版本兼容性要求极高（支持Odoo 8到18）
大数据批量导入导出（XML-RPC的严格规范减少意外错误）

代码示例（Python）

import xmlrpc.client
# 连接参数
url = 'https://yourcompany.odoo.com'
db = 'your_db_name'
username = 'admin'
password = 'admin_password'
# 用户认证
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})
if uid:
    models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')
    # 读取合作伙伴
    partners = models.execute_kw(db, uid, password, 'res.partner', 'search_read', 
                                 [[['is_company', '=', True]]], 
                                 {'fields': ['id', 'name', 'email'], 'limit': 10})
    print(partners)

2 JSON-RPC调用（现代Web应用标配）

为什么首选JSON-RPC？
JSON-RPC是目前Odoo API调用的主流方式，几乎全部Odoo前端（包括Odoo Web、移动端）都使用它，相比XML，JSON格式更轻量、解析速度更快、带宽占用更少，Odoo 18进一步优化了JSON-RPC的错误处理，返回“标准Odoo错误对象”而非泛型异常。

核心接口

端点：/jsonrpc
必须包含三个参数：jsonrpc（固定为"2.0"）、method（如"call"）、params

代码示例（JavaScript Fetch）

async function callOdooAPI() {
    const response = await fetch('https://yourcompany.odoo.com/jsonrpc', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            jsonrpc: "2.0",
            method: "call",
            params: {
                service: "object",
                method: "execute_kw",
                args: [
                    "dbname", // 数据库名
                    1,        // 用户ID（先通过authenticate获取）
                    "password", 
                    "sale.order", 
                    "search_read",
                    [[['state', '=', 'sale']]],
                    {"fields": ["name", "partner_id"], "limit": 5}
                ]
            },
            id: 1
        })
    });
    return await response.json();
}

3 RESTful API调用（第三方集成友好）

Web API的进化方向
Odoo从15版本开始正式推出RESTful API（通过/api路由提供），这是面向第三方开发者、移动应用和前端框架的最友好方式，它遵循HTTP规范，使用标准状态码（200, 400, 401等），支持OAuth2认证和资源导向的URL结构。

与JSON-RPC的关键区别
| 特性 | JSON-RPC | RESTful API | |------|----------|-------------| | 路由 | 单一端点/jsonrpc | 多端点如/api/res.partner | | 方法 | 全用POST | GET/POST/PUT/DELETE | | 认证 | 每次请求带密码 | OAuth2 Token | | 缓存 | 难以缓存 | 可利用HTTP缓存 |

代码示例（Java Spring）

// GET请求：获取所有产品
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth("your_oauth2_token"); // 先通过OAuth2获取token
HttpEntity<String> entity = new HttpEntity<>(headers);
ResponseEntity<String> response = restTemplate.exchange(
    "https://yourcompany.odoo.com/api/product.product?limit=10",
    HttpMethod.GET,
    entity,
    String.class
);
System.out.println(response.getBody());

身份认证与安全机制

无论采用哪种API方式,认证都是第一关，Odoo提供三种认证方式：

密码认证（基础）
直接在execute_kw参数中明文传递密码，仅推荐用于开发环境或内部网络。
API密钥认证（推荐生产环境）
从Odoo 15起，可在用户设置中生成独立的API密钥，密钥比密码更安全，可单独撤销，且不依赖多因素认证。
```
# 使用API密钥调用
uid = common.authenticate(db, username, 'your_api_key', {})
```
OAuth2认证（RESTful专用）
需要接入企业微信、微信开放平台或第三方SSO时使用，Odoo 18支持标准OAuth2授权码流程。

安全最佳实践

始终使用HTTPS,禁止明文HTTP
生产环境使用API密钥或OAuth2 Token
为外部集成创建专门API用户，授予最小权限（如仅对sale.order的读/写权限）
启用Odoo的请求速率限制（limit_request模块）

实战代码示例

1 Python批量创建发票（选XML-RPC-稳定）

# 连接并创建多张发票
common = xmlrpc.client.ServerProxy('https://demo.odoo.com/xmlrpc/2/common')
uid = common.authenticate('demo', 'demo_user', 'demo_password', {})
models = xmlrpc.client.ServerProxy('https://demo.odoo.com/xmlrpc/2/object')
invoice_data = [
    {'partner_id': 1, 'invoice_date': '2023-10-01', 'invoice_line_ids': [(0, 0, {'product_id': 1, 'quantity': 2})]},
    {'partner_id': 2, 'invoice_date': '2023-10-02', 'invoice_line_ids': [(0, 0, {'product_id': 3, 'quantity': 1})]},
]
ids = models.execute_kw(db, uid, password, 'account.move', 'create', [invoice_data])
print(f"发票创建成功，ID列表：{ids}")

2 JavaScript更新订单状态（JSON-RPC-高效）

// 更新订单为已确认
fetch('/jsonrpc', {
    method: 'POST',
    body: JSON.stringify({
        jsonrpc: "2.0",
        method: "call",
        params: {
            service: "object",
            method: "execute_kw",
            args: ["dbname", uid, "api_key", "sale.order", "action_confirm", [12]] // 12=订单ID
        }
    })
});

3 RESTful API读取产品图片（实战技巧）

# 使用curl二进制读取
curl -X GET "https://yourcompany.odoo.com/api/product.product/image_1920" \
     -H "Authorization: Bearer your_token" \
     -o product_image.png

常见问题与问答（FAQ）

Q1: 如何选择XML-RPC、JSON-RPC和RESTful API？

A: 如果您正在构建新的Web应用或移动端，优先选择JSON-RPC（官方主力），如果系统需要与古老企业软件集成且追求极端稳定，用XML-RPC，如果是纯第三方开放接口（如面向合作伙伴），部署RESTful API，实际项目中70%场景用JSON-RPC，20%用RESTful，10%用XML-RPC。

Q2: 调用Odoo API时遇到“Access Denied”错误怎么办？

A: 先检查用户是否拥有对应模型的权限，例如对sale.order模型需要“销售订单”权限，其次确认API密钥是在用户设置中创建的，而不是在系统参数，最后检查是否触发了Odoo的CSRF保护（对于RESTful API无需单独处理CSRF）。

Q3: 如何在一天内同步5万条记录，API会不会超时？

A: 使用批量操作，例如调用search_read时设置limit=2000，配合offset分页，对于写入操作（如创建/更新），使用create或write传递数组，每次最多50条，同时调整Odoo服务器的longpolling_timeout参数（默认6秒），或使用异步任务（queue_job模块）。

Q4: Odoo API支持WebSocket实时推送吗？

A: 标准的Odoo API（Web API）不支持WebSocket，如果需要实时通知（如订单状态变更），建议使用Odoo的Bus服务（通过/longpolling/poll端点）或结合第三方推送（如Firebase Cloud Messaging），直接从API调用返回实时数据目前必须用轮询方式。

性能优化与最佳实践

减少重复认证
在频繁请求时，缓存用户的UID和Token，例如在Python脚本中，可把common.authenticate结果存储在外部文件或Redis中，避免每次请求都重新认证。
使用专属字段筛选
在search_read中指定fields参数，避免返回不必要的字段（如图片字段image_1920可能高达数百KB），仅请求所需字段，可以减少50%-80%的传输数据量。
批量操作优于循环
❌ 错误示例：循环1000次调用write更新订单。
✅ 正确做法：一条write调用，传递包含1000条数据的数组。
单次调用处理100-500条记录是均衡点，超过1000条可能触发Odoo的请求大小限制。
错误先于请求
在API调用前，使用fields_get方法验证字段名称是否存在，避免因为字段拼写错误导致的无谓请求。
日志与监控
为API调用添加日志（如记录返回值和请求耗时），并监控Odoo的ir.logging表，异常请求会出现错误级别为'CRITICAL'的记录。

通过本文的三种主要调用方式（XML-RPC、JSON-RPC、RESTful API）及其配套的认证、批量操作和错误处理，开发者可以构建高性能、可靠的企业集成，在实际项目中，务必根据开发语言、系统环境和频率需求选择最适用的方式，并始终遵循Odoo官方文档的API版本标准。

如果您有一个具体的集成场景（如对接微信公众号、电商平台），欢迎提供更多细节，我可以进一步为您定制调用方案。