一分钟了解钉钉接口开发中的坑

钉钉接口开发介绍

钉钉官网地址：钉钉官网

钉钉开放了丰富的服务端接口能力，开发者可以借助这些接口能力，实现企业系统与钉钉的集成打通。

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

钉钉在线调试工具：API Explorer

接口说明格式如下：

请求方式：GET/POST（HTTPS）
请求地址：https://oapi.dingtalk.com/gettoken?appkey=APP_KEY&appsecret=APP_SECRET
请求包体：
...
参数说明：
...
SDK请求示例：
...
返回结果：
...

1）请求方式，标明接口调用的HTTP方法，区分HttpGet/HttpPost请求。所有的请求都为HTTPS协议。

2）请求地址，接口的请求地址。

3）请求包体/参数说明，标明请求参数示例及说明，参数说明包括字段含义、取值范围。

4）SDK请求示例，使用SDK时调用接口的Java代码示例， 钉钉最新SDK下载。
注意：这里下载的SDK只有两个jar包，缺少一个lippi-oapi-encrpt.jar；
下载地址：SDK完整的下载

5）返回结果/参数说明，标明返回参数示例及说明。所有接口的返回结果里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功（errcode意义请见全局错误码）。而errmsg仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。

钉钉白名单

每一个公司都有不同的AgentId，AppKey，AppSecret，一下是它们的名词解释：
AgentId：在创建应用时，系统会自动生成一个AgentId，可用于发送企业会话消息等场景。

AppKey：在创建应用时，系统会自动分配一对AppKey和AppSecret，该AppKey是应用开发过程中的唯一性标识。

AppSecret：AppSecret和上面AppKey一同生成，使用AppKey和AppSecret来换取access_token。

1.为什么申请白名单

钉钉虽然提供了丰富的接口，但是考虑安全问题，开发者在开发应用调用接口前，需要先申请并设置接口调用权限。具体参考:钉钉服务API

在调用接口会遇到——“访问ip不在白名单之中”——，ip白名单，帮助防火墙做规则,访问ip不在白名单之中解决办法地址。

访问ip不在白名单之中的解决办法：
当请求开放平台服务端接口遇到“访问IP不在白名单”问题时，表示您的请求IP不在该应用出口IP白名单内。

可以按照以下方式排查并修改：

（1）对比调用接口的应用中的AppKey值，与报错信息中返回的AppKey值是否一致。如果不一致，可能是由于AppKey或者AppSecret使用的是其他的，导致在获取AccessToken值时会提示错误。

注意：如果错误信息中返回的是CorpId值，说明创建应用时间较早，添加IP的路径为：登录开发者后台-基本信息-开发信息旧版-找到该应用使用的CorpSecret值，点击设置修改IP；如果当前账号按照上述路径查看不到CorpSecret，需要该企业主管理员账号查看并修改IP。

（2）如果应用中的AppKey值跟报错信息中返回的AppKey值是一致的，解决办法是将报错信息中的request IP添加到该应用的出口IP里面。

注意：如果在应用的IP出口白名单内添加返回的IP，出现占用的错误提示，参考“IP被占用”。

2.申请白名单步骤

错误信息：

{
    "errcode": 88,
    "sub_code": "60020",
    "sub_msg": "请参考FAQ：https://open-doc.dingtalk.com/microapp/faquestions/cvbtph。错误原因：访问ip不在白名单之中,request ip=1.193.82.51 appKey(dingb38lbcp5xxugjvqo)",
    "errmsg": "ding talk error[subcode=60020,submsg=请参考FAQ：https://open-doc.dingtalk.com/microapp/faquestions/cvbtph。错误原因：访问ip不在白名单之中,request ip=1.193.82.51 appKey(dingb38lbcp5xxugjvqo)]",
    "request_id": "6nwk6wv507v8"
}

（1).登录钉钉后台

（2).找到对应的微应用，点击设置

（3).点击查看详情

（4).点击修改

（5).将提示报错的IP写到白名单上去

（6).提交→完成白名单申请，申请后可以在该白名单ip下进行接口测试；

接口调用

在开发过程中我们需要获取access_token，在以后每次调用接口时都需要使用，是一个身份的象征。

获取access_token

获取access_token
【注意】正常情况下access_token有效期为7200秒，有效期内重复获取返回相同结果，并自动续期。

调试工具：在线调试

请求方式：GET（HTTPS）

请求地址：https://oapi.dingtalk.com/gettoken?appkey=key&appsecret=secret

参数说明：

参数	参数类型	必须	说明
appkey	String	是	应用的唯一标识key
appsecret	String	是	应用的密钥

SDK请求示例（JAVA）：

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/gettoken");
OapiGettokenRequest request = new OapiGettokenRequest();
request.setAppkey("appkey");
request.setAppsecret("appsecret");
request.setHttpMethod("GET");
OapiGettokenResponse response = client.execute(request);

返回说明：

{
    "errcode": 0,
    "errmsg": "ok",
    "access_token": "fw8ef8we8f76e6f7s8df8s"
}

我在这只说最主要的接口，若调用别的接口可参考官方文档:钉钉开发API