跳到主要内容
支持地域：上海

OpenAPI 接口调用方式

软件化部署下 OpenAPI 接口调用时，域名和鉴权机制获取方式有所不同，本文档将进行详细说明。

1. 接口使用说明​

1.1 域名（访问地址）​

注意

软件化部署后访问 WeDa 的地址，一般为 http://ip:port，即为 OpenAPI 接口的访问地址

说明
  1. 如果使用 HTTPS，请将协议改为 https；如果有域名，请将 IP 替换为具体域名
  2. port 填写部署时的真实端口号
    • HTTP 默认端口 80 可省略
    • HTTPS 默认端口 443 可省略

环境 ID 获取：

环境 ID 可以在浏览器的地址栏中获取，是以 envId 开头的请求参数值。

1.2 鉴权机制​

1.2.1 获取密钥​

前往软件化管理页面的 环境配置 中获取 SecretId 和 SecretKey。

环境配置

1.2.2 获取 Access Token​

使用 OAuth 2.0 鉴权方式换取 Access Token。

Token 获取 URL：

http://ip:port/auth/v1/token/clientCredential
# 将 http://ip:port 替换成具体的访问地址

请求示例：

  • Method: POST
  • Headers:
    • Content-Type: application/json
    • Authorization: Basic <Base64(SecretId:SecretKey)>
  • Body:
    {
      "grant_type": "client_credentials"
    }

返回值格式：

{
  "token_type": "Bearer",
  "access_token": "xxxxyyyy",
  "expires_in": 259200
}
说明
  • access_token：访问令牌，用于后续 API 调用
  • expires_in：Access Token 有效期，单位：秒

1.2.3 使用 Access Token 请求接口​

在 Request Header 中加入：

Authorization: Bearer <access_token>

1.3 请求说明​

  • 所有接口均通过 HTTP/HTTPS 进行通信，使用 UTF-8 编码
  • 支持的 HTTP 请求方法：POST、GET、PUT、DELETE
  • Content-Type 类型：application/json;utf-8

2. 操作示例​

以审批流 OpenAPI 接口调用为例进行演示。

2.1 Node.js 代码示例​

接口获取说明

接口信息可以在 APIs 连接器 → 工作流 中获取。

例如：查询流程实例审批人列表

{{vars.host}}/weda/workflow/v1/{{WeDa.EnvType}}/DescribeInstanceApproverList

参数说明：
1. {{vars.host}} - 上述提到的域名
2. {{WeDa.EnvType}} - 环境值：prod（正式环境）或 dev（体验环境）

代码示例：

const Koa = require("koa");
const fetch = require("node-fetch");
const app = new Koa();

const SecretId = ""; // 从软件化"环境配置"页面获取
const SecretKey = ""; // 从软件化"环境配置"页面获取
const EnvType = "prod"; // prod: 正式环境，dev: 体验环境

// 域名
const domain = '使用真正的域名值替换';

app.use(async (ctx) => {
  // 1. 换取 AccessToken
  const tokenResponse = await fetch(
    `${domain}/auth/v1/token/clientCredential`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${Buffer.from(
          `${SecretId}:${SecretKey}`
        ).toString("base64")}`,
      },
      body: JSON.stringify({
        grant_type: "client_credentials",
      }),
    }
  );

  const { access_token } = await tokenResponse.json();

  // 2. 请求服务端 API
  const queryResponse = await fetch(
    `${domain}/weda/workflow/v1/${EnvType}/DescribeInstanceApproverList`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${access_token}`,
      },
    }
  );

  ctx.body = await queryResponse.json();
});

app.listen(3000);

2.2 使用 Postman 调用接口​

2.2.1 创建请求​

打开 Postman 工具，添加一个请求（具体请求方法可在 APIs 连接器 → 工作流 中查看）。

创建请求

配置全局环境变量：

说明

需要设置以下全局环境变量：

  1. vars.host - 域名地址
  2. WeDa.EnvType - 环境值：prod（正式环境）或 dev（体验环境）
  3. SECRET_ID - 从软件化管理页面的 环境配置 中获取
  4. SECRET_KEY - 从软件化管理页面的 环境配置 中获取

