REBUILD OpenAPI 使用

当企业规模逐渐增大时，作为支撑业务运营的 IT 建设也变得越来越重要。不过往往企业的 IT 建设过程中会发现某一家软件供应商基本不能完全覆盖企业所有的业务运营流程。这样的结果就是，企业上的 IT 系统很多很全，从 ERP 到 HR、CRM、PDM、OA 等，貌似所有的业务都能覆盖到，但实际上因为这些系统的不集成，而形成了企业很多新的信息孤岛，非常不利于企业的后续管理和战略发展。毕竟企业经营的多样化，并不是所有的业务都能在 REBUILD 中完成，所以我们必须在产品架构上支持更好的与外部系统进行协同。

基础知识

OpenAPI 是基于 HTTP 调用的后台接口（类 RESTful），通过 JSON 数据进行交互。具备跨语言、安全可控、高灵活度等特性。

OpenAPI 通常应用于第三方系统集成使用，例如单点登录、数据交互等。你同样可以通过 OpenAPI 为 RB 添加一些新的功能特性，而不必修改 RB 的核心代码，以此保持后续的版本升级和安全更新可用。

数据返回格式

数据统一采用 JSON 数据格式返回，示例如下：

{
  "error_code": 0,
  "error_msg": "调用成功",
  "data": xxx,
  "error_data": xxx
}

其中 error_code 为错误码，error_msg 为错误描述，data 为请求返回数据（若有）。同时，针对某些特定错误（例如字段值重复），会在 "error_data" 中返回相关数据（若有）。

全局错误码

• 0 - 调用成功
• 4xx - 业务失败。参数错误或违反数据/业务规则，具体可参考 error_msg
  • 401 - 鉴权错误
  • 402 - 无效 API 接口
  • 403 - 请求频率超限
  • 410 - 请求参数有误
  • 420 - 违反业务约束
• 5xx - 系统错误。请联系接口提供方

公共请求参数

公共请求参数是每次请求所必须携带的参数，用于 API 鉴权。

参数	说明
appid	APP ID（见下文 创建 API 账户）
timestamp	时间戳，精确到秒。客户端/服务器时间偏差允许正负 15 秒
sign_type	签名类型，可选 MD5 或 SHA1
sign	加密签名

授权方式

OpenAPI 支持基于加密签名的授权方式。将请求参数通过固定的方式组装并加密，形成加密签名，并在请求时携带。其适用于安全要求较高的应用。

加密方法和规则

1. 将所有 URL 参数（不含 POST 及 sign 部分）按字段升序（A-Z）排列
2. 将排序后的参数进行拼接，形式如 key1=value1&key2=value2，最后拼接上 &APP_ID.APP_SECRET
3. 将拼接好的参数进行 MD5 或 SHA 加密得到加密签名
4. 将签名（sign）拼接到请求 URL 中

设有请求参数 page_no 值 2，那么其组装加密步骤如下：

// APP_ID = 999999999
// APP_SECRET = hRwXFvykcmD6MofNOHOzaMSuaB6U76P077ZT8ZFj

// 1. 拼接参数得到
appid=999999999&page_no=2&sign_type=MD5&timestamp=1602772338&999999999.hRwXFvykcmD6MofNOHOzaMSuaB6U76P077ZT8ZFj

// 2. 对步骤1得到的字符串进行 MD5 加密得到
2356574a32b680514bd3b38e4b0cd960

// 3. 拼接 sign 参数最终得到
appid=999999999&page_no=2&sign_type=MD5&timestamp=1602772338&sign=2356574a32b680514bd3b38e4b0cd960

我们提供了一个 Java 版本的实现供你参考 OpenApiSDK

开始使用

创建 API 账户

进入管理中心 - API 密钥，点击右上角 [添加] 新建一个 API 访问账户。添加后你将得到一对访问密钥，即 APP ID 与 API SECRET。

请特别注意 绑定用户 字段，接口所能使用到的权限与绑定用户相符，同时其也在调用上下文中作为操作用户使用。同时注意保密 APP SECRET 参数，一旦泄漏请立即重置或删除使其作废。

调用接口

OpenAPI 的基础调用 URL 为 http://YOUR-RB-SERVER/gw/api/，例如获取服务器时间的完整调用 URL 为：

http://YOUR-RB-SERVER/gw/api/system-time?appid=999999999&sign_type=MD5&timestamp=1602752048&sign=840d6ee50ef013e545b543fa63cce860

我们提供了一个 Java 版本的实现供你参考 OpenApiSDK

查看调用日志

你可以点击 API 账户后面的“调用量”数字查看调用日志，日志中详细记录了该 API 账户的每一次调用详情。

可用接口

• 通用 (3)
  • 服务器时间
  • 单点登录
  • 页面验证
• 元数据 (5)
  • 实体列表
  • 字段列表
  • 分类数据值
  • 下拉列表数据值
  • 多选数据值
• 业务记录 (6)
  • 新建记录
  • 更新记录
  • 新建或更新记录
  • 删除记录
  • 获取单条记录
  • 获取多条记录（支持高级搜索）
• 文件 (2)
  • 文件上传
  • 文件下载
• 主动式接口
  • 主动式接口请使用触发器 回调 URL

常见问题

是否可以直接操作数据库而不使用接口？

直接操作数据库将导致业务逻辑、缓存缺失或错误，导致不可预知的情况发生。