钉钉开发之业务事件回调

水深无声 2023-06-16 10:40 5阅读 0赞

# 钉钉开发 #

## 一、钉钉开发之业务事件回调 ##

简单的来说：业务事件回调就是 通过向钉钉服务器注册监听 一些指定的事件，当用户在钉钉上操作我们已经监听的事件，那么钉钉服务器就会想 我们的服务器 发送通知，我们可以得到监听事件的详细信息。  
比如：我最近开发遇到的需求，需要获取用户审批实例里面的表单数据，这里我就用了钉钉的业务事件回调，我想钉钉服务器注册我需要监听的事件（这里我监听了，审批实例回调和审批任务回调）。当我向钉钉服务器注册回调接口后，一旦有用户在 钉钉上发起流程，钉钉服务器就会推动给我，而我这边也可以获取用户发起流程的详情。

1.注册业务事件回调接口

![format_png][]

①、微应用服务器调用 注册事件回调接口（post请求）

https://oapi.dingtalk.com/call_back/register_call_back?access_token=ACCESS_TOKEN

请求参数示例：

{ 
        "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org"],
        "token": "123456",
        "aes_key": "xxxxxxxxlvdhntotr3x9qhlbytb18zyz5zxxxxxxxxx",
        "url":"http://test001.vaiwan.com/eventreceive"
    }

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>参数类型</th> 
   <th>必须</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>access_token</td> 
   <td>String</td> 
   <td>是</td> 
   <td>调用接口凭证</td> 
  </tr> 
  <tr> 
   <td>call_back_tag</td> 
   <td>Array[String]</td> 
   <td>是</td> 
   <td>需要监听的事件类型</td> 
  </tr> 
  <tr> 
   <td>token</td> 
   <td>String</td> 
   <td>是</td> 
   <td>加解密需要用到的token，ISV(服务提供商)推荐使用注册套件时填写的token，普通企业可以随机填写</td> 
  </tr> 
  <tr> 
   <td>aes_key</td> 
   <td>String</td> 
   <td>是</td> 
   <td>数据加密密钥。用于回调数据的加密，长度固定为43个字符，从a-z, A-Z, 0-9共62个字符中选取,您可以随机生成，ISV(服务提供商)推荐使用注册套件时填写的EncodingAESKey</td> 
  </tr> 
  <tr> 
   <td>url</td> 
   <td>String</td> 
   <td>是</td> 
   <td>接收事件回调的url，必须是公网可以访问的url地址</td> 
  </tr> 
 </tbody> 
</table>

返回结果：

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

**更多 查询事件回调接口、更新事件回调接口、删除事件回调接口、获取回调失败的结果等接口**参考 https://ding-doc.dingtalk.com/doc\#/serverapi2/pwz3r5

②.钉钉服务器会向第①步中请求参数 url 的地址推送消息

③.第 ② 和 第③ 都在下面的方法中执行了

例如：下面callback方法为回调地址,钉钉服务器会返回 signature timestamp nonce 加密后的 json 数据

package com.controller;
    
    import com.alibaba.fastjson.JSON;
    import com.alibaba.fastjson.JSONObject;
    
    import com.config.Constant;
    import com.config.URLConstant;
    import com.dingtalk.api.DefaultDingTalkClient;
    import com.dingtalk.api.DingTalkClient;
    import com.dingtalk.api.request.OapiCallBackDeleteCallBackRequest;
    import com.dingtalk.api.request.OapiCallBackGetCallBackRequest;
    import com.dingtalk.api.request.OapiCallBackRegisterCallBackRequest;
    import com.dingtalk.api.response.OapiCallBackDeleteCallBackResponse;
    import com.dingtalk.api.response.OapiCallBackRegisterCallBackResponse;
    import com.dingtalk.oapi.lib.aes.DingTalkEncryptor;
    import com.dingtalk.oapi.lib.aes.Utils;
    import com.util.AccessTokenUtil;
    import com.util.MessageUtil;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.ResponseBody;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.Arrays;
    import java.util.Map;
    
    /** * E应用回调信息处理 */
    @RestController
    public class CallbackController { 
    
        private static final Logger bizLogger = LoggerFactory.getLogger("BIZ_CALLBACKCONTROLLER");
        private static final Logger mainLogger = LoggerFactory.getLogger(CallbackController.class);
    
        /** * 创建套件后，验证回调URL创建有效事件（第一次保存回调URL之前） */
        private static final String CHECK_URL = "check_url";
    
        /** * 审批任务回调，更多回调类型 参考 https://ding-doc.dingtalk.com/doc#/serverapi2/skn8ld */
        private static final String BPMS_TASK_CHANGE = "bpms_task_change";
    
        /** * 审批实例回调 */
        private static final String BPMS_INSTANCE_CHANGE = "bpms_instance_change";
    
        /** * 相应钉钉回调时的值 */
        private static final String CALLBACK_RESPONSE_SUCCESS = "success";
        
        /** * 审批模板唯一标识，可以在审批管理后台的 URL 中找到 */
        public static final String PROCESS_CODE = "***";
    
    
        @RequestMapping(value = "/callback", method = RequestMethod.POST)
        @ResponseBody
        public Map<String, String> callback(@RequestParam(value = "signature", required = false) String signature,
                                            @RequestParam(value = "timestamp", required = false) String timestamp,
                                            @RequestParam(value = "nonce", required = false) String nonce,
                                            @RequestBody(required = false) JSONObject json) { 
            String params = " signature:"+signature + " timestamp:"+timestamp +" nonce:"+nonce+" json:"+json;
            try { 
                DingTalkEncryptor dingTalkEncryptor = new DingTalkEncryptor(Constant.TOKEN, Constant.ENCODING_AES_KEY,
                    Constant.CORP_ID);
    
                //从post请求的body中获取回调信息的加密数据进行解密处理
                String encryptMsg = json.getString("encrypt");
                String plainText = dingTalkEncryptor.getDecryptMsg(signature, timestamp, nonce, encryptMsg);
                JSONObject obj = JSON.parseObject(plainText);
    
                //根据回调数据类型做不同的业务处理
                String eventType = obj.getString("EventType");
                if (BPMS_TASK_CHANGE.equals(eventType)) { 
                    bizLogger.info("收到审批任务进度更新: " + plainText);
                    // 可以根据 PROCESS_CODE 来判断这是属于哪个模板发起的流程
                    // 参考 https://ding-doc.dingtalk.com/doc#/serverapi2/skn8ld 得到返回的数据做业务
                    //todo: 实现审批的业务逻辑，如发消息
                } else if (BPMS_INSTANCE_CHANGE.equals(eventType)) { 
                    bizLogger.info("收到审批实例状态更新: " + plainText);
                    //todo: 实现审批的业务逻辑，如发消息
                    String processInstanceId = obj.getString("processInstanceId");
                    if (obj.containsKey("result") && obj.getString("result").equals("agree")) { 
                        MessageUtil.sendMessageToOriginator(processInstanceId);
                    }
                } else { 
                    // 其他类型事件处理
                }
    
                // 返回success的加密信息表示回调处理成功【这是第 三 步，返回加密后的 “success” 给钉钉服务器，让钉钉服务器知道此次回调成功了。否则钉钉会持续推动消息的回调接口。】
                return dingTalkEncryptor.getEncryptedMap(CALLBACK_RESPONSE_SUCCESS, System.currentTimeMillis(), Utils.getRandomStr(8));
            } catch (Exception e) { 
                //失败的情况，应用的开发者应该通过告警感知，并干预修复
                mainLogger.error("process callback failed！"+params,e);
                return null;
            }
    
        }
    
        public static void main(String[] args) throws Exception{ 
            // 先删除企业已有的回调
            DingTalkClient client = new DefaultDingTalkClient(URLConstant.DELETE_CALLBACK);
            OapiCallBackDeleteCallBackRequest request = new OapiCallBackDeleteCallBackRequest();
            request.setHttpMethod("GET");
            client.execute(request, AccessTokenUtil.getToken());
    
            // 重新为企业注册回调
            client = new DefaultDingTalkClient(URLConstant.REGISTER_CALLBACK);
            OapiCallBackRegisterCallBackRequest registerRequest = new OapiCallBackRegisterCallBackRequest();
            registerRequest.setUrl(Constant.CALLBACK_URL_HOST + "/callback");
            registerRequest.setAesKey(Constant.ENCODING_AES_KEY);
            registerRequest.setToken(Constant.TOKEN);
            registerRequest.setCallBackTag(Arrays.asList("bpms_instance_change", "bpms_task_change"));
            OapiCallBackRegisterCallBackResponse registerResponse = client.execute(registerRequest,AccessTokenUtil.getToken());
            if (registerResponse.isSuccess()) { 
                System.out.println("回调注册成功了！！！");
            }
        }
    }

[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9zcHJpbmdpbWFnZS5vc3MtY24tY2hlbmdkdS5hbGl5dW5jcy5jb20vMjAxOTExMjYwMDEwMzIucG5n?x-oss-process=image/format,png