OpenAPI 接口调用方式

在微搭私有部署环境中，OpenAPI 接口的调用方式与公有云版本存在差异，主要体现在域名配置和鉴权机制上。本文档将详细介绍私有部署环境下的 OpenAPI 接口调用方法。

1. 基础配置

1.1 访问地址配置

重要提示

私有部署环境的 OpenAPI 接口访问地址即为微搭平台的访问地址，通常格式为 http://ip:port

配置说明

1. 协议选择：如果启用了 HTTPS，请将协议改为 https；如果配置了域名，请将 IP 替换为具体域名
2. 端口配置：填写部署时的实际端口号
   • HTTP 默认端口 80 可以省略
   • HTTPS 默认端口 443 可以省略

环境 ID 获取方法：

环境 ID 可以从浏览器地址栏中获取，查找以 envId 开头的 URL 参数值。

1.2 身份认证机制

1.2.1 获取认证密钥

1. 登录微搭私有部署管理后台
2. 进入 环境配置 页面
3. 获取 SecretId 和 SecretKey

1.2.2 获取访问令牌（Access Token）

使用 OAuth 2.0 客户端凭证模式获取访问令牌。

令牌获取接口：

POST http://ip:port/auth/v1/token/clientCredential
# 请将 http://ip:port 替换为实际的访问地址

请求配置：

• 请求方法：POST
• 请求头：
  • Content-Type: application/json
  • Authorization: Basic <Base64(SecretId:SecretKey)>
• 请求体：

  {
    "grant_type": "client_credentials"
  }

响应格式：

{
  "token_type": "Bearer",
  "access_token": "xxxxyyyy",
  "expires_in": 259200
}

字段说明

• access_token：访问令牌，用于后续 API 调用
• expires_in：令牌有效期，单位为秒

1.2.3 使用访问令牌调用接口

在所有 API 请求的请求头中添加：

Authorization: Bearer <access_token>

1.3 接口调用规范

• 通信协议：所有接口均使用 HTTP/HTTPS 协议，采用 UTF-8 编码
• 支持的请求方法：POST、GET、PUT、DELETE
• 内容类型：application/json;charset=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) => {
  try {
    // 步骤1：获取访问令牌
    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：调用业务接口
    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();
  } catch (error) {
    ctx.status = 500;
    ctx.body = { error: error.message };
  }
});

app.listen(3000);

2.2 Postman 调用配置

2.2.1 创建新请求

1. 打开 Postman 应用
2. 创建新的请求（请求方法可在 APIs 连接器 → 工作流 中查看）

2.2.2 配置环境变量

设置以下全局环境变量：

必需变量

1. vars.host - 私有部署的访问地址
2. WeDa.EnvType - 环境类型：prod（正式环境）或 dev（体验环境）
3. SECRET_ID - 从环境配置页面获取的 SecretId
4. SECRET_KEY - 从环境配置页面获取的 SecretKey

2.2.3 配置请求认证

在 Authorization 选项卡中，设置 Bearer Token 为 {{access_token}}。

2.2.4 配置预请求脚本

在 Scripts 选项卡的 Pre-request 中添加以下代码：

脚本代码：

// 检查当前访问令牌是否有效
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);

// 如果令牌存在且未过期，跳过获取流程
if (accessToken && expiry && now < expiry) {
    console.log("访问令牌有效，跳过获取流程");
    return;
}

console.log("访问令牌不存在或已过期，正在重新获取...");

// 构建令牌获取请求
const tokenUrl = host + "/auth/v1/token/clientCredential";
console.log("令牌获取地址:", tokenUrl);

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

// 发送令牌获取请求
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("获取访问令牌失败:", err);
        return;
    }

    if (res.status !== 'OK') {
        console.error("令牌接口返回错误:", 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("返回的访问令牌为空");
        return;
    }

    // 保存令牌和过期时间（提前 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("访问令牌获取成功并已保存");
});

2.2.5 配置请求头

在 Headers 选项卡中设置必要的请求头。

2.2.6 配置请求体

在 Body 选项卡中设置请求数据。

2.2.7 发送请求

点击 Send 按钮执行请求。

3. 错误处理

接口调用过程中可能遇到两类异常返回：

3.1 认证和公共参数异常

错误响应格式：

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

常见错误码：

错误码	描述
INVALID_ACCESS_TOKEN	访问令牌无效或已过期
BAD_REQUEST	请求数据格式错误
INVALID_HOST	访问地址不合法
INVALID_REGION	地域参数不匹配
INVALID_ENV	环境参数错误或环境不存在
INVALID_ENV_STATUS	环境状态异常，暂不可用
INVALID_COMMON_PARAM	公共参数格式错误
SIGN_PARAM_INVALID	签名校验失败
PERMISSION_DENIED	权限不足，访问被拒绝
EXCEED_REQUEST_LIMIT	超出资源使用限制
EXCEED_RATELIMIT	超出请求频率限制
SYS_ERR	系统内部错误
SERVER_TIMEOUT	服务响应超时

3.2 业务逻辑异常

错误响应格式：

{
  "Response": {
    "RequestId": "12345678-1234-1234-1234-123456789012",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "参数值不符合要求"
    }
  }
}

处理建议：

具体的业务错误码和处理方法请参考各个接口文档中的详细说明。

4. 支持的 OpenAPI 模块

除了本文演示的审批流接口，以下模块同样支持在私有部署环境中使用 OpenAPI 调用：

配置参考

1. 访问地址配置请参考 1.1 访问地址配置 章节
2. 身份认证配置请参考 1.2 身份认证机制 章节

4.1 数据模型接口

提供数据模型的增删改查等操作接口。

认证方式差异

数据模型接口和云存储接口的 access_token 获取方式与审批流接口不同：

• 审批流接口、权限相关接口：使用 SecretId/SecretKey 通过客户端凭证模式获取（参考 1.2 身份认证机制）
• 数据模型接口、云存储接口：使用用户名和密码获取 access_token，访问地址仍为 1.1 章节 中的配置

具体获取方法请参考：CloudBase HTTP API - Access Token

详细文档：数据模型 OpenAPI

4.2 云存储接口

提供文件上传、下载、管理等云存储相关接口。

认证方式说明

云存储接口的 access_token 获取方式与数据模型接口相同，请参考上述 4.1 数据模型接口 中的认证方式说明。

详细文档：云存储 OpenAPI

4.3 权限相关接口

提供用户权限管理、角色分配等接口。

认证方式说明

权限相关接口使用标准的 SecretId/SecretKey 客户端凭证模式获取 access_token，与审批流接口认证方式相同（参考 1.2 身份认证机制）。

详细文档：权限相关 OpenAPI

---

总结

通过本文档，您已经了解了微搭私有部署环境下 OpenAPI 接口的完整调用流程：

1. 配置访问地址：使用私有部署的实际访问地址
2. 获取认证密钥：从环境配置页面获取 SecretId 和 SecretKey
3. 获取访问令牌：通过 OAuth 2.0 客户端凭证模式获取 Access Token
4. 调用业务接口：在请求头中携带 Bearer Token 进行接口调用
5. 处理异常情况：根据错误码进行相应的错误处理

建议在实际使用中，实现访问令牌的自动刷新机制，以确保接口调用的稳定性和连续性。