钉钉测试

钉钉测试知识思维导图，主要包括：成为钉钉开发者、第三方企业应用、服务端API等内容。希望对你有所帮助。

钉钉

成为钉钉开发者

步骤

1、实名认证

打开钉钉手机客户端，单击个人头像，然后选择设置

在设置页面，选择我的信息

在个人信息页面，完成个人实人认证

2、申请权限

联系组织主管理员申请子管理员和开发者权限

组织管理员需要在OA管理后台将开发者添加为子管理员并赋予相关的开发者权限和工作台管理权限。详情请参考

3、登录开发者后台

开发者只需登录开发者后台，即可进行应用开发。详情请参考

开发须知

1、调用钉钉服务端接口时，需使用HTTPS协议、JSON数据格式、UTF-8编码，访问域名为 https://oapi.dingtalk.com 。POST请求请在HTTP Header中设置 Content-Type:application/json。

2、在调用服务端接口前，确保你已了解调用频率限制。详情请参考

3、在调用服务端接口前，确保你已经设置了对应的接口权限。详情请参考

4、无论是哪种应用（H5应用还是小程序），都必须接入钉钉免登，即在用户打开应用时可直接获取用户身份无需输入钉钉账号和密码。详情请参考：

免登授权码

H5应用免登

5、如果开发的是小程序应用，确保你已经在开放平台配置了小程序HTTP域名和开发人员。详情请参考

6、如果开发的是H5微应用，需要进行JS API鉴权。详情请参考

7、推荐配置事件订阅。钉钉会向应用推送订阅的事件，例如部门变更、签到通知、打卡通知等。通过订阅这些事件，开发者可以更好地与钉钉集成。详情请参考

第三方企业应用

注意：在开发企业第三方应用前，确保你的组织已经完成应用服务商认证。

说明

应用类型：第三方企业应用

开发者：应用服务商的开发者

使用人员：购买开通该三方应用的企业内部人员

关联的组织：作为应用服务商的开发者开发第三方企业应用，你的企业组织必须完成应用服务商认证。详情请参考

支持的能力

小程序

H5微应用

交付方式

支持上架到钉钉应用广场。详情请参考

创建应用

1、登录钉钉开发者后台

2、在应用开发页面，选择第三方企业应用 > 小程序或H5微应用，然后单击创建应用

3、填写应用的基本信息，然后单击确定创建

4、在应用的凭证与基础信息页面获取应用的基础信息

配置应用

服务器出口IP

添加服务端API权限

1、普通接口权限：单击添加接口权限添加需要的接口权限

在权限管理页面设置接口使用权限接口权限是以应用维度做授权，鼓励应用使用尽可能多的接口，实现与钉钉核心能力的全面互通

在创建应用后，需要完成基础配置，例如服务器出口IP、接口权限等

开发应用

开发流程

1、调用服务端接口，进行业务集成。例如调用审批接口，自定义审批流。更多信息请参考如何调用服务端API。

2、注册回调：第三方企业应用必须要注册回调，接收企业授权开通应用事件，用于通知应用哪个组织开通了本应用，第三方应用后台收到此事件后，需要初始化企业信息，完成应用的开通。推荐使用RDS和HTTPSync推送方式，该方式的应用授权流程更简单。详情请参考回调事件概述。

3、授权应用开通：钉钉应用广场中的第三方企业应用，企业管理员可以授权开通。授权开通过程中需要接收企业开通的回调事件，钉钉支持不同的回调推送方式。回调方式不同，应用开通的流程也不同。详情请参考授权应用开通。

4、第三方应用必须接入钉钉免登、通讯录和工作通知能力。详情请参考接入服务端能力。

注册回调事件

回调事件方式

1、RDS数据推送

1、入驻聚石塔

2、创建RDS实例

3、设置数据推送源

4、查看钉钉推送的数据

2、HTTP数据推送（不推荐）

3、SyncHTTP推送

1、注册回调事件流程

1、配置HTTP地址和订阅事件

2、向接口地址推送“check_url”事件

3、返回加密字符串“success”

4、注册成功

2、配置请求地址和订阅回调事件

3、推送数据说明

4、接收并响应回调事件

5、消息加解密

4、RDS和SyncHTTP推送数据表说明

三者对比

授权应用开通

RDS推送（聚石塔/钉钉云）和SyncHTTP推送

推荐第三方企业应用使用RDS推送来接收数据，安全稳定性能高。

部署应用

上架到钉钉应用广场的第三方企业应用必须部署到聚石塔。其他分发方式，可根据体情况选择部署方式

部署方式

1、定向分发

2、线下拓客

3、上架到应用广场（必须部署到聚石塔）

聚石塔

1、入驻聚石塔

1、申请淘宝企业账号

2、获取令牌

3、绑定聚石塔

4、使用钉钉账号登录聚石塔

2、应用部署

1、创建集群

2、创建应用

3、配置环境

4、应用发布

5、流量接入

6、安全组申请

准备工作

1、已完成应用服务商入驻

2、已完成聚石塔账号绑定

3、钉钉云迁移聚石塔方案

1、绑定聚石塔账号

2、准备迁移环境

3、云产品迁移

4、聚石塔应用部署

5、应用切换

6、迁移咨询

4、RDS推送

1、概述：RDS推送是替换HTTP协议推送的升级版本，是钉钉开放平台结合阿里云独创的一套推送方案

2、配置

1、使用聚石塔RDS数据库

1、创建RDS实例

2、设置数据推送源

2、使用自有MySQL

1、安装MySQL

2、设置字符集

3、创建数据表

4、设置数据推送源

钉钉云

测试应用

1、登录开发者后台，找到已创建的应用

2、单击版本管理与发布

3、单击创建体验组织创建一个体验组织并添加体验人员。如果已有体验组织，选中一个体验组织

4、单击授权

应用自检

1、功能自检

1、登录开发者后台

2、选择已创建的第三方企业应用

3、单击目标应用，进入详情页，选择应用自检，然后点击开始检查

基础设置检查

应用部署

4、单击下一步，进入安全审核界面

2、安全审核

1、下载安全测试报告模板，并严格按照《安全性认证》文档完成安全监测

2、上传你的安全测试报告，然后阅读并勾选上传协议

3、单击下一步，进入稳定性监控界面

3、稳定性监控

1、选择接入稳定性监控系统

2、单击自检完成，完成自检

当应用完成自检后，可以在钉钉市场中进行上架或进行线下推广活动

发布和安装应用

1、发布小程序应用

1、登录开发者后台、找到已创建的应用

2、单击版本管理与发布

3、单击设置体验组织创建一个体验组织并添加体验人员

4、单击开通应用

5、在小程序IDE中选择要关联的体验组织然后单击上传

6、在开发者后台，单击设为体验版本

7、单击灰度，设置灰度的组织

8、单击发布发布该应用

9、单击提交审核，根据提示，依次提交产品、安全和稳定性审核

10、完成审核后，可使用部署二维码进行线下部署或提交产品上架

2、发布H5微应用

1、登录开发者后台、找到已创建的应用

2、单击版本管理与发布

3、单击设置体验组织创建一个体验组织并添加体验人员

4、单击授权

5、单击提交审核，根据提示，依次提交产品、安全和稳定性审核

6、完成审核后，可使用部署二维码进行线下部署或提交产品上架

定向应用分发

1、登录开发者后台

2、单击应用开发，选中第三方企业应用

3、单击目标应用进入应用详情页，然后单击定向应用分发

4、单击创建分发申请

5、在创建应用分发申请页面填写一下信息

项目名称

相关钉钉小二联系方式

应用安装方式

导入清单

6、填写完成后单击提交，提交审核

7、在审核通过后，可以直接单击应用分发进行部署，也可以使用部署二维码进行线下部署

子主题

服务端API

API总揽

如何调用服务端API

1、文档格式约定

p, li { white-space: pre-wrap; } 请求方式：GET/POST（HTTPS） 请求地址：https://oapi.dingtalk.com/gettoken?appkey=APP_KEY&appsecret=APP_SECRET 请求包体： ... 参数说明： ... 返回结果： ... 示例 ...

1、请求方式：接口使用的HTTP方法和请求协议。所有接口都使用HTTPS协议

2、请求地址：接口的请求地址。钉钉服务端接口的访问域名为 https://oapi.dingtalk.com。请求参数使用“&”分隔。请求地址中的大写单词是需要替换的变量值

3、请求包体/参数说明：提供请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考定义范围

4、返回结果/参数说明：提供返回参数示例及说明

注意

所有接口在调用失败时都会返回errcode和errmsg。开发者可根据errcode和errmsg排查问题。请不要仅根据errmsg判断调用是否成功。当请求返回结果中返回了errcode且不为0时可判断为请求失败。errmsg是对errcode的说明，供开发者参考排查问题。我们对接口的返回字段做了简化处理，如果字段的值为空或者null，将不返回该字段。

2、接口调用流程

1、添加接口调用权限。应用创建后默认只开放登录和消息通知接口的调用权限，您需要根据开发需要，添加对应的接口使用权限。详情请参考添加接口调用权限

2、获取应用的access_token。access_token相当于身份凭证。调用接口是，通过access_token来鉴权调用者身份

3、调用方式

1、API Explorer

API Explorer是可视化在线API调用工具，可实时查看API请求和返回结果

2、SDK

钉钉开放平台提供了Java、PHP、Python、.NET SDK供开发者使用。单击服务端SDK下载

服务端SDK下载

SDK请求示例（PHP）

p, li { white-space: pre-wrap; } include "TopSdk.php"; // DingTalkConstant::$METHOD_GET 要与下面调用接口url要求的保持一致 $c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_GET , DingTalkConstant::$FORMAT_JSON); $req = new OapiUserGetRequest(); $req->setUserid("userid1"); $resp=$c->execute($req, $accessToken,"https://oapi.dingtalk.com/user/get"); var_dump($resp)

1、定义Client对象，设置接口地址URI。一般情况，无需拼接URL后面的参数，比如access_token；需要注意部分Post接口，需要在URI后拼接除access_token外的个别参数

2、构造Request对象，接口对应的request对象，一般规则是Oapi+接口Path驼峰形式+Request，如/user/get接口，请求对象是OapiUserGetRequest

3、调用Request的方法设置参数，注意参数HttpMethod，默认是POST，如果是GET类型接口，需要这样设置request.setHttpMethod("GET")

4、调用client.execute执行，其中access_token同样可以使用SDK获取到。同时，/gettoken，/sns/gettoken，/service/get_suite_token等获取token的接口在调用execute时，无需再传token参数

5、执行后得到Response对象，是与Request对应的，然后可获取执行结果

2、SDK下载（PHP）

添加接口调用权限

1、添加普通接口权限

1、登录开发者后台

2、在应用开发页面，单击目标应用进入应用详情页面

3、在应用详情页，单击接口权限，然后单击添加接口权限

4、在弹出的页面，选择要添加的接口，然后单击确认

2、申请开通新接口

1、登录开发者后台

2、在应用开发页面，单击目标应用进入应用详情页面

3、在应用详情页，单击接口权限，然后单击添加接口权限

4、在添加接口权限页面，单击开通新接口

5、选择要开通的新接口，然后单击申请提交并完成申请说明

3、设置通讯录权限范围

1、管理员登录开发者后台

2、在应用开发页面，单击目标应用进入应用详情页面

3、单击接口权限，然后选择权限范围

全部员工：可获取全部员工的

部分员工：选择授权开放通讯录权限的部门和人员

注意

调用钉钉服务端接口前，需要先添加所需接口的调用权限，应用创建后，系统默认添加身份验证和消息通知接口权限。鼓励应用使用尽可能多的接口，实现跟钉钉核心能力的全面互通。 接口权限是以应用为维度授予的，每个应用的接口权限都是独立存在的，如果多个应用都需要调用同一个接口，那么每个应用都要添加相对应的接口调用权限。例如：企业内同时拥有A、B两个应用，且应用A已经拥有通讯录权限，此时如果应用B要获取企业通讯录，那么也需要添加通讯录权限，添加方式与应用A一样。 注意 不是所有接口都可以直接开通使用，具体参照接口的使用范围和适用类型，部分接口需要付费或满足特定条件后才可使用。

调用频率限制

1、企业和ISV共享

1、每个接口每秒能被调用的次数都有一个上限，如触发限流，会返回错误码90002。出现此错误时，请等待1秒钟后再重新调用该接口

2、每个IP调用开放平台所有接口总量，不能超过20秒3000次。如触发限流，会禁止调用5分钟。该限流不会返回对应的错误码，返回的是一个html页面，需要开发者自行处理。你可以通过增加IP的数量，来控制调用量

2、企业独享

1、每个企业的每个appkey调用单个接口的频率不可超过40次/秒，否则返回错误码90018

2、每个企业的每个appkey调用单个接口的频率不可超过1500次/分，否则返回错误码90006

3、每个企业调用单个接口的频率不可超过1500次/分，否则返回错误码90005

3、ISV独享

1、每个ISV（应用服务商）调用单个企业的单个接口频率不可超过40次/秒，否则返回错误码90019

2、每个ISV（应用服务商）调用单个接口的频率不可超过2000次/分，否则返回错误码90010

3、每个ISV（应用服务商）调用单个企业的单个接口频率不可超过1500次/分，否则返回错误码90008

4、每个ISV的套件调用单个企业的单个接口频率不可超过1000次/分，否则返回错误码90014

错误码

获取凭证

1、获取第三方应用授权企业的access_token

定制服务商应用和服务商可通过此接口获取授权企业的access_token。调用服务端API获取应用资源时，需要通过access_token来鉴权调用者身份进行授权。 注意 在使用access_token时，请注意： access_token的有效期为7200秒（2小时），有效期内重复获取会返回相同结果并自动续期，过期后获取会返回新的access_token。 开发者需要缓存access_token，用于后续接口的调用。因为每个应用的access_token是彼此独立的，所以进行缓存时需要区分应用来进行存储。 不能频繁调用gettoken接口，否则会受到频率拦截。推荐使用SDK调用本接口： HTTP调用方式必须设置signature参数，钉钉会对请求进行签名验证，以保证安全。签名计算方式，请参考第三方访问接口的签名计算方法https://developers.dingtalk.com/document/app/signature-calculation-method-for-third-party-access-interfaces-1?spm=ding_open_doc.document.0.0.3a256573UHS1Uk#topic-1949473。 SDK调用方式无需自行进行签名计算，钉钉SDK已自带签名功能。推荐使用钉钉提供的SDK进行调用，SDK下载地址参见服务端SDK下载https://developers.dingtalk.com/document/resourcedownload/download-server-sdk?spm=ding_open_doc.document.0.0.3a256573UHS1Uk#topic-1950896。

1、基本信息

1、请求方式：POST

2、请求地址：https://oapi.dingtalk.com/service/get_corp_token

2、请求参数（SDK请求）

3、请求参数（HTTP请求）

4、返回参数

示例：{ "access_token":"1cc1bb3xxxx", "errcode":0, "errmsg":"ok", "expires_in":7200 }

1、expires_in->Number->授权企业的access_token超时时间，单位秒

2、access_token->String->授权企业的access_token

3、errmsg->String->返回码的描述

4、errcode->Number->返回码

2、获取第三方企业应用的suite_acess_token

调用本接口获取第三方企业应用的suite_access_token。 该suite_access_token主要用于获取第三方企业应用的信息，在调用以下接口时会使用第三方企业应用的suite_access_token： 获取授权企业的永久授权码 获取授权应用的基本信息 获取企业授权信息 激活应用

1、基本信息

1、请求方式：POST

2、请求地址：https://oapi.dingtalk.com/service/get_suite_token

2、Body参数

3、返回参数

示例：{ "errcode":0, "errmsg":"ok", "suite_access_token":"67477fed82e63563a320xxxx", "expires_in":7200 }

1、errmsg->String->返回码的描述

2、errcode->Number->返回码

3、suite_access_token->String->第三方企业应用的凭证

4、expires_in->Number->第三方企业应用的凭证过期时间，单位秒

说明 suite_access_token有效期为7200秒，过期之前建议服务端做定时器主动更新，而不是依赖钉钉的定时推送。

身份验证（第三方企业应用免登）

在钉钉上开发的第三方企业应用，作为公开的云端SaaS服务可以让企业客户安装使用。管理员开通应用后，企业员工在钉钉内使用该ISV应用时，无需输入账号密码便可直接登录该应用。

1、开发流程

建议用户信息保存在前端缓存中（dd.setStorage）或者cookie中，避免每次进入应用都调用钉钉接口进行免登

1、获取免登授权码

2、获取access_token

3、获取用户userid

4、获取用户详情

2、示例代码

/** * * 第三方企业应用免登 * @author openapi@dingtalk * 2020-11-3 */ @RestController public class LoginController { /** * 欢迎页面，通过 /welcome 访问，判断后端服务是否启动 * * @return 字符串 welcome */ @GetMapping("/welcome") public String welcome() { return "welcome"; } /** * * @param requestAuthCode * @return * ServiceResult * 2020-11-3 */ @RequestMapping(value = "/login", method = RequestMethod.POST) public ServiceResult<Map<String, Object>> login (@RequestParam("authCode") String requestAuthCode) { // 获取access_token，注意正式代码要有异常流处理 String access_token= AccessTokenUtil.getToken(); // 获取用户信息 DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getuserinfo"); OapiUserGetuserinfoRequest request = new OapiUserGetuserinfoRequest(); request.setCode(requestAuthCode); request.setHttpMethod("GET"); OapiUserGetuserinfoResponse response; try { response = client.execute(request, access_token); } catch (ApiException e) { // TODO Auto-generated catch block e.printStackTrace(); return null; } // 查询得到当前用户的userId // 获得到userId之后应用应该处理应用自身的登录会话管理（session）,避免后续的业务交互（前端到应用服务端）每次都要重新获取用户身份，提升用户体验 String userId = response.getUserid(); Map<String, Object> returnMap = new HashMap<String,Object>(); returnMap.put("userId", userId); return ServiceResult.success(returnMap); } }

3、免登常见问题

HTTP回调

1、HTTP回调流程

1、开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的回调事件

2、钉钉会向应用配置的HTTP地址推送回调事件数据包。使用应用创建时开发者在开发者后台填写的应用加解密key来进行加密，开发者填写的应用Token进行签名。详情请参考测试回调URL事件

3、应用在收到推送后需要进行验证签名和解密，并且返回包含经过加密的字符串的JSON数据

4、调用注册回调事件接口接口要接收的回调事件

2、配置请求地址和事件

1、登录开发者后台。找到已创建的应用，进入应用详情页

2、单击开发管理，然后单击修改，推送类型选择HTTP推送

3、配置用于接收请求的HTTP地址

说明 每个应用只能配置一个回调URL，该应用订阅的所有事件通知都会发送到该请求网址

1、token2、数据加密秘钥3、回调URL

4、配置完成后，单击验证有效性按钮时，开放平台会向你配置的网址推送一个application/json格式的 POST请求, 用于验证你配置的网址的合法性

5、成功配置请求地址后，单击右上角保存

3、第三方企业应用回调事件

1、企业授权开通应用事件

2、解除授权事件

3、启用和停用应用事件

4、通讯录授权范围变更事件

5、审批事件

6、用户购买下单事件

应用在收到推送后需要进行验证签名和解密，并且返回包含经过加密的字符串的JSON数据