鉴权

所有 API 功能都需要合法的授权。授权凭证的签算需要觅知开放平台账号下的一对有效的 Access Key 和 Secret Key ，这对密钥可以通过如下步骤获得

获取 AK/SK

步骤说明

  • 1.注册开放平台账户
  • 2.进入控制台密钥管理
  • 3.申请 AK / SK

签名获取

说明:

  • 1.签算方法：HmacSHA256
  • 2.签算参数：Access Key、Secret Key、请求方法、请求路径、请求参数、请求体
  • 3.签算结果：Base64 编码

步骤说明:

  1. 保证当前发起请求的服务器时间与授时中心时间保持一致，误差不能超过1分钟

  2. 获取当前服务器的时间戳 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数 放入请求 Header 字段Timestamp

  3. 生成请求流水号放入请求 Header 字段X-Request-Id中

  4. 将请求参数按照键名自然排序正序后根据键名=键值依次使用&符号拼接

    const reqParams = {
  page: 1,
  pageSize: 100,
  keyword: "测试",
};
const paramStr = Object.keys(reqParams)
  .sort()
  .map((key) => `${key}=${reqParams[key]}`)
  .join("&");

  5. 将上一步得到的字符串拼接上请求方法（GET/POST/PUT/DELETE）、请求路径、请求的 Content-Type 的值、时间戳、X-Request-Id

    const signStr = `${paramStr}&${method}${path}${contentType}${t}${xRequestId}`;

  6. 对签名字符使用 hmac_sha256 加密获取签名字符串并且使用 base64 编码（需要注意的是请确保 base64 编码的字符串是经过 hmac_sha256 加密后的十六进制字符串）

    const sign = base64_encode(hmac_sha256(signstr,${SK}))

  7. 将 Access Key 和签名字符串使用:拼接后放入请求 Header 字段AccessToken中

    const accessToken = `${AK}:${sign}`;

  8. 上述步骤总共需要发送的请求头字段有Timestamp、X-Request-Id、AccessToken、Content-Type

  9. 示例请求搜索接口 POST https://plt.v5ppt.com/api/search/ppt 的伪代码如下：

    const reqParams = {
  page: 1,
  pageSize: 100,
  keyword: "测试",
};
const paramStr = Object.keys(reqParams)
  .sort()
  .map((key) => `${key}=${reqParams[key]}`)
  .join("&");
const reqUrl = "https://plt.v5ppt.com/api/search/ppt";
const t = Math.floor(Date.now() / 1000);
const xRequestId = uuidv4();
// 拼接参数与必要请求值
const signStr = `${paramStr}&POST/api/search/pptapplication/x-www-form-urlencoded; charset=UTF-8${t}${xRequestId}`;

//accessToken的格式是AK:SIGN 两个字符串通过:拼接
const accessToken = `${AK}:${base64_encode(hmac_sha256(signStr, SK))}`;
const reqHeaders = {
  Timestamp: t,
  "X-Request-Id": xRequestId,
  AccessToken: accessToken,
  "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
};
response = axios.post(url, paramStr, reqHeaders);

用于测试的签名的辅助接口

  1. 接口地址
    • https://plt.v5ppt.com/auth/sign-test/*
    • 用于测试请求接口签名是否正确，不参与业务逻辑，仅用于测试
    • 支持请求方法：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、TRACE
  2. 基本使用说明
    • 按照开放接口的文档要求使用与要求相符的请求方法、header、参数、path
    • 使用具体接口的 url path 替换https://plt.v5ppt.com/auth/sign-test/*中的*
    • 示例：请求搜索接口 POST https://plt.v5ppt.com/api/search ，则请求地址为 https://plt.v5ppt.com/auth/sign-test/api/search
  3. 请求参数
    • 任意参数
  4. 请求体
    • 任意请求体
  5. 请求返回结果示例：https://plt.v5ppt.com/auth/sign-test/api/search
    {
  "code": 200,
  "msg": "成功",
  "data": {
    "Access Key": "",
    "other": [
      "GET",
      "/api/search",
      "application/x-www-form-urlencoded; charset=utf-8",
      "",
      ""
    ],
    "二次绑定参数": {},
    "待签名字符串": "&GET/auth/sign-test/application/x-www-form-urlencoded; charset=utf-8",
    "接收签名": "",
    "生成签名": "09041111c68f36597a7190423d2274c4ea5184b5f74cd0e2b46fa0385dac391a",
    "签名base64解码": "",
    "请求参数": {},
    "错误列表": [
      "请求Timestamp不能为空",
      "请求X-Request-Id不能为空",
      "AccessToken格式错误",
      "请求过期",
      "签名校验失败"
    ]
  }
}
Contributors: yuhao, zhangjiasheng