为您推荐:
精华内容
最热下载
问答
  • 5星
    126.2MB qc_id_01 2021-01-26 18:19:05
  • 结合企业实际需求,对接钉钉考勤,得到考勤统计报表,对接人事管理系统,自动得到薪资报表。 启用智能统计报表流程 接口调用 是否启用智能统计报表 获取报表列定义 获取报表列值 获取报表假期数据 考勤智能...

    结合企业实际需求,对接钉钉考勤,得到考勤统计报表,对接人事管理系统,自动得到薪资报表。

     

    • 启用智能统计报表流程
    • 接口调用
    • 是否启用智能统计报表
    • 获取报表列定义
    • 获取报表列值
    • 获取报表假期数据

    考勤智能统计报表,是考勤为了满足企业个性化的统计需求,提供的一套智能可编程的报表系统。企业可以通过简单勾选或者高级编程模式来定制企业的统计规则,非常便捷地提供便于计算薪酬结果的统计数据。本文介绍如何使用统计报表API,获取企业的统计报表数据。

    启用智能统计报表流程

    开发者登录钉钉管理后台,点击工作台-考勤打卡-进入,打开考勤打卡后台。

    image.png

    image.png

    点击月度汇总,查看是否开启智能统计报表:

    如果右上角是“切换新版”,那么是未启用智能报表状态。需要点击切换新版,即可启用智能统计报表。

    image.png

    如果右上角是“返回旧版”,那么无需进行其他操作,当前已启用新版智能统计报表。

    image.png

     

    接口调用

    是否启用智能统计报表

    判断企业是否开启了考勤智能报表,如果企业未启用智能报表,无法调用统计报表其他的接口。

     

    请求方式:POST(HTTPS)

    请求地址https://oapi.dingtalk.com/topapi/attendance/isopensmartreport?access_token=ACCESS_TOKEN

    参数说明:无需入参

     

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/isopensmartreport");
    OapiAttendanceIsopensmartreportRequest req = new OapiAttendanceIsopensmartreportRequest();
    OapiAttendanceIsopensmartreportResponse rsp = client.execute(req, access_token);
    System.out.println(rsp.getBody());

     

    返回结果

    {
        "result": {
            "smart_report": true
        },
        "errmsg": "ok",
        "errcode": 0
    }

     

    参数

    类型

    示例值

    说明

    errcode

    Number

    0

    返回码。0表示成功,其他表示失败

    errmsg

    String

    ok

    对返回码的文本描述内容

    result

     

     

     

    └smart_report

    boolen

    true

    true:开启,false:未开启

     

    获取报表列定义

    获取企业智能考勤报表中的列信息,通过获取列信息中的id值,可以根据列的id查询考勤智能报表中该列的统计数据,企业可以自主选择需要哪些列值来参与薪酬的计算。

    注意:如果是获取假期相关字段信息,不返回id。如果希望获取假期相关信息,请调用本文-“获取报表假期数据”接口。

     

    请求方式:POST(HTTPS)

    请求地址https://oapi.dingtalk.com/topapi/attendance/getattcolumns?access_token=ACCESS_TOKEN

    参数说明:无需入参


    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getattcolumns");
    OapiAttendanceGetattcolumnsRequest req = new OapiAttendanceGetattcolumnsRequest();
    OapiAttendanceGetattcolumnsResponse rsp = client.execute(req, access_token);
    System.out.println(rsp.getBody());

     

    返回结果

    {
        "errmsg": "ok",
        "errcode": 0,
        "result": {
            "columns": [{
                "id": 123,
                "name": "工时"
            }]
        }
    }

     

    参数

    类型

    示例值

    说明

    errcode

    Number

    0

    返回码。0表示成功,其他表示失败

    errmsg

    String

    ok

    对返回码的文本描述内容

    result

     

     

     

    └columns

     

     

     

    └└id

    Number

    123

    列id

    └└name

    String

    工时

    列名称

     

    获取报表列值

    获取钉钉智能考勤报表的列值数据,其中包含了一定时间段内报表某些列的所有数据,以及相关的列信息,企业可以基于该接口的返回值计算员工薪酬。

     

    注意:不支持获取离职人员的考勤信息,离职人员的考勤数据可以在OA管理后台查询。

    请求方式:POST(HTTPS)

    请求地址https://oapi.dingtalk.com/topapi/attendance/getcolumnval?access_token=ACCESS_TOKEN

    参数说明:

    参数

    类型

    必须

    示例值

    说明

    userid

    String

    zhangsan

    员工id

    column_id_list

    String

    1,2,3

    报表列id列表,多个用英文逗号分隔,最大长度20

    from_date

    Date

     

    2018-07-11 12:12:12

    开始时间

    to_date

    Date

    2018-07-12 12:12:12

     

    结束时间,结束时间减去开始时间必须在31天以内

     

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getcolumnval");
    OapiAttendanceGetcolumnvalRequest req = new OapiAttendanceGetcolumnvalRequest();
    req.setUserid("zhangsan");
    req.setColumnIdList("1,2,3");
    req.setFromDate(StringUtils.parseDateTime("2018-07-11 12:12:12"));
    req.setToDate(StringUtils.parseDateTime("2018-07-12 12:12:12"));
    OapiAttendanceGetcolumnvalResponse rsp = client.execute(req, access_token);
    System.out.println(rsp.getBody());

     

    返回结果

    {
        "errmsg": "ok",
        "errcode": 0,
        "result": {
            "column_vals": [{
                "column_vals": [{
                    "date": "2019-07-11",
                    "value": "1.0"
                }],
                "column_vo": {
                    "id": 123
                },
                "fixed_value": "0"
            }]
        }
    }

     

    参数

    类型

    示例值

    说明

    errcode

    Number

    0

    返回码。0表示成功,其他表示失败

    errmsg

    String

    ok

    对返回码的文本描述内容

    result

     

     

     

    └column_vals

     

     

     

    └└column_vals

     

     

     

    └└└date

    String

    2019-08-15

    日期

    └└└value

    String

    1.0

    每天的值

    └└column_vo

     

     

     

    └└└id

    Number

    123

    报表列id

    └└fixed_value

    String

    2.0

    固定值,某些报表列是固定列值的,那么仅会在这个字段返回,不会在column_vals中返回

     

    获取报表假期数据

    根据假期名称和用户id获取钉钉智能考勤报表的假期数据,其中包含了一定时间段内报表假期列的所有数据,由于假期列是一个动态列,因此需要根据假期名称获取数据。

     

    请求方式:POST(HTTPS)

    请求地址https://oapi.dingtalk.com/topapi/attendance/getleavetimebynames?access_token=ACCESS_TOKEN

    参数说明:

    参数

    类型

    必须

    示例值

    说明

    userid

    String

    zhangsan

    员工id

    leave_names

    String

    年假

    假期名称,多个用英文逗号分隔,最大长度20

    from_date

    Date

     

    2018-07-11 12:12:12

    开始时间

    to_date

    Date

    2018-07-12 12:12:12

    结束时间,结束时间减去开始时间必须在31天以内

     

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getleavetimebynames");
    OapiAttendanceGetleavetimebynamesRequest req = new OapiAttendanceGetleavetimebynamesRequest();
    req.setUserid("zhangsan");
    req.setLeaveNames("年假");
    req.setFromDate(StringUtils.parseDateTime("2018-07-11 12:12:12"));
    req.setToDate(StringUtils.parseDateTime("2018-07-12 12:12:12"));
    OapiAttendanceGetleavetimebynamesResponse rsp = client.execute(req, access_token);
    System.out.println(rsp.getBody());

     

    返回结果

    {
        "result": {
            "columns": [{
                "columnvo": {
                    "name": "年假",
                    "id": 1
                },
                "columnvals": [{
                    "value": "1.0",
                    "date": "2018-08-09"
                }]
            }]
        },
        "errcode": 0,
        "errmsg": "ok"
    }

     

    参数

    类型

    示例值

    说明

    errcode

    Number

    0

    返回码。0表示成功,其他表示失败

    errmsg

    String

    ok

    对返回码的文本描述内容

    result

     

     

     

    └columns

     

     

     

    └└columnvals

     

     

     

    └└└date

    String

    2018-08-09

    日期

    └└└value

    String

    1.0

    每天的值

    └└columnvo

     

     

     

    └└└id

    Number

    123

    报表列id

    └└└name

    String

    年假

    假期类型

    展开全文
    dingdingoa 2020-09-25 11:23:45
  • 目前暂不支持一性获取企业下所有员工userid值,如果开发者希望获取企业下所有员工userid值,可以通过以下方法: (1)步骤一,调用“获取部门列表”接口,参数id值传1,可以获取该企业下所有部门id,参考接口调用...

    建用户

     

    调试工具在线调试

    请求方式:POST(HTTPS)

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

    请求包结构体

    {
        "userid": "zhangsan",
        "name": "张三",
        "orderInDepts" : "{1:10, 2:20}",
        "department": [1,2],
        "position": "产品经理",
        "mobile": "1xxxxxxxxxx",
        "tel" : "xxxx-xxxxxxxx",
        "workPlace" :"",
        "remark" : "",
        "email": "test@xxx.com",
        "orgEmail": "test@xxx.com",
        "jobnumber": "xxx",
        "isHide": false,
        "isSenior": false,
        "extattr": {
                    "爱好":"旅游",
                    "年龄":"24"
                    }
    }

     

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    userid

    String

    员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改,企业内必须唯一。

    长度为1~64个字符,如果不传,服务器将自动生成一个userid。

    name

    String

    成员名称。

    长度为1~64个字符

    orderInDepts

    JSONObject

    在对应的部门中的排序,

    Map结构的json字符串,key是部门的id, value是人员在这个部门的排序值

    department

    List

    数组类型,数组里面值为整型,成员所属部门id列表

    position

    String

    职位信息。

    长度为0~64个字符

    positionInDepts

    JSONObject

    设置用户在每个部门下的职位。

    Map结构的json字符串,

    Map的Key是deptId,表示部门id,

    Map的Value是职位,表示在这个部门下的职位

    mobile

    String

    手机号码,企业内必须唯一,不可重复。如果是国际号码,请使用+xx-xxxxxx的格式

    tel

    String

    分机号,长度为0~50个字符,企业内必须唯一,不可重复

    workPlace

    String

    办公地点,长度为0~50个字符

    remark

    String

    备注,长度为0~1000个字符

    email

    String

    邮箱。长度为0~64个字符。企业内必须唯一,不可重复

    orgEmail

    String

    员工的企业邮箱,员工的企业邮箱已开通,才能增加此字段, 否则会报错

    jobnumber

    String

    员工工号。对应显示到OA后台和客户端个人资料的工号栏目。

    长度为0~64个字符

    isHide

    Boolean

    是否号码隐藏。true表示隐藏,false表示不隐藏。

    隐藏手机号后,手机号在个人资料页隐藏,但仍可对其发DING、发起钉钉免费商务电话。

    isSenior

    Boolean

    是否高管模式。true表示是,false表示不是。

    开启后,手机号码对所有员工隐藏。普通员工无法对其发DING、发起钉钉免费商务电话。高管之间不受影响。

    extattr

    JSONObject

    扩展属性,可以设置多种属性(手机上最多显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)。

    该字段的值支持链接类型填写,同时链接支持变量通配符自动替换,目前支持通配符有:userid,corpid。示例: [工位地址](http://www.dingtalk.com?userid=#userid#&corpid=#corpid#) 

    hiredDate

    Number

    入职时间,Unix时间戳,单位ms

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/create");
    OapiUserCreateRequest request = new OapiUserCreateRequest();
    request.setUserid("zhangsan");
    request.setMobile("1xxxxxxxxxx");
    request.setName("张三");
    
    // 需要用字符串, "[100,200]" 这种格式
    List<Long> departments = new ArrayList<Long>();
    departments.add(100L);
    departments.add(200L);
    request.setDepartment(JSON.toJSONString(departments));
    
    OapiUserCreateResponse response = client.execute(request, accessToken);

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    userid

    员工唯一标识

    更新用户

     

    调试工具在线调试

    请求方式:POST(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/update?access_token=ACCESS_TOKEN

    请求包结构体

    {
        "userid": "zhangsan",
        "name": "张三",
        "department": [1, 2],
        "orderInDepts": "{1:10}",
        "position": "产品经理",
        "tel" : "xxxx-xxxxxxxx",
        "workPlace" :"",
        "remark" : "",
        "email": "test@xxx.com",
        "orgEmail": "test@xxx.com",
        "jobnumber": "xxx",
        "isHide": false,
        "isSenior": false,
        "extattr": {
                    "爱好":"旅游",
                    "年龄":"24"
                    }
    }

     

    参数说明(如果非必须的字段未指定,则钉钉后台不改变该字段之前设置好的值)

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    lang

    String

    通讯录语言

    (默认zh_CN另外支持en_US)

    userid

    String

    员工id,不可修改,长度为1~64个字符

    name

    String

    成员名称,长度为1~64个字符

    department

    List

    成员所属部门id列表

    orderInDepts

    JSONObject

    实际是Map的序列化字符串,

    Map的Key是deptId,表示部门id,

    Map的Value是order,表示排序的值,

    列表是按order的倒序排列输出的,即从大到小排列输出的

    position

    String

    职位信息。长度为0~64个字符

    positionInDepts

    JSONObject

    设置用户在每个部门下的职位。

    Map结构的json字符串,

    Map的Key是deptId,表示部门id,

    Map的Value是职位,表示在这个部门下的职位

    tel

    String

    分机号,长度为0~50个字符

    workPlace

    String

    办公地点,长度为0~50个字符

    remark

    String

    备注,长度为0~1000个字符

    email

    String

    邮箱,长度为0~64个字符,企业内必须唯一

    orgEmail

    String

    员工的企业邮箱,需要确认员工已经开通企业邮箱,否则会报错

    jobnumber

    String

    员工工号,对应显示到OA后台和客户端个人资料的工号栏目,长度为0~64个字符

    isHide

    Boolean

    是否号码隐藏,true表示隐藏,false表示不隐藏。

    隐藏手机号后,手机号在个人资料页隐藏,但仍可对其发DING、发起钉钉免费商务电话

    isSenior

    Boolean

    是否高管模式,

    true表示是,

    false表示不是。

    开启后,手机号码对所有员工隐藏。普通员工无法对其发DING、发起钉钉免费商务电话。高管之间不受影响

    extattr

    JSONObject

    扩展属性,可以设置多种属性(手机上最多显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)。

    该字段的值支持链接类型填写,同时链接支持变量通配符自动替换,目前支持通配符有:userid,corpid。示例: [工位地址](http://www.dingtalk.com?userid=#userid#&corpid=#corpid#) ;

    查看扩展属性:

    (1)链接类型扩展属性,只支持在“移动端钉钉-点击该用户头像-个人资料页”查看,点击链接可以跳转;

    (2)非链接类型扩展属性,支持在“移动端钉钉/PC端钉钉-点击该用户头像-个人资料页”查看;

    hiredDate

    Number

    入职时间,Unix时间戳

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/update");
    OapiUserUpdateRequest request = new OapiUserUpdateRequest();
    request.setUserid("zhangsan");
    request.setName("张三");
    
    OapiUserUpdateResponse response = client.execute(request, accessToken);

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    删除用户

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/delete?access_token=ACCESS_TOKEN&userid=zhangsan

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    userid

    String

    员工id

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/delete");
    OapiUserDeleteRequest request = new OapiUserDeleteRequest();
    request.setUserid("zhangsan");
    request.setHttpMethod("GET");
    
    OapiUserDeleteResponse response = client.execute(request, accessToken);

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

     

     

    获取用户详情

    如果您想调用通讯录接口并同时获取员工手机号,请先参考通讯录权限说明,设置下通讯录接口权限和手机号等敏感字段权限

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=zhangsan

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    userid

    String

    员工id

    lang

    String

    通讯录语言(默认zh_CN,未来会支持en_US)

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get");
    OapiUserGetRequest request = new OapiUserGetRequest();
    request.setUserid("zhangsan");
    request.setHttpMethod("GET");
    OapiUserGetResponse response = client.execute(request, accessToken);

     

    返回结果

    {
        "errcode": 0,
        "unionid": "PiiiPyQqBNBii0HnCJ3zljcxxxxxx",
        "remark": "remark",
        "userid": "zhangsan",
        "isLeaderInDepts": "{1:false}",
        "isBoss": false,
        "hiredDate": 1520265600000,
        "isSenior": false,
        "tel": "xxx-xxxxxxxx",
        "department": [1,2],
        "workPlace": "place",
        "email": "test@xxx.com",
        "orderInDepts": "{1:71738366882504}",
        "mobile": "1xxxxxxxxxx",
        "errmsg": "ok",
        "active": false,
        "avatar": "xxx",
        "isAdmin": false,
        "isHide": false,
        "jobnumber": "001",
        "name": "张三",
        "extattr": {},
        "stateCode": "86",
        "position": "manager",
        "roles": [
            {
                "id": 149507744,
                "name": "总监",
                "groupName": "职务"
            }
        ]
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    userid

    员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改

    unionid

    员工在当前开发者企业账号范围内的唯一标识,系统生成,固定值,不会改变

    name

    员工名字

    tel

    分机号(仅限企业内部开发调用)

    workPlace

    办公地点

    remark

    备注

    mobile

    手机号码

    email

    员工的电子邮箱

    orgEmail

    员工的企业邮箱,如果员工已经开通了企业邮箱,接口会返回,否则不会返回

    active

    是否已经激活,true表示已激活,false表示未激活

    orderInDepts

    在对应的部门中的排序,Map结构的json字符串,key是部门的id,value是人员在这个部门的排序值

    isAdmin

    是否为企业的管理员,true表示是,false表示不是

    isBoss

    是否为企业的老板,true表示是,false表示不是

    isLeaderInDepts

    在对应的部门中是否为主管:Map结构的json字符串,key是部门的id,value是人员在这个部门中是否为主管,true表示是,false表示不是

    isHide

    是否号码隐藏,true表示隐藏,false表示不隐藏

    department

    成员所属部门id列表

    position

    职位信息

    avatar

    头像url

    hiredDate

    入职时间。Unix时间戳 (在OA后台通讯录中的员工基础信息中维护过入职时间才会返回)

    jobnumber

    员工工号

    extattr

    扩展属性,可以设置多种属性(手机上最多显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)。

    该字段的值支持链接类型填写,同时链接支持变量通配符自动替换,目前支持通配符有:userid,corpid。示例: [工位地址](http://www.dingtalk.com?userid=#userid#&corpid=#corpid#) 

    isSenior

    是否是高管

    stateCode

    国家地区码

    roles

    用户所在角色列表

    └ id

    角色id

    └ name

    角色名称

    └ groupName

    角色组名称

    realAuthed

    是否实名认证

     

    获取部门用户userid列表

    通过该接口,可以获取当前部门下的userid列表。目前暂不支持一次性获取企业下所有员工userid值,如果开发者希望获取企业下所有员工userid值,可以通过以下方法:

    (1)步骤一,调用“获取部门列表”接口,参数id值传1,可以获取该企业下所有部门id,参考接口调用文档

    (2)步骤二,调用此接口“获取部门用户userid列表”,分别获取每个部门下的员工userid。

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/getDeptMember?access_token=ACCESS_TOKEN&deptId=1

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    deptId

    String

    部门id

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getDeptMember");
    OapiUserGetDeptMemberRequest req = new OapiUserGetDeptMemberRequest();
    req.setDeptId("a");
    req.setHttpMethod("GET");
    OapiUserGetDeptMemberResponse rsp = client.execute(req, accessToken);
    System.out.println(rsp.getBody());

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    userIds

    userid列表

     

    获取部门用户

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/simplelist?access_token=ACCESS_TOKEN&department_id=1

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    lang

    String

    通讯录语言(默认zh_CN另外支持en_US)

    department_id

    long

    获取的部门id

    offset

    long

    支持分页查询,与size参数同时设置时才生效,此参数代表偏移量

    size

    long

    支持分页查询,与offset参数同时设置时才生效,此参数代表分页大小,最大100

    order

    String

    支持分页查询,部门成员的排序规则,默认不传是按自定义排序;

    entry_asc:代表按照进入部门的时间升序,

    entry_desc:代表按照进入部门的时间降序,

    modify_asc:代表按照部门信息修改时间升序,

    modify_desc:代表按照部门信息修改时间降序,

    custom:代表用户定义(未定义时按照拼音)排序

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/simplelist");
    OapiUserSimplelistRequest request = new OapiUserSimplelistRequest();
    request.setDepartmentId(100L);
    request.setOffset(0L);
    request.setSize(10L);
    request.setHttpMethod("GET");
    
    OapiUserSimplelistResponse response = client.execute(request, accessToken);

     

    返回结果

    {
        "errcode": 0,
        "errmsg": "ok",
        "hasMore": false,
        "userlist": [
            {
                "userid": "zhangsan",
                "name": "张三"
            }
        ]
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    hasMore

    在分页查询时返回,代表是否还有下一页更多数据

    userlist

    成员列表

    userid

    员工id

    name

    成员名称

     

    获取部门用户详情

    如果您想调用通讯录接口并同时获取员工手机号,请先参考通讯录权限说明,设置下通讯录接口权限和手机号等敏感字段权限

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/listbypage?access_token=ACCESS_TOKEN&department_id=1

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    lang

    String

    通讯录语言(默认zh_CN另外支持en_US)

    department_id

    long

    获取的部门id,1表示根部门

    offset

    long

    支持分页查询,与size参数同时设置时才生效,此参数代表偏移量,偏移量从0开始

    size

    long

    支持分页查询,与offset参数同时设置时才生效,此参数代表分页大小,最大100

    order

    String

    支持分页查询,部门成员的排序规则,默认 是按自定义排序;

    entry_asc:代表按照进入部门的时间升序,

    entry_desc:代表按照进入部门的时间降序,

    modify_asc:代表按照部门信息修改时间升序,

    modify_desc:代表按照部门信息修改时间降序,

    custom:代表用户定义(未定义时按照拼音)排序

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/listbypage");
    OapiUserListbypageRequest request = new OapiUserListbypageRequest();
    request.setDepartmentId(1L);
    request.setOffset(0L);
    request.setSize(10L);
    request.setOrder("entry_desc");
    request.setHttpMethod("GET");
    OapiUserListbypageResponse execute = client.execute(request,accessToken);

     

    返回结果

    {
        "errcode": 0,
        "errmsg": "ok",
        "hasMore": false,
        "userlist":[
            {
                "userid": "zhangsan",
                "unionid": "PiiiPyQqBNBii0HnCJ3zljcxxxxxx",
                "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": "test@xxx.com",
                "avatar":  "xxx",
                "jobnumber": "xxx",
                "extattr": {
                    "爱好":"旅游",
                    "年龄":"24"
                    }
            }
        ]
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    hasMore

    在分页查询时返回,代表是否还有下一页更多数据

    userlist

    成员列表

    userid

    员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改

    unionid

    员工在当前开发者企业账号范围内的唯一标识,系统生成,固定值,不会改变

    order

    表示人员在此部门中的排序,列表是按order的倒序排列输出的,即从大到小排列输出的

    钉钉管理后台里面调整了顺序的话order才有值

    mobile

    手机号

    tel

    分机号

    workPlace

    办公地点

    remark

    备注

    isAdmin

    是否是企业的管理员,true表示是,false表示不是

    isBoss

    是否为企业的老板,true表示是,false表示不是

    isHide

    是否隐藏号码,true表示是,false表示不是

    isLeader

    是否是部门的主管,true表示是,false表示不是

    name

    成员名称

    active

    表示该用户是否激活了钉钉

    department

    成员所属部门id列表

    position

    职位信息

    email

    员工的邮箱

    orgEmail

    员工的企业邮箱,如果员工的企业邮箱没有开通,返回信息中不包含

    avatar

    头像url

    jobnumber

    员工工号

    hiredDate

    入职时间

    extattr

    扩展属性,可以设置多种属性(手机上最多显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)。

    该字段的值支持链接类型填写,同时链接支持变量通配符自动替换,目前支持通配符有:userid,corpid。示例: [工位地址](http://www.dingtalk.com?userid=#userid#&corpid=#corpid#) 

    stateCode

    国家地区码

     

     

    管理员相关

    获取管理员列表

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/get_admin?access_token=ACCESS_TOKEN

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_admin");
    OapiUserGetAdminRequest request = new OapiUserGetAdminRequest();
    request.setHttpMethod("GET");
    
    OapiUserGetAdminResponse response = client.execute(request, accessToken);

     

    返回结果

    {
        "errcode": 0,
        "errmsg": "ok",
        "admin_list":[
            {"sys_level":2,"userid":"userid2"},
            {"sys_level":1,"userid":"userid1"}
        ]
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    sys_level

    管理员角色,1表示主管理员,2表示子管理员

    userid

    员工id

    获取管理员通讯录权限范围

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/topapi/user/get_admin_scope?access_token=ACCESS_TOKEN

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    userid

    String

    员工id

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/user/get_admin_scope");
    OapiUserGetAdminScopeRequest req = new OapiUserGetAdminScopeRequest();
    req.setUserid("userid1");
    OapiUserGetAdminScopeResponse rsp = client.execute(req, accessToken);

     

    返回结果

    {
        "errcode": 0,
        "errmsg": "ok",
        "dept_ids":[1,2]
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    dept_ids

    可管理的部门id列表

    根据unionid获取userid

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/getUseridByUnionid?access_token=ACCESS_TOKEN&unionid=xxx

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    unionid

    String

    员工在当前开发者企业账号范围内的唯一标识,系统生成,固定值,不会改变

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getUseridByUnionid");
    OapiUserGetUseridByUnionidRequest request = new OapiUserGetUseridByUnionidRequest();
    request.setUnionid("M9Ar4MVQA4vk4iPRwIxxxxxxxxx");
    request.setHttpMethod("GET");
    
    OapiUserGetUseridByUnionidResponse response = client.execute(request, accessToken);

     

    返回结果

    {
        "errcode": 0,
        "errmsg": "ok",
        "contactType": 0,
        "userid": "userid1"
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    contactType

    联系类型,0表示企业内部员工,1表示企业外部联系人

    userid

    员工id

     

    根据手机号获取userid

    企业使用此接口可通过手机号获取其所对应员工的userid。

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/get_by_mobile?access_token=ACCESS_TOKEN&mobile=1xxxxxxxxxx

    参数说明:

    参数

    类型

    是否必须

    说明

    access_token

    String

    必须

    调用接口凭证,通过获取企业access_token获取

    mobile

    String

    必须

    手机号码

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_by_mobile");
    OapiUserGetByMobileRequest request = new OapiUserGetByMobileRequest();
    request.setMobile("1xxxxxxxxxx");
    
    OapiUserGetByMobileResponse execute = client.execute(request, access_token);

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    userid

    员工在当前企业内的唯一标识。

     

    获取企业员工人数

     

    调试工具在线调试

    请求方式:GET(HTTPS)

    请求地址:https://oapi.dingtalk.com/user/get_org_user_count?access_token=ACCESS_TOKEN&onlyActive=0

    参数说明

    参数

    类型

    必须

    说明

    access_token

    String

    调用接口凭证

    onlyActive

    Number

    0:包含未激活钉钉的人员数量

    1:不包含未激活钉钉的人员数量

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_org_user_count");
    OapiUserGetOrgUserCountRequest request = new OapiUserGetOrgUserCountRequest();
    request.setOnlyActive(1L);
    request.setHttpMethod("GET");
    OapiUserGetOrgUserCountResponse response = client.execute(request, accessToken);

     

    返回结果

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

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    count

    企业员工数量

     

    未登录钉钉的员工列表

    企业使用此接口可查询指定日期内未登录钉钉的企业员工列表 (每天9点后调用接口才能确保获取前一天数据)

     

    调试工具在线调试

    请求方式:POST(HTTPS)

    请求地址:https://oapi.dingtalk.com/topapi/inactive/user/get?access_token=ACCESS_TOKEN

    参数说明:

    名称

    类型

    是否必须

    示例值

    说明

    query_date

    String

    必须

    20190808

    查询日期

    offset

    Number

    必须

    0

    分页数据偏移量,从0开始

    size

    Number

    必须

    100

    每页大小,最大100

    SDK请求示例(JAVA)

    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/inactive/user/get");
    OapiInactiveUserGetRequest request = new OapiInactiveUserGetRequest();
    // 分页偏移量
    request.setOffset(0L);
    // 每页size,最多100
    request.setSize(100L);
    // 查询日期
    request.setQueryDate("20190903");
    OapiInactiveUserGetResponse response = client.execute(request, access_token);

     

    返回结果

    {
      "errcode": 0,
      "errmsg":"成功",
      "result": {
        "has_more": false,
        "list": [
          "1075xxxxx",
          "1075xxxxx",
          "000000000"
        ]
      }
    }

     

    参数

    说明

    errcode

    返回码

    errmsg

    对返回码的文本描述内容

    result

     

    └ has_more

    是否还有更多数据

    └ list

    未登录用户userId列表

     

    展开全文
    dingdingoa 2020-09-17 17:40:57
  • 1.96MB weixin_44575744 2019-01-19 12:29:04
  • 功能需求 所开发的软件内部状态需要进行监控,...对比了企业微信和钉钉机器人的开发文档。选择了简单的钉钉机器人的实现方式。平时工作也是利用钉钉通知工作消息,因此算是锦上添花吧。 功能实现 自定义机器人接入开发

    功能需求

    所开发的软件内部状态需要进行监控,如当有服务不可用,即时通知系统维护人员监控告警消息。目前我们已基本离不开手机,因此能够通过手机收取消息可谓是方便之至。

    功能分析

    可选的方案有以下几种。

    • 邮箱方式
    • 企业微信
    • 钉钉机器人
    • 自开发手机移动APP

    因为邮箱经常收到很多垃圾信息,习惯屏蔽之。自开发手机移动APP所消耗的资源太大,而且功能较为单一。对比了企业微信和钉钉机器人的开发文档。选择了简单的钉钉机器人的实现方式。平时工作也是利用钉钉通知工作消息,因此算是锦上添花吧。

    功能实现

    自定义机器人接入开发文档链接在此。开发流程在文档里已经介绍的很详细了,不再赘述。
    原理就是利用HTTP POST请求钉钉服务器上该功能的微服务,钉钉也给开发者提供了SDK,能够快速上手完成业务功能开发。
    需要说明的是当前机器人尚不支持应答机制,该机制指的是群里成员在聊天@机器人的时候,钉钉回调指定的服务地址,即Outgoing机器人。
    消息类型支持文本 (text)链接 (link)Markdown(支持部分语法)ActionCardFeedCard

    结果展示

    消息类型选择了钉钉提供的link方式。
    在这里插入图片描述

    展开全文
    qq_40657528 2021-03-05 16:16:18
  • 本篇我们来讨论下关于jenkins社区中钉钉提醒这个插件的二次开发过程。为什么需要二次开发呢,很简单,这个插件只是提供了最基本的构建后的提醒,有时候,我们需要一些额外的功能。例如,我们在打完app的包后,利用这...

           本篇我们来讨论下关于jenkins社区中钉钉提醒这个插件的二次开发过程。为什么需要二次开发呢,很简单,这个插件只是提供了最基本的构建后的提醒,有时候,我们需要一些额外的功能。例如,我们在打完app的包后,利用这个插件是可以发送提醒,但是点击标题,这个插件默认跳转的是jenkins上当前构建号的页面。我的实际工作中,有一个需求,用户在钉钉群,点击这个成功打包提醒,希望跳转到一个下载包的页面。点击失败提醒,和改插件的原功能一样,直接跳转到当前构建失败的这个构建号页面。


           本文介绍的钉钉提醒插件的github的地址是:https://github.com/jenkinsci/dingding-notifications-plugin

    可以先看看作者的写的效果图介绍,大概了解下提醒的效果。但是文章没有介绍点击可以跳转到构建号的页面。如果可以,先安装jenkins环境,然后到插件管理下载这个钉钉提醒插件,自己试试提醒效果。

     

    需求:用户点击打包成功提醒,跳转到下载路径,点击失败打包提醒,跳转到当前构建号页面。

     

    需求分析

           原作者实现了打包成功或者失败,点击标题都跳转到当前构建号的页面。这个功能是通用的,例如网站项目代码构建就没有下载功能。但是我们现在做的是APP自动化构建,肯定要给用户提供下载功能。思考一下,也就是说,我们在这个插件的界面,添加一个下载链接的输入控件,打包成功发送提醒这个方法,修改原来的链接,替换成用户输入的下载链接,这样打包成功提醒,点击就可以调整到下载包的web界面。

    不要有在代码写死打包下载路径的想法,这个想法是愚蠢的。因为换了一个环境,打包下载的路径可能就要换。属于,这个下载路径我们需要在前端设计一个文本输入框,让用户填写,代码里获取这个就可以。我们只动打包成功发送提醒消息这个代码,失败的代码不用动。

            这是一个很小的需求变动,我们可以通过这种二次开发过程,窥探下jenkins的插件开发过程。成功了,也好给自己一个满足感,会了这个基本,接下来,我们还可以针对提醒消息内容进行优化,再次开发新的功能。

     

    具体二次开发过程

    1. 前提条件

    做这个二次开发是需要一些前提条件的:

    1)Java代码阅读能力

    2)钉钉聊天软件,提前设置好机器人

    3)IDEA Java IDE开发工具

    4)本地安装好Maven环境

    5)Jenkins安装好,插件需要安装到Jenkins上进行测试

     

    2. Github下载源码

           下载源码,一般有两个方法,git命令下载或者直接下载项目zip包。由于我博客文章中介绍了git的基本命令,所以,这里我选择git clone源码到本地。

    1)打开git bash窗口

    如果没有安装git,请到博客对应文章去查找方法,或者百度,或者下载zip包的源码,忽略本步骤。

    在桌面,右键点击git bash here


    2)输入如下命令

    首先,我们获取这个github项目的地址,如下图红框,如果不会git,选择Download ZIP这个按钮下载源码到本地。

    在git bash输入如下命令


           由于我是在桌面打开git bash的,所以下载的项目的文件夹会在桌面生成,文件夹名称叫dingding-notifications-plugin,根据上图来看,源码是成功下载到本地。


    3)  检查源码是否成功下载

           打开桌面源码文件夹,点击展开src,和该项目github地址对比下,网络没有问题,git命令肯定帮你成功下载源码到本地。


    3. 编辑器打开下载源码

           源码下载好了,我们需要用IDEA打开。打开IntelliJ IDEA之后,点击File-New-Moudle from existing source,选择刚才桌面的dingding文件夹,效果如下。


           一般来说,我们都要右键pom.xml-Maven-DownloadSources,这样打开里面的java文件就不会报各种错误,特别是哪些导入包语句。或者点击右键reimport菜单。

     

    展开源码,得到如下结构图。


           主要就是编辑config.jelly添加前端一个文本输入框,用来接收用户的包下载地址。在上面三个方法和一个借口,插入对应获取下载包地址的方法,并且修改成功状态下打包的json字符串中的url换成打包下载路径的URL。

     

    4. 二次开发过程

           为了区别开发前后效果,我先在Jenkins上安装一个在线下载的插件。就是在插件管理,搜索dingding,然后点击下载安装。


    新建一个job, 构建选择bat命令


    因为我们仅仅测试钉钉提醒插件,随便写一个dos命令来作为构建配置。构建后选择钉钉提醒插件。


           我就是在jenkins URL 和钉钉access token之间插入一个输入框,用来获取打包下载路径。这个功能就是本篇的介绍的所谓的二次开发。真正的开发就下面开始的过程。

     

    1)添加一个下载包路径

    这个最简单,我们先来实现简单的。所有的前端页面的空间布局都写在config.jetty这个文件中。


    这个代码和前面构建后效果图对比,你就很快明白了。所以,我们插入一个下载包路径的文本输入框应该是这样写。


    红框就是我添加的控件部分的代码。直接复制,然后修改下就可以。这个文件如果没有出错,我们暂时不动它,只有到最后测试的时候才知道是什么效果。

     

    2)构造一个获取用户输入buildURL的方法

    在上面的jetty配置文件中,我们可以参考accessToken这个field是如何写获取用户输入的token的方法。

    我们可以在DingdingNotifier.java找到accessToken是定义的一个类属性。所以,我们这里也定义一个buildURL的类属性并且添加get方法
    
    
    如果你在打开代码问题,出现导入包语句错误,你可以手动点击错误地方,选择添加到library,有些包确实不会自动帮你导入到项目的library。

     

    3)修改下构造方法,buildURL添加进入构造方法

     

    4)打开DingdingServiceImpl.java,修改构建成功提醒的方法
     

    5)修改构建成功方法的提醒

    因为我们要构建成功,点击跳转到下载页面。

     

    6) 返回到DingdingNotifier.java文件,修改如下
    
    
    因为我们修改了DingdingServiceImpl的构造函数,所以这个地方也需要添加buildURL这个参数。保存代码,下面开始打包测试。


    5. 打包进行测试

     

    打包测试,我们在jenkins上是需要得到一个.hpi的文件,下面就教你如何打包。

    1)打开cmd,进入到桌面dingding-notifications-plugin这个文件夹


    2)使用mvn package打包


    3)打包成功


    4)查看打包


    根据上面的路径,拷贝出.hpi文件到桌面,下一步,我们要上传到jenkins来进行测试

    5)上传安装测试

           由于我前面在线安装了钉钉提醒这个插件,所以我这里先要卸载,然后插件管理选择高级,然后上传。

    点击上传按钮,开始安装。可能需要重启jenkins服务。


    6)构建后钉钉提醒插件效果

    看到这里,我们成功添加了一个APP包下载地址的输入框。构建测试需要钉钉群,添加机器人,具体就不介绍了。

    我在APP包下载地址输入框输入https://www.baidu.com,实际项目,可以设置你们tomcat配置好的docbase的地址。然后输入钉钉群设置的机器人的token。

     

    7)实际构建测试

    我这边测试了下,点击红框位置,会跳转到百度首页,这个就证明了,我实现了这个需求。

     

           以上就是关于钉钉提醒这个插件的二次开发的完整过程,主要是这个开源项目代码很少,容易读懂,而且我们添加的新的需求也很简单,比较容易实现。通过这个实战,让我们基本了解一个jenkins插件的开发流程中的部分知识,至少知道mavn项目的如何打包,而且还对我们实际工作的项目有帮助,这个就稍微有点成就感。

    展开全文
    u011541946 2017-11-25 22:43:02
  • 5星
    268KB bjshanxi 2018-01-07 18:49:08
  • weixin_39953618 2021-03-23 12:47:05
  • 1.18MB kendy94 2018-09-05 19:12:18
  • weixin_35300124 2020-12-23 02:40:50
  • 5星
    5.05MB simbagu 2019-01-17 15:26:51
  • xiaoxiao_2020 2020-12-03 20:17:41

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 5,861
精华内容 2,344
关键字:

钉钉二次开发