集成机器人钉钉

一、简介

背景

• 客户需要通过钉钉接收消息通知

名词解释

• 群聊机器人：钉钉群里可以创建一个机器人，平台通过机器人把告警/通知推送到群里
• 私聊机器人：钉钉后台开启机器人配置，平台绑定此机器人后，可以通过私聊的方式将告警/通知推送到个人
• 系统消息：平台可以通过钉钉系统消息将告警/通知推送到个人
• corpId：企业ID
• agentId：应用ID
• appKey：应用Key
• appSecret：应用Secret
• Webhook：钉钉群机器人Webhook
• robotCode：私聊机器人编码（非必填，且不是只能作为私聊，目前我们平台只需要私聊功能）

二、设计思路

思路：

• 方案一：群聊机器人，告警/通知会直接推送到钉钉群；此时还需要配置Webhook，群消息支持@指定人。经讨论此方案会导致群消息增多，且每个人都可以看到告警/通知，不采纳
• 方案二：私聊机器人，告警/通知会以私聊的方式推送给指定人；此时还需要额外配置robotCode，采纳（当使用机器人推送失败时，会继续尝试用系统消息推送）
• 方案三：系统消息，告警/通知会以钉钉系统消息的方式推送给指定人，比较友好，故采纳

钉钉消息推送

1. 当配置了robotCode时：使用单聊机器人推送消息
2. 当未配置robotCode时：使用系统通知推送消息

获取钉钉用户ID

1. 背景：发送钉钉系统消息，需要指定钉钉的用户ID，钉钉提供了根据手机号查询用户ID的API
2. 实现方式：根据告警/通知推送的平台用户信息，获取到手机号；再根据手机号获取钉钉用户ID

钉钉测试

1. 配置 corpId、agentId、appKey、appSecret
2. 填写钉钉账户关联的手机号
3. 钉钉测试文案：测试钉钉消息发送

钉钉token缓存维护

1. 钉钉默认access_token有效期2小时，无需频繁获取token（钉钉存在访问限制），维护token内存级缓存

三、概要设计

3.1.钉钉消息通知配置

• 入参：

{ ??"dingTalk": { ????"corpId":?"", ????"agentId":?"", ????"appKey":?"", ????"appSecret":?"", ????"robotCode":?"非必填" ??}, ??"email": { ????"host":?"192.168.7.224", ????"port": 25, ????"protocol":?"smtp", ????"email":?"mailtest5@test.com", ????"username":?"mailtest5@test.com", ????"password":?"123456", ????"protocolSelect": [{ ??????"name":?"smtp", ??????"port": 25 ????}, { ??????"name":?"pop3", ??????"port": 110 ????}, { ??????"name":?"iamp", ??????"port": 143 ????}] ??}, ??"comWechat": { ????"corpId":?"", ????"agentId":?"", ????"secret":?"" ??}, ??"zabbix": { ????"host":?"", ????"port": 10051, ????"hostName":?"", ????"monitorKey":?"" ??}, ??"copyToList": [{ ????"name": "zhangsan", ????"email": "mailtest@test.com", ????"enableEmail":?true, ????"enableComWechat":?false ??}] }

3.2.钉钉测试

• 接口：POST?/base/sys/config/ding-talk/test
• 入参：

{ ??"dingTalk": { ????"corpId":?"企业ID", ????"agentId":?"应用ID", ????"appKey":?"应用Key", ????"appSecret":?"应用Secret", ????"robotCode":?"非必填" ??}, ??"mobile":?"手机号" }

3.3.是否可以开启钉钉

• 接口：GET /base/message/sysmessageevent/open-dingtalk
• 入参：无

3.4.钉钉token缓存维护

• url：GET?https://oapi.dingtalk.com/gettoken?appkey=xxx&appsecret=xxx
• 维护内存缓存，有效期2小时

3.5.获取钉钉用户ID

• url：GET?https://oapi.dingtalk.com/topapi/v2/user/getbymobile
• 入参：mobile、access_token

• 添加接口调用权限（根据手机号查询用户）：添加接口调用权限 - 钉钉开放平台 (dingtalk.com)

3.6.钉钉消息通知

3.6.1.私聊机器人

• url POST?/v1.0/robot/oToMessages/batchSend
• 入参：

{ ??"title":?"标题", ??"text":?"文本" }

3.6.2.系统通知

• url：POST?https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=xxx
• 入参：

{ ??"agent_id":?"企业ID", ??"userid_list":?"用户id", ??"msg": { ????"msgtype":?"text", ????"text": { ??? ??"content":?"告警消息" ????} ??} }

• 限制：给同一员工一天只能发送一条内容相同的消息通知。为了兼容这一点，钉钉的消息在末尾追加时间 yyyy-MM-dd HH:mm:ss
  • eg：**通知-提交数据授权申请 2023-12-20 17:49:53**
    尊敬的【测试系统】用户您好：张三提交权限申请,[去审批](http://192.168.9.25/#/dta/data/authorization?uuid=4&type=2)

四、实现效果

4.1.私聊机器人

• **通知-提交数据授权申请**
  尊敬的【测试系统】用户您好：万曾辉提交数据授权申请,去审批

4.2.系统通知

• **通知-提交数据授权申请 2023-12-20 17:49:53**
  尊敬的【测试系统】用户您好：安心玮提交数据授权申请,[去审批](http://192.168.9.25/#/data/test?uuid=4&type=2)