DingTalk「开发者说」
钉钉服务端OpenAPI开发工具实践
摘要：钉钉开发工具提供一站式API 调试、诊断、集成、管理等能力，降低应用开发门槛，提升开发效率。本文主要介绍了钉钉开发的四个API工具及实操演练。
分享人：笑乾，钉钉服务端OpenAPI能力建设负责人
目录：
- 钉钉API开发工具简介
- 钉钉API工具初探
- 实践操作
正文：
一、 钉钉API开发工具简介
1. 关于钉钉开发工具
钉钉开发工具为开发者提供一站式API 调试、诊断、集成、管理等能力，并支持开发工具下载使用，降低应用开发门槛，提升开发效率。
2. 钉钉API工具箱地址
https://open-dev.dingtalk.com/fe/api-tools#/
3. 常用工具
- API工具：API调试、API诊断、API调用、API流控；
- 其他工具：微应用调试工具、小程序开发工具、内网穿透工具、DingTalk Design CLI、D-Design 组件库；
二、 钉钉API工具初探
钉钉API工具主要有以下几种：
- API调试：可视化API在线调试，快速入门API开发；
- API诊断：快速定位API使用问题，获取有效解决方案；
- API调用：总览API调用稳定性，洞察出错原因；
- API流控：自助申请提升限流阈值，保障业务稳定；
1. API调试
API Explorer
API Explorer是一款可视化的服务端API在线调试工具，避免了繁杂的环境搭建，直接通过在线填充API入参来发起实际的API请求。
主要功能
- API检索：汇集钉钉 1000+ API，可根据API名称或路径快速检索；
- API文档：内嵌开发文档，便捷查阅API信息；
- 代码生成：根据填写的API请求参数，动态生成可执行的多语言SDK代码示例；
- 在线调试：在线发起真实的API请求，显示实际请求地址和请求参数；
- 结构化输出：输出API调用结果、响应时间、状态码等；
注意事项
- 在线调试需要登录态，其他功能不需要；
- 在线调试需要先获取AccessToken（API访问凭证）；
- AK/SK的所属组织需要与当前登录组织一致，并且操作者需要具有该密钥的使用权限（微应用权限）；
- 在线调试会对当前登录企业的线上数据发起真实的API请求，谨慎操作写接口。
2. API诊断
API诊断根据单次API调用返回的requestid，可快速定位、分析错误原因；如果没有获取到requestid，可以通过日志检索功能定位问题。
API诊断后会提供以下信息：
请求时间；
- HTTP下上文；
- API信息；
- 出入参数；
- 错误原因；
- 解决方案
日志检索
日志检索是根据筛选条件API调用日志，获取以下信息：
- 请求时间；
- HTTP下上文；
- API信息；
- 应用信息；
- 出入参数；
3. API统计
进入API统计页面，首先会展示企业内应用近7天的OpenAPI运行情况总览，包括：
- 使用API数；
- 调用次数；
- 出错次数；
- 限流次数；
- 错误率；
注意：数据为离线数据（T - 1），即仅支持近8天至昨日（T - 8 ~ T - 1）的时间筛选。
查看应用内API调用明细
在总览表中点击目标应用，可以查看调用详情：
- 接口名称；
- 总调用次数；
- 调用调出次数；
- 调用出错率；
- 限流次数；
查看API错误分布
- 在调用详情页点击“查看错误分布”，查看API错误情况，包含所有错误码以及相对应的数量；
- 点击“去诊断”会跳转到诊断工具页面，进行错误诊断分析以及提供解决方案；
- 如果存在限流错误，可以点击“申请流控”。
4. API流控
钉钉流控策略包含三个维度：全局维度、IP维度和应用维度。
a. 全局维度
当所有应用调用同一个接口超过最高频率时，触发限流，返回错误码90002。
b. IP维度
- 每个IP调用所有接口总量，最高20秒6000次；
- 触发限流，会禁止调用5分钟；
- 限流不会返回对应的错误码，返回的是一个html页面，需要开发者自行处理；
错误示例：
{
"status":1111,
"wait":5,
"source":"x5",
"punish":"deny",
"uuid" :"xxx"
}
c. 应用维度
- 企业内部应用
- 每个应用，调用每个接口，最高频率40次/秒。触发限流，返回错误码90018；
- 每个应用，调用每个接口，最高频率1500次/分。触发限流，返回错误码90006；
- 第三方企业应用
- 每个应用，对每个授权企业，调用每个接口，最高频率40次/秒，触发限流，返回错误码90019；
- 每个应用，对每个授权企业，调用每个接口，最高频率1000次/分。触发限流，返回错误码90014。
针对应用维度的限流问题，钉钉提供流控工具，可以自助申请提升应用维度限流阈值。
三、 API工具实践
API工具实践流程图
1. 创建应用
进入开发者后台，选择应用开发-企业内部应用-创建应用，填写应用信息，单击“确定创建”；
2. 申请权限
进入“权限管理”，查找“通讯录管理”（本次实践以通讯录管理为例），单击“申请权限”；
3. 获取accessToken
进入调试工具页面，选择“获取企业内部应用的accessToken”，复制新创建应用的appKey和appSecret填写到相应位置，即可获取accessToken；
4. 调用接口
选择用户管理2.0-获取管理员列表，填入获取的access_token，单击“发起调用”，右侧栏中会显示调试结果；
使用调试结果中的userid，进行用户详情接口调用操作，即可在右边栏看到用户信息详情以及示例代码；
5. 错误诊断
在userid里键入一个错误信息，并查看调试结果；
复制request_id，进入API诊断页面，输入该request_id，查看诊断结果及解决方案；
6. 日志检索
进入日志检索页面，选择起止时间、请求URL、requestid、返回状态或错误码进行检索，可以查询到符合条件的调用接口信息列表，点击前面“+”号可以查看调用详情；
7. 查看应用调用接口详情
进入API统计页面，选择调用日期进行查询，单击“查看调用详情”；
进入详情页面，查看应用调用接口列表；
8. 查看错误分布
接上步，在调用接口列表页面单击“查看错误分布”；
9. 申请提升限流阈值
同上，在调用接口列表页面单击“申请提升限流”；
注意：
- “申请理由”请详细填写；
- 申请提交后需要1-2个工作日的审批流程，在“错误分布”页面可以查看审批状态。