环境变量配置

2.2.2 配置 Authorization​

进入 Authorization 选项卡，设置 {{access_token}}。

Authorization 配置

2.2.3 配置 Pre-request Script​

进入 Script 选项卡，在 Pre-request 中设置如下代码：

Pre-request Script

代码内容：

// 检查是否有有效的 access_token
const accessToken = pm.environment.get("access_token");
const expiry = pm.environment.get("access_token_expiry");
const secretId = pm.globals.get("SECRET_ID");
const secretKey = pm.globals.get("SECRET_KEY");
const host = pm.globals.get("vars.host");
const now = Math.floor(Date.now() / 1000);

// 如果 token 存在且未过期，跳过获取
if (accessToken && expiry && now < expiry) {
    console.log("Token 有效，跳过获取");
    return;
}

console.log("Token 不存在或已过期，正在获取...");

// 定义请求参数
const tokenUrl = host + "/auth/v1/token/clientCredential";
console.log("请求 Token 的地址:", tokenUrl);

// 构造 Basic Auth
const credentials = btoa(`${secretId}:${secretKey}`);

// 同步请求获取 token
pm.sendRequest({
    url: tokenUrl,
    method: 'POST',
    header: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${credentials}`
    },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            grant_type: "client_credentials"
        })
    }
}, function (err, res) {
    if (err) {
        console.error("获取 token 失败:", err);
        return;
    }

    if (res.status !== 'OK') {
        console.error("Token 接口返回错误:", res.status, res.text());
        return;
    }

    const jsonResponse = res.json();
    const newToken = jsonResponse.access_token;
    const expiresIn = jsonResponse.expires_in || 3600; // 默认 1 小时

    if (!newToken) {
        console.error("返回的 access_token 为空");
        return;
    }

    // 保存 token 和过期时间（提前 60 秒过期，防止临界问题）
    const expiresAt = Math.floor(Date.now() / 1000) + expiresIn - 60;
    pm.environment.set("access_token", newToken);
    pm.environment.set("access_token_expiry", expiresAt);

    console.log("Token 获取成功并已保存");
});

2.2.4 配置 Headers​

进入 Headers 选项卡，设置相应参数。

Headers 配置

2.2.5 配置 Body​

进入 Body 选项卡，设置相应请求数据。

Body 配置

2.2.6 发送请求​

点击 Send 按钮发送请求。

发送请求

3. 接口异常返回​

接口异常返回有两种格式：

3.1 公共参数校验异常​

返回格式：

{
  "code": "INVALID_ACCESS_TOKEN",
  "requestId": "79e7c0fc8286e",
  "message": "access token verify failed: jwt expired"
}

错误码说明：

错误码描述
INVALID_ACCESS_TOKENTOKEN 不正确或已过期
BAD_REQUEST请求数据格式异常
INVALID_HOSTHOST 不合法
INVALID_REGION地域不匹配
INVALID_ENV错误的环境、环境未找到
INVALID_ENV_STATUS环境状态异常、不可用
INVALID_COMMON_PARAM公共参数错误
SIGN_PARAM_INVALID签名校验不通过
PERMISSION_DENIED权限拒绝
EXCEED_REQUEST_LIMIT资源超限
EXCEED_RATELIMITQPS 超限
SYS_ERR系统错误
SERVER_TIMEOUT服务超时

3.2 业务接口异常​

返回格式：

{
  "Response": {
    "RequestId": "",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "参数错误"
    }
  }
}

错误码说明：

具体错误码请参见各接口文档中的描述。

4. 软件化支持的 OpenAPI 模块​

除了上述讲解的审批流接口调用，以下模块也支持在软件化部署下采用 OpenAPI 方式调用。

说明
  1. 域名获取方式请参考本文档 1.1 域名（访问地址） 章节
  2. 鉴权机制中涉及的 Token 获取方式请参考 1.2 鉴权机制 章节

4.1 MySQL 数据库​

详见：MySQL 数据库 OpenAPI

4.2 数据模型​

详见：数据模型 OpenAPI

4.3 云存储​

详见：云存储 OpenAPI