开放能力配置说明

配置说明

    开放能力提供了除原本发送消息接口以外的设置相关的接口。原本发送消息的接口是通过用户令牌来调用的，考虑到这种方式安全性较低，容易泄露，所以开放能力接口采用AccessKey的校验方式。在请求接口的时候，需要在header中带上key名为“access-key”的内容，否则会请求失败。

    由于开放接口权限较高，泄露后会给用户造成严重后果，所以默认是禁用状态，需要用户手动的在设置中开启，并在调用AccessKey接口之前配置好secretKey和安全IP地址。

:::caution
开放能力接口请求限制12次/分钟，超过会返回900错误码！
:::

一. 获取AccessKey

1. 使用说明

    AccessKey是开放能力接口的全局唯一的接口调用凭证，调用其他各接口都需要使用AccessKey。开发者需要进行妥善保存。AccessKey的存储至少要保留32个字符空间。AccessKey的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的AccessKey失效。

微加机器人的开放能力接口调用所需的AccessKey的使用及生成方式说明：

1. 用户需要提前配置自己的secretKey，建议至少32位数字、英文大小写随机组合。将请求的服务器IP添加到安全IP列表中。接口使用的token同发送消息的token。

2. 建议第三方开发者使用中控服务器统一获取和刷新AccessKey，其他业务逻辑服务器所使用的AccessKey均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致AccessKey覆盖而影响业务；

3. 目前AccessKey的有效期通过返回的expireIn来传达，目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新AccessKey。在刷新过程中，中控服务器可对外继续输出的老AccessKey，此时pushplus后台会保证在5分钟内，新老AccessKey都可用，这保证了第三方业务的平滑过渡；

4. AccessKey的有效时间可能会在未来有调整，所以中控服务器不仅需要内部定时主动刷新，还需要提供被动刷新AccessKey的接口，这样便于业务服务器在API调用获知AccessKey已超时的情况下，可以触发AccessKey的刷新流程。

5. 对于可能存在风险的调用，在开发者进行获取AccessKey调用时请求的服务器需要在用户设置的安全IP列表内，否则会返回编码为403的错误。

2. 接口调用说明

• 请求地址：https://www.weplusbot.com/pro/api/getAccessKey
• 请求方式：POST
• 请求参数:

  {
  "token": "d90******c20",
  "secretKey": "qLc******gdk"
  }
  

• 请求参数说明

参数名称	是否必填	默认值	说明
token	是	无	用户令牌，同发送消息接口令牌
secretKey	是	无	用户密钥

• 响应内容

  {
  "code": 200,
  "msg": "请求成功",
  "data": {
    "accessKey": "d7b******62f",
    "expiresIn": 7200
  }
  }
  

• 响应字段说明

参数名称	类型	说明
accessKey	字符串	访问令牌，后续请求需加到header中
expiresIn	数字	过期时间，过期后需要重新获取

二、使用示例

获取用户设置接口

• 请求地址：https://www.weplusbot.com/pro/open/userSetting/getUserSetting
• 请求方式：GET
• (header) access-key: d7b******62f(获取到的AccessKey)
• 请求参数，url传参
• 请求参数：无
• 响应内容

  {
  "code": 200,
  "msg": "执行成功",
  "data": {
    "userId": "1",
    "botId": "1",
    "friendIsEnable": 1,
    "callbackUrl": "https://request.worktile.com/xvELO2hcn",
    "token": "a271******a53d1",
    "secretKey": "2409&&&&&&8a5f",
    "ipList": "120.127.123.185",
    "apiEnable": 1,
    "lastDay": "2024-12-28"
  }
  }
  

• 响应字段说明

参数名称	类型	说明
userId	数字	用户id
botId	数字	机器人id
friendIsEnable	数字	好友是否可用
callbackUrl	字符串	消息回调地址
token	字符串	访问令牌
secretKey	字符串	密钥
ipList	字符串	IP白名单
apiEnable	数字	开放能力是否启用
lastDay	日期	到期时间