钉钉开放平台-小程序开发实战（钉钉小程序服务器端）

钉钉小程序服务器端

参考官网： https://ding-doc.dingtalk.com/doc#/serverapi2/gh60vz

一、钉钉服务api 接口规范

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

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

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

总结： 统一请求为json，返回码中 errcode为0位正常调用。

二、第三方个人应用、第三方企业应用、企业内部应用 区别

1. 第三方个人应用

   频率限制
   用户在使用第三方个人应用时，进行了提交表单操作，且提交该表单后需要向用户发送消息时，有以下限制：
   
   （1）每个第三方个人应用，可以向用户在7天内推送有限条数的消息；
   （2）提交1次表单可发送1条，多次提交发送多条；
   

   如上，根据官方描述，可以总结和理解，个人应用 在发送消息这一块有很大限制。根据官方描述 ：提交1次表单可发送1条，多次提交发送多条；

   小程序个人应用，小程序客户端通过e.detail.formId获取推送消息临时授权码，服务器端必须获取该授权码，才可以发消息，而且是一次性的。而且这个临时授权码应该还有时间限制。

   总结：所以个人应用不太适合那种，那种需要服务器端完全掌控发消息的场景。第三方个人小程序需要提交表单才可以发送消息，企业内部应用，可以使用服务端接口主动发送消息。

   根据官网进入到相应文档，发现 个人小程序文档连服务器API 菜单都没有，目测 个人小程序能调钉钉开放接口非常有限。

   经过测试，你调企业内部接口 https://oapi.dingtalk.com/gettoken 会报 错误的appKey和appSecrect。 就是说你个人应用的 appKey和appSecrect 是调不了一些 企业内部应用接口的。

2. 第三方企业应用
   第三方企业应用开发，是指开发者以钉钉、企业之外的第三方身份，基于钉钉的开放能力开发应用，并提供给钉钉上的其他组织使用。
   

3. 企业内部应用
   官方参考 https://ding-doc.dingtalk.com/doc#/bgb96b/ok9au2

   企业内部应用 发送消息需要先调 https://oapi.dingtalk.com/gettoken接口获取access_token。
   所有的发送消息接口都需要access_token。

总结： 三个应用场景各有不同。

接下来，我们主要以 **企业内部应用** 为主进行分析学习。

必须使用钉钉云的情形

参考官网https://ding-doc.dingtalk.com/doc#/ln6dmh/wbhq0x/ker7fv

• 第三方企业应用（上架到钉钉应用市场）

第三方企业应用，若需在钉钉应用市场上架，必须使用钉钉云。同时还需要购买钉钉云解决方案并将应用部署在钉钉云上。原因主要包含以下：首先企业的数据应该在可控的环境下使用，不能造成企业信息泄漏的严重事故；另外保障应用的稳定性及可用性非常重要，钉钉云会在架构、监控及报警等方面有相应的要求。

• 个人小程序

个人小程序如果需要上架到钉钉应用市场，也需要使用钉钉云，通过钉钉云解决方案进行部署。这是因为钉钉的个人小程序更多的是和工作相关的场景，安全及稳定性的要求会更高一些。

总结： 个人小程序、第三方企业应用 这两者你要上传到应用市场，就都必须使用钉钉云。

三、企业内部应用 服务API

1. 通信录管理

获取部门列表

根部门ID为1

接口
https://oapi.dingtalk.com/department/list
参数

其中 fetch_child参数比较重要，默认是false， 是否递归部门的全部子部门，ISV微应用固定传递false。

比如设置为true，返回如下：

{
	"errcode":0,
	"errmsg":"ok",
	"department":[
		{
			"createDeptGroup":true,
			"name":"金融部",
			"id":285358123,
			"autoAddUser":true,
			"parentid":1
		},
		{
			"createDeptGroup":false,
			"name":"财务部",
			"id":286635451,
			"autoAddUser":false,
			"parentid":1
		}
	]
}

开放平台应用后台，如下 需要开通 通讯录只读权限。

它返回部门列表信息含有，部门id信息。

用户管理

相关接口如下：

• 创建用户
• 更新用户
• 删除用户
• 获取用户详情
• 获取部门用户userid列表
• 获取部门用户
• 获取部门用户详情
• 获取管理员列表
• 获取管理员通讯录权限范围
• 根据unionid获取userid
• 根据手机号获取userid
• 获取企业员工人数
• 未登录钉钉的员工列表

根据部门id获取员工ID列表

接口：
https://oapi.dingtalk.com/user/getDeptMember

返回

{
	"errcode":0,
	"userIds":[
		"manager36299"
	],
	"errmsg":"ok"
}

总结：这个接口直接获取某个部门下 userid列表。

获取部门用户

接口：
https://oapi.dingtalk.com/user/simplelist

返回信息如下：

{
	"errcode":0,
	"userlist":[
		{
			"name":"郭xx",
			"userid":"022222223211111111"
		}
	],
	"hasMore":false,
	"errmsg":"ok"
}

总结： 正如接口命名simple list ，这个接口返回的部门下人员信息比较简单，只有name和userid。

获取部门用户详情

接口：
https://oapi.dingtalk.com/user/listbypage

返回信息如下：

{
    "errcode": 0,
    "errmsg": "ok",
    "hasMore": false,
    "userlist":[
        {
            "userid": "zhangsan",
            "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
            "mobile": "1xxxxxxxxxx",
            "tel" : "xxxx-xxxxxxxx",
            "workPlace" :"",
            "remark" : "",
            "order" : 1,
            "isAdmin": true,
            "isBoss": false,
            "isHide": true,
            "isLeader": true,
            "name": "张三",
            "active": true,
            "department": [1, 2],
            "position": "工程师",
            "email": "[email protected]",
            "avatar":  "xxx",
            "jobnumber": "xxx",
            "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
        }
    ]
}

总结：它这个接口和上一个接口一样，获取部门下人员，不过比上一个接口获取的人员信息详细。

2. 消息通知

钉钉消息通知

• 工作通知消息：是以企业工作通知会话中某个微应用的名义推送到员工的通知消息，例如生日祝福、入职提醒等。
• 群消息：是指可以调用接口以系统名义向群里推送群聊消息。
• 普通消息：是指员工个人在使用应用时，可以通过界面操作的方式往群或其他人的会话里推送消息，例如发送日志的场景。
• 任务类通知：是指需要发送一条任务提醒给员工，比如审批任务等，这类情况下可参考待办任务案例。

工作通知消息

参考官网： https://ding-doc.dingtalk.com/doc#/serverapi2/pgoxpy/DgMTZ

相关接口；

• 发送工作通知消息
• 查询工作通知消息的发送进度
• 查询工作通知消息的发送结果
• 工作通知消息撤回

工作通知消息是以企业工作通知会话中某个微应用的名义推送到员工的通知消息，例如生日祝福、入职提醒等等。下图是工作通知的会话和消息示例：

发送工作通知消息需要注意以下事项：

• 同一个微应用相同消息的内容同一个用户一天只能接收一次。
• 同一个微应用给同一个用户发送消息，企业内部开发方式一天不得超过500次
• 通过设置to_all_user参数全员推送消息，一天最多3次。
• 该接口是异步发送消息，接口返回成功并不表示用户一定会收到消息，需要通过“查询工作通知消息的发送结果”接口查询是否给用户发送成功。
• 消息类型和样例可参考消息类型

总结： 工作通知消息 是以应用的名义发送消息，它也可以发送各种消息类型，取决你传参。

接口：
https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2
传参

{
	"agent_id":"你的微应用id",
	"msg":{
		"msgtype":"text",
		"text":{
			"content":"2020不平凡的一年"
		}
	},
	"to_all_user":"true"
}

群消息

群消息相关接口：

• 发送群消息
• 查询群消息已读人员列表
• 创建会话
• 修改会话
• 获取会话

群会话消息是指可以调用接口创建企业群聊会话，然后可以以系统名义向群里推送群聊消息。

创建会话（即创建群）

发送群消息，需要群会话的id。
群会话的id，可以在调用创建群会话接口的返回结果里面获取，也可以通过dd.chooseChat获取

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/chat/create?access_token=ACCESS_TOKEN

请求包结构体：

{
    "name": "groupName",
    "owner": "zhangsan",
    "useridlist": ["zhangsan","lisi"]
}

参数如下：

总结：默认情况下，我们一般只需设置如下3个参数，组名、群主的userid、群成员userid列表
{
“name”: “groupName”,
“owner”: “zhangsan”,
“useridlist”: [“zhangsan”,“lisi”]
}

注意：该接口也需要开放平台后台，专门开接口权限，否则，报如下返回：

{
	"errcode":60011,
	"errmsg":"没有调用该接口的权限"
}

注意：这个需要打开的权限是
高级权限-微应用开发应用所需要的应用相关权限，根据应用功能合理开通。
下的 企业会话 权限。

开发者后台找到该应用，进入应用详情，有个接口权限，最下方有个企业会话权限检查一下有没有开通。

另外，目前群会话id（chatid）的获取只有前端api。

创建会话创建失败，常见错误还有： 不合法的UserID列表,注意请求参数中useridlist的值必须是一个数组。

{
    
	"name":"gggg",
	"owner":"aaa9876",
	"useridlist":"['aaa9876','081234232936594740']"
}

发送群消息

请求地址：https://oapi.dingtalk.com/chat/send?access_token=ACCESS_TOKEN

群会话的id，可以在调用创建群会话接口的返回结果里面获取，也可以通过dd.chooseChat获取

请求参数示例：

{
    
	"chatid":"chat6aca4f0991afc7f3f635ee902ads31d2f",
	"msg":{
    
		"msgtype":"text",
		"text":{
    
			"content":" 成功测试通过"
		}
	}
}

正确响应结果：

{
    
	"errcode":0,
	"errmsg":"ok",
	"messageId":"msg6XMrDnA/DSAsdfaafsdfQ=="
}