资源工坊

如何调用服务端API ​

开发前须知 ​

  1. 在调用服务端 API 之前，需要先创建应用，才可以获取权限和凭证。了解应用类型和开发流程。
  2. 在调用服务端 API 之前，确保已设置 API 所需要的权限。权限可在开发者后台-权限申请处申请。
  3. 在调用服务端 API 之前，确保已获取 API 所需要的凭证（token），并加入到请求中。凭证获取流程可见API凭证。
  4. 在调用服务端 API 之前，请在开发者后台-安全设置设置IP白名单（服务端接口限制了指定IP的请求才可调用）。
  5. API调用时，需要通过WPS-4算法进行签名鉴权，了解签名说明。
  6. 了解常用术语概念定义将有助于你正确调用接口，了解概念说明。
  7. API调用报错时将返回错误状态码，不同状态码含义不同。状态码含义可见状态码说明。
  8. 应用也可通过订阅协作提供的事件，获取应用消息通知，了解事件订阅。

API文档约定格式 ​

json
请求：
	请求说明         //接口调用地址、方式、签名、支持调用的应用类型、所需权限
	请求头           //HTTP请求中的header参数，要求使用WPS-4签名
	路径参数         //这部分参数需要放置在URL中，文档中一般以：开头
	查询参数         //这部分参数需要在URL后使用？进行拼接，多个查询参数间用 & 分隔
	请求地址示例      //一般以{请求方式}+{请求地址}+{路径参数}+{查询参数}形式呈现
	请求体           //这部分参数需要放置在body中，一般为json格式
	请求体示例        //对应API成功请求参数的样例
响应：
	响应体           //一次API调用后，HTTP响应中body部分的内容
	响应体示例        //API成功请求结果的样例

API调用流程 ​

1. 申请API调用所需权限 ​

登录开发者后台，选择进入具体应用，在权限申请模块添加所需权限，并申请权限开通：

  • 企业自建应用：添加申请权限后，页面提示敏感项修改，可提交审核到本企业管理后台，由超管审核开通并授权。

目前协作需要申请的权限如下表所示：

scope权限名称说明
kso.contacts.read通讯录查询以管理员身份读取通讯录
kso.im.message.send发送消息以应用身份发送协作消息
kso.im.websocket.write使用websocket推送以应用身份使用协作websocket能力
kso.im.chat.manage管理会话及会话成员信息以应用身份管理协作单聊、群聊会话及其成员信息
kso.im.chat.read查询会话及会话成员信息以应用身份查询协作单聊、群聊会话及其成员信息
kso.app.manage管理应用查询和管理应用及应用在企业内的使用信息
kso.im.file.manage管理协作文件管理协作内的文件资源
kso.im.jsapi.authorized授权协作JSAPI使用协作JSAPI
kso.im.user2bot.notification获取用户发给机器人的单聊消息以应用身份接收单聊中用户向机器人发送的消息
kso.im.chat2bot.notification获取用户在群聊中@机器人的群聊消息以应用身份接收群聊中用户@机器人的消息
kso.im.chat.read.notification订阅群组变更通知接收群组设置、成员数据变更的订阅通知
kso.task.read查询待办信息查询用户的待办信息
kso.task.write更新待办信息查询和更新用户的待办信息
kso.task.category.write更新待办分类查询和更新待办的分类
kso.calendar.event.write更新日程信息查询和更新用户的日程信息
kso.calendar.event.read查询日程信息查询用户的日程信息
kso.workflow.template.write更新审批模版信息查询和更新审批模版及模版组信息
kso.workflow.template.read查询审批模版信息查询审批模版及模版组信息
kso.workflow.approval.write更新审批单信息查询和更新审批单信息
kso.workflow.approval.read查询审批单信息查询审批单信息
kso.announce_role.readwrite查询和管理公告角色允许应用创建、修改和查询公告的角色信息
kso.attendance_punch.read查询打卡记录信息允许应用查询用户打卡信息
kso.attendance_approval_record.write管理假勤审批记录查询和修改假勤审批记录

2. 获取API调用所需凭证 ​

接口访问凭证分为用户授权凭证、应用授权凭证、企业授权凭证。具体获取流程请参考使用方接入流程。