对接钉钉Stream模式考勤打卡相关事件的指南

news2024/11/8 20:24:51

钉钉之前的accessToken是公司级别的，现在的accessToken是基于应用的，接口的权限也是基于应用的。所以第一步是在钉钉开放平台（https://open-dev.dingtalk.com/）创建一个应用。

创建好应用之后，因为我们后续还需要调用钉钉不少服务端api，这些api都要求这个应用被授予了相应的权限，所以我们先给当前这个应用授予足够多的权限（全部都勾上）。

在进行事件订阅之前，需要完成代码接入，才会展示事件列表，所以现在转到事件订阅的文档，先进行代码接入（https://open.dingtalk.com/document/orgapp/develop-stream-mode-push-server）

这块参考官方文档就行了。

接入成功之后，回到上面创建的应用，点击事件订阅菜单

选择Stream模式推送，再点“已完成接入，验证连接通道”

验证成功之后，下面的事件就会展示出来

如果只需要监听考勤相关的事件，经过我的验证，只需要监听下面2个事件就行

员工打卡的触发场景包括：员工上下班打卡，补卡申请通过（坑：如果当天无排班，不会触发这个事件。无排班的场景：1.对于固定上下班，钉钉默认只会初始化未来15天的排班，超过15天都是休息，这点可参考钉钉APP的考勤日历。这样就会导致。2. 节假日，即：节假日的补卡不会触发这个事件（需要再去监听审批完成事件））。以上内容都是开发过程中发现问题之后提工单给钉钉的开发人员得到的回复，不是杜撰的。

因为钉钉Stream事件返回的数据结构与考勤接口返回的数据不一致，如果需要更多的信息，需要对接钉钉考勤相关的接口。

所以我目前对于这块的设计是这样的：

接收到打卡事件之后，拿到userId和打卡时间，拿这2个参数再去查询考勤详情数据（https://open.dingtalk.com/document/orgapp/obtain-the-attendance-update-data），相当于Stream事件只作为我去钉钉拉取数据的一个触发器，请假、加班、出差、外出事件也是一个意思，拿到请假时间范围之后，去查询这段时间的考勤数据

如果发现有些请假类型的数据没有收到推送（或者通过https://open.dingtalk.com/document/orgapp/queries-the-column-value-of-the-attendance-report 查到某个字段的value是null），需要检查以下配置：

把带薪年休假啥的都加进来

消息推送失败的处理方案

钉钉默认的推送失败处理方案：https://open.dingtalk.com/document/orgapp/obtain-the-event-list-of-failed-push-messages

我们只需要写一个SpringTask任务定时拉取就行

要注意的一点是这个接口的数据需要通过getBody读取

public JSONArray getStreamCallBackFailedResult() {
    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/get_call_back_failed_result");
    OapiCallBackGetCallBackFailedResultRequest req = new OapiCallBackGetCallBackFailedResultRequest();
    req.setHttpMethod("GET");
    OapiCallBackGetCallBackFailedResultResponse rsp;
    try {
        rsp = client.execute(req, getAccToken());
        if (Objects.equals(SUCCESS_CODE, rsp.getErrcode())) {
            JSONObject body = JSON.parseObject(rsp.getBody());
            return body.getJSONArray("failed_list");
        }
    } catch (ApiException e) {
        log.warn("[请求钉钉接口失败]获取推送失败的数据", e);
    }
    return null;
}