《钉钉应用开发者速成手册》之“API实战——同步打卡数据”

2022-05-28 00:25:56

准备工作

在开始本教程前，确保你已经完成了以下准备工作：

你已经完成了钉钉开发者的注册与激活并拥有了子管理员和开发者权限。若尚未完成，请参考成为钉钉开发者。
已经安装了Java开发环境。若未安装，请访问Oracle官网下载。
已下载并安装了IntelliJ IDEA工具。若未安装，请访问IntelliJ IDEA。

创建Java工程并安装钉钉Java SDK

在本部分，你将创建一个Java工程并完成钉钉Java SDK的安装。

打开IntelliJ IDEA工具。
单击选择Projects，然后单击New Project。
参考下图，选择Maven项目和JDK版本，然后单击Next。
输入项目名称，然后单击Finish。
单击这里下载钉钉服务端Java SDK。
解压dingtalk-sdk-java.zip。
在IntelliJ IDEA工具的顶部菜单栏中，选择File > Project Structure。
选择Project Settings > Libraries ，然后依次单击 “+”> Java。
选中下载的SDK，然后依次单击OK > Apply完成导入。

创建应用

在本部分，你将在开发者后台创建一个H5微应用，并完成基础配置。

登录钉钉开发者后台。

说明
只有管理员和子管理员可登录开发者后台。
在开发者后台页面，单击应用开发，然后选择企业内部开发 > 小程序，最后单击创建应用。
在弹出的创建应用页面中填写基本信息，然后单击确定创建。

- 应用类型：选择H5微应用。
- 开发方式：选择企业自助开发。

《钉钉应用开发者速成手册》之“API实战——同步打卡数据”

应用创建完成后，在凭证与基础信息页面，复制应用的AppKey和AppSecret备用。
单击开发管理进入开发管理页面，然后单击修改，并根据以下内容配置开发信息。

- 开发模式：选择开发应用。
- 服务器出口IP：输入调用钉钉服务端API时使用的IP即企业服务器的公网IP，多个IP请以英文逗号","隔开，支持带一个*号通配符的IP格式。可通过工具进行查看。
  本教程设置为127.0.0.1。
- 应用首页地址：输入应用首页URL，在移动端工作台点击应用图标会跳转到此页面。可输入后端服务部署的服务器的IP或域名。例如：http://公网IP:8080。
  本教程设置为https://ding-doc.dingtalk.com/。

《钉钉应用开发者速成手册》之“API实战——同步打卡数据”

单击权限管理进入权限管理页面，然后根据以下配置添加接口调用权限。

1. 权限范围选择全部员工，然后单击添加接口权限。
2. 选择考勤权限，单击确认。

获取调用凭证

在本部分，你将通过创建的应用的AppKey和AppSecret获取调用钉钉服务端API的调用凭证access_token。

如下图所示，在项目的src/test/java/目录下新建一个AccessTokenUtil测试类。
在AccessTokenUtil类中添加以下代码，并运行。
调用gettoken接口获取服务端API授权凭证access_token。

import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.request.OapiGettokenRequest;
import com.dingtalk.api.response.OapiGettokenResponse;
import com.taobao.api.ApiException;
public class AccessTokenUtil {
    public static String AppKey = "替换为你应用的AppKey";
    public static String AppSecret = "替换为你应用的AppSecret";
    public static String getToken() throws RuntimeException {
        try {
            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);
            String accessToken = response.getAccessToken();
            return accessToken;
        } catch (ApiException e) {
            throw new RuntimeException();
        }
    }
    public static void main(String[] args)throws ApiException{
        String accessToken = AccessTokenUtil.getToken();
        System.out.println(accessToken);
    }
}

调用成功的返回结果类似如下。

efcfb3d7f6aa3abxxx

获取考勤打卡记录

在本部分，你将通过服务端API的调用凭证access_token从钉钉后台获取考勤打卡记录。

如下图所示，在项目的src/test/java/目录下新建一个AttendanceDemo测试类。
在AttendanceDemo类中添加以下代码，并运行。
调用/attendance/list接口，获取企业内员工的实际打卡结果。

import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiAttendanceListRequest;
import com.dingtalk.api.response.OapiAttendanceListResponse;
import com.taobao.api.ApiException;
import java.util.Arrays;
public class AttendanceDemo {
    /**
     * 获取考勤打卡记录
     *
     * @param args
     */
    public static void main(String args[]) {
        // 获取服务端接口调用凭证access_token
        String access_token = AccessTokenUtil.getToken();
        try {
            // 通过调用接口获取考勤打卡结果
            DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/attendance/list");
            OapiAttendanceListRequest request = new OapiAttendanceListRequest();
            // 查询考勤打卡记录的起始工作日
            request.setWorkDateFrom("2021-01-12 00:00:00");
            // 查询考勤打卡记录的结束工作日
            request.setWorkDateTo("2021-01-19 00:00:00");
            // 员工在企业内的userid列表，最多不能超过50个。
            request.setUserIdList(Arrays.asList("user123"));
            // 表示获取考勤数据的起始点
            request.setOffset(0L);
            // 表示获取考勤数据的条数，最大不能超过50条。
            request.setLimit(1L);
            OapiAttendanceListResponse response = client.execute(request, access_token);
            System.out.println(response.getBody());
        } catch (ApiException e) {
            e.printStackTrace();
        }
    }
}

调用成功的返回结果类似如下。

{
    "errcode": 0,
    "recordresult": [
        {
            "checkType": "OnDuty",
            "corpId": "dinge8a56572f80xxxx",
            "locationResult": "Normal",
            "baseCheckTime": 1610380800000,
            "groupId": -1,
            "timeResult": "Normal",
            "userId": "user123",
            "recordId": 54735159894,
            "workDate": 1610380800000,
            "sourceType": "ATM",
            "userCheckTime": 1610380800000,
            "planId": 180485053237,
            "id": 129082
        }
    ],
    "_record": "77964B20FC00",
    "hasMore": false,
    "errmsg": "ok"
}

此时，你就可以将打卡结果同步到自有的OA系统中了。

恭喜

你已完成本教程的全部内容！

现在你已经拥有一个可以正常运行的钉钉应用。你也可以在其中添加其他功能，参考应用开发了解更多。

码农公寓

准备工作

创建Java工程并安装钉钉Java SDK

创建应用

获取调用凭证

获取考勤打卡记录

恭喜

相关文章