odoo-rpc-api

Odoo RPC API

概述

Odoo 通过 JSON-RPC 和 XML-RPC 提供功能强大的外部 API，允许任何外部应用读取、创建、更新和删除记录。本技能将指导你完成身份验证、调用模型并构建稳健的集成。

适用场景

• 将外部应用（例如 Django、Node.js 或移动应用）连接到 Odoo。
• 运行自动化脚本，从 Odoo 导入或导出数据。
• 在 Odoo 与第三方平台之间构建中间件层。
• 调试 API 身份验证或权限错误。

工作原理

1. 激活：提及 @odoo-rpc-api 并描述你需要的集成。
2. 生成：获取可直接复制粘贴的 Python、JavaScript 或 curl RPC 调用代码。
3. 调试：粘贴错误信息并获取诊断结果和修正后的调用。

示例

示例 1：身份验证并读取记录（Python）

import os
import xmlrpc.client

url = 'https://myodoo.example.com'
db = 'my_database'
username = 'integration-user'
password = os.environ["ODOO_API_KEY"]  # Use API keys, not passwords, in production

# Step 1: Authenticate
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})
if not uid:
    raise RuntimeError("Odoo authentication failed")

# Step 2: Call models
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')

# Search confirmed sale orders
orders = models.execute_kw(db, uid, password,
    'sale.order', 'search_read',
    [[['state', '=', 'sale']]],
    {'fields': ['name', 'partner_id', 'amount_total'], 'limit': 10}
)
for order in orders:
    print(order)

示例 2：创建记录（Python）

此操作会更改业务数据。请使用经过授权的测试数据库和获批的集成用户；重复使用示例 1 中已通过身份验证的对象。

new_partner_id = models.execute_kw(db, uid, password,
    'res.partner', 'create',
    [{'name': 'Acme Corp', 'email': '[email protected]', 'is_company': True}]
)
print(f"Created partner ID: {new_partner_id}")

示例 3：基于会话的 JSON-RPC 片段

与 XML-RPC API 密钥示例不同，以下 Web 端点需要单独通过身份验证的 Odoo 会话 Cookie。此处不会建立会话；如果没有会话，请求将失败。对于实际部署的 Odoo 版本，请优先使用对应版本文档所述的外部 API。

curl -X POST https://myodoo.example.com/web/dataset/call_kw \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "call",
    "id": 1,
    "params": {
      "model": "res.partner",
      "method": "search_read",
      "args": [[["is_company", "=", true]]],
      "kwargs": {"fields": ["name", "email"], "limit": 5}
    }
  }'
# Supply an authorized session through your HTTP client’s protected cookie store.
# Do not paste session cookies or API keys into logs or shared examples.

最佳实践

• ✅ 建议： 使用 API 密钥（Settings → Technical → API Keys）代替密码 — Odoo 14+ 提供此功能。
• ✅ 建议： 使用 search_read，而不是 search + read，以减少网络往返次数。
• ✅ 建议： 对安全读取操作的连接错误进行有界退避处理。遇到结果不明确的创建或写入超时后，应使用稳定的外部标识符进行核对，再重试以避免重复创建业务记录。
• ✅ 建议： 将凭据存储在环境变量或密钥管理器（例如 AWS Secrets Manager、.env 文件）中。
• ❌ 不要： 在脚本中直接硬编码密码或 API 密钥 — 应定期轮换密钥并使用环境变量。
• ❌ 不要： 在紧密循环中不加批处理地调用 API — 批量操作可显著降低服务器负载。
• ❌ 不要： 将主管理员密码用于 API 集成 — 应创建权限范围满足最低需求的专用集成用户。

限制

• 不实现 OAuth2 或会话登录。XML-RPC 示例使用 API 密钥；Web JSON-RPC 片段则要求事先单独建立会话。
• 速率限制未内置于 Odoo XMLRPC 层；你必须在客户端实现限流。
• 附件属于模型记录：通过授权的 RPC 模型调用 ir.attachment 时，请将二进制字段内容编码为 base64。JSON-RPC 不是 REST 上传端点；请遵守负载限制和访问规则。
• 选择端点前，请确认托管方式、订阅方案以及对应确切版本对外部 API 的支持情况。Odoo Online 和 Odoo.sh 是不同的产品。请参阅 Odoo 外部 API。