衣星科技知识库

Appearance

API 配置指南 ​

本文档详细介绍明道云 API 的配置方法和最佳实践。

API Token 配置 ​

创建 API Token ​

  1. 登录明道云账号
  2. 进入「设置」-「开放平台」
  3. 点击「API Token」标签
  4. 点击「新建 Token」
  5. 填写 Token 信息：
    • 名称：用于标识 Token 的用途（如：CRM系统集成）
    • 权限范围：选择 Token 可访问的应用
    • 过期时间：设置 Token 有效期（可选）
  6. 点击「创建」
  7. 重要：立即复制并保存 Token（仅显示一次）

Token 权限配置 ​

应用级权限 ​

  • 选择 Token 可以访问的具体应用
  • 建议按最小权限原则，只授予必要的应用访问权限

操作权限 ​

  • 读取：仅可查询数据
  • 写入：可创建和更新数据
  • 删除：可删除数据
  • 管理：完整权限（谨慎使用）

Token 管理 ​

查看 Token 列表 ​

  1. 进入「设置」-「开放平台」-「API Token」
  2. 查看所有已创建的 Token
  3. 查看 Token 的最后使用时间

禁用 Token ​

  • 如果 Token 泄露或不再使用，立即禁用
  • 禁用后该 Token 将无法继续使用

删除 Token ​

  • 确认不再需要后，可以删除 Token
  • 删除操作不可恢复

Webhook 配置 ​

创建 Webhook ​

  1. 进入目标应用
  2. 点击「设置」-「Webhook」
  3. 点击「新建 Webhook」
  4. 配置 Webhook 信息：

基本信息 ​

  • 名称：Webhook 的名称
  • 描述：说明 Webhook 的用途

触发条件 ​

  • 数据新增：当表单新增数据时触发
  • 数据更新：当数据被修改时触发
  • 数据删除：当数据被删除时触发
  • 工作流完成：当工作流执行完成时触发

筛选条件（可选） ​

  • 可以设置具体的筛选条件，只有满足条件的事件才会触发 Webhook
  • 例如：仅当状态字段为「已完成」时触发

回调 URL ​

  • 接收 Webhook 通知的服务器地址
  • 必须是可公网访问的 HTTPS 地址
  • 示例：https://api.example.com/webhook/mingdao

请求方式 ​

  • POST：推荐使用
  • GET：仅用于简单场景

请求头（可选） ​

  • 可以添加自定义请求头
  • 常用于身份验证，如：Authorization: Bearer YOUR_SECRET

Webhook 安全配置 ​

签名验证 ​

明道云会在请求头中包含签名信息，用于验证请求来源：

javascript
// 验证签名示例
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}

IP 白名单 ​

  • 如果服务器支持，建议配置 IP 白名单
  • 仅允许明道云服务器 IP 访问

Webhook 测试 ​

  1. 创建 Webhook 后，点击「测试」
  2. 系统会发送一条测试请求
  3. 检查服务器是否正常接收
  4. 验证数据格式是否正确

Webhook 日志 ​

  • 查看 Webhook 的调用历史
  • 查看成功/失败的请求记录
  • 查看错误信息和响应状态

环境配置 ​

开发环境 ​

bash
# 环境变量配置
MINGDAO_API_TOKEN=dev_token_here
MINGDAO_API_BASE_URL=https://api.mingdao.com/api/v1
MINGDAO_WEBHOOK_SECRET=webhook_secret_here

生产环境 ​

bash
# 生产环境配置
MINGDAO_API_TOKEN=prod_token_here
MINGDAO_API_BASE_URL=https://api.mingdao.com/api/v1
MINGDAO_WEBHOOK_SECRET=prod_webhook_secret

配置管理 ​

使用环境变量 ​

  • 不要将 Token 硬编码在代码中
  • 使用环境变量或配置文件管理
  • 不同环境使用不同的 Token

配置文件示例 ​

config.json（不提交到代码仓库）：

json
{
  "mingdao": {
    "apiToken": "your_token_here",
    "baseUrl": "https://api.mingdao.com/api/v1",
    "webhookSecret": "your_secret_here"
  }
}

请求配置 ​

请求头配置 ​

标准请求头 ​

http
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

自定义请求头 ​

http
X-Request-ID: unique-request-id
X-Client-Version: 1.0.0

超时配置 ​

javascript
// JavaScript 示例
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000); // 5秒超时

fetch(url, {
  signal: controller.signal,
  // ... 其他配置
}).finally(() => clearTimeout(timeoutId));

重试配置 ​

javascript
// 重试机制示例
async function requestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

错误处理配置 ​

HTTP 状态码 ​

状态码说明处理方式
200成功正常处理
400请求错误检查请求参数
401未授权检查 Token 是否有效
403权限不足检查 Token 权限
404资源不存在检查资源 ID
429请求过多降低请求频率
500服务器错误联系技术支持

错误响应格式 ​

json
{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token 无效或已过期",
    "details": {}
  }
}

错误处理示例 ​

javascript
async function handleApiError(response) {
  if (!response.ok) {
    const error = await response.json();
    switch (response.status) {
      case 401:
        // Token 失效，重新获取
        await refreshToken();
        break;
      case 429:
        // 请求过多，等待后重试
        await waitAndRetry();
        break;
      default:
        console.error('API Error:', error);
        throw new Error(error.message);
    }
  }
  return response.json();
}

最佳实践 ​

安全建议 ​

  1. Token 管理

    • 定期更换 Token（建议每 3-6 个月）
    • 不同系统使用不同的 Token
    • 及时删除不再使用的 Token

  2. 权限控制

    • 遵循最小权限原则
    • 只授予必要的应用和操作权限
    • 定期审查 Token 权限

  3. 数据传输

    • 始终使用 HTTPS
    • 不要在 URL 中传递敏感信息
    • 对敏感数据进行加密

性能优化 ​

  1. 批量操作

    • 使用批量接口减少请求次数
    • 合理设置批量大小（建议 50-100 条）

  2. 缓存策略

    • 对不经常变化的数据进行缓存
    • 设置合理的缓存过期时间

  3. 异步处理

    • 对于耗时操作使用异步方式
    • 使用队列处理大量数据

监控和日志 ​

  1. 请求日志

    • 记录所有 API 请求和响应
    • 记录错误信息和堆栈

  2. 监控指标

    • 请求成功率
    • 响应时间
    • 错误率

  3. 告警设置

    • API 调用失败告警
    • Token 过期提醒
    • 异常流量告警

常见配置问题 ​

Token 无效 ​

原因：

  • Token 已过期
  • Token 被禁用或删除
  • Token 格式错误

解决方案：

  1. 检查 Token 是否在有效期内
  2. 确认 Token 未被禁用
  3. 验证 Token 格式是否正确（Bearer 前缀）

Webhook 未触发 ​

原因：

  • 回调 URL 不可访问
  • 触发条件配置错误
  • 筛选条件过于严格

解决方案：

  1. 测试回调 URL 是否可访问
  2. 检查触发条件配置
  3. 查看 Webhook 日志确认是否有错误

权限不足 ​

原因：

  • Token 权限范围不足
  • 应用权限配置错误

解决方案：

  1. 检查 Token 是否有对应应用的权限
  2. 确认操作权限是否足够
  3. 联系管理员调整权限

维护负责人：技术部
最后更新：2025-01-15

衣星科技知识库 © 2025

仅供内部使用，请勿外传