• 钉钉组件


    一、简介

    1.1 概述

    钉钉服务支持

    1.2 组件坐标

    <dependency>
        <groupId>org.hzero.starter</groupId>
        <artifactId>hzero-starter-integrate-dd</artifactId>
    </dependency>
    

    二、使用说明

    提供钉钉基础接口、应用消息发送及通讯录同步方法

    2.1 钉钉基础接口

    DingCorpAddressService提供钉钉基础接口

        /**
         * 创建用户
         * @param userDTO
         * @param accessToken
         * @return
         */
        UserCreateResultDTO createUser( String accessToken,DingSyncUserDTO userDTO);
    
        /**
         * 更新用户
         * @param userDTO
         * @param accessToken
         * @return
         */
        DefaultResultDTO updateUser( String accessToken,DingSyncUserDTO userDTO);
    
        /**
         * 删除用户
         * @param userid
         * @param accessToken
         * @return
         */
        DefaultResultDTO deleteUserById( String accessToken, String userid);
    
        /**
         * 获取用户详情
         * @param userid
         * @param accessToken
         * @return
         */
        GetUserDTO getUserInfoByUserId(String accessToken, String userid,  String lang);
    
        /**
         * 通过部门ID获取用户userid列表
         * @param deptId
         * @param accessToken
         * @return
         */
        GetUserListDTO getUserListByDeptId( String accessToken, String deptId);
    
        /**
         *  获取部门用户详情
         * @param  accessToken
         * @param lang
         * @param department_id
         * @param offset
         * @param size
         * @param order
         * @return
         */
        GetDeptUserInfoResultDTO getDeptUserInfo(String  accessToken, String lang, Long department_id, Long offset, Long size, String order);
    
        /**
         * 获取部门用户
         * @param  accessToken
         * @param lang
         * @param department_id
         * @param offset
         * @param size
         * @param order
         * @return
         */
        GetDeptUserResultDTO getDeptUser(String  accessToken, String lang, Long department_id, Long offset, Long size, String order);
    
        /**
         * 获取管理员列表
         * @param  accessToken
         * @return
         */
        GetAdminListResultDTO getAdminList(String  accessToken);
    
        /**
         * 获取管理员通讯录权限范围
         * @param accessToken
         * @param userid
         * @return
         */
        GetAdminScopeResultDTO getAdminScope(String accessToken, String userid);
    
        /**
         * 根据unionid获取userid
         * @param accessToken
         * @param unionid
         * @return
         */
        GetUseridByUnionidResultDTO getUseridByUnionid(String accessToken, String unionid);
    
        /**
         * 根据手机号获取userid
         * @param  accessToken
         * @param mobile
         * @return
         */
        GetUseridByMobileResultDTO getUseridByMobile(String  accessToken, String mobile);
    
        /**
         * 获取企业员工人数
         * @param  accessToken
         * @param onlyActive
         * @return
         */
        GetOrgUserCountResultDTO getOrgUserCount(String  accessToken, Long onlyActive);
    
        /**
         * 未登录钉钉的员工列表
         * @param  accessToken
         * @param getInactiveUserDTO
         * @return
         */
        GetInactiveUserResultDTO getInactiveUser(String  accessToken, GetInactiveUserDTO getInactiveUserDTO);
    
        /**
         *
         * @param accessToken
         * @param code
         * @return
         */
        GetUserInfoByCodeResultDTO  getUserInfoByCode(String accessToken, String code);
    
        /**
         * 创建部门
         * @param deptDTO
         * @param accessToken
         * @return
         */
        CreateDeptResultDTO createDept( String accessToken,DingSyncDeptDTO deptDTO);
    
        /**
         * 更新部门
         * @param deptDTO
         * @param accessToken
         * @return
         */
       UpdateDeptResultDTO updateDept( String accessToken,DingSyncDeptDTO deptDTO);
    
        /**
         * 删除部门
         * @param id
         * @param accessToken
         * @return
         */
    
        DefaultResultDTO deleteDeptById(String accessToken, String id);
    
        /**
         * 获取部门列表
         * @param deptId
         * @param accessToken
         * @return
         */
        DeptListDTO getDeptList(Long deptId, String accessToken, String lang, String fetch_child);
    
        /**
         * 获取部门详情
         * @param id
         * @param accessToken
         * @return
         */
        GetDeptDTO getDeptById(String accessToken,String id,  String lang);
    
        /**
         * 获取子部门ID列表
         * @param id
         * @param accessToken
         * @return
         */
        GetSubDeptDTO getSubDeptbyId(String accessToken,String id );
    
        /**
         * 查询部门的所有上级父部门路径
         * @param accessToken
         * @param id
         * @return
         */
        GetListParentDeptsByDeptIdResultDTO getListParentDeptsByDeptId(String accessToken, String id);
    
        /**
         * 查询指定用户的所有上级父部门路径
         * @param accessToken
         * @param userId
         * @return
         */
        GetListParentDeptsByUserId getListParentDeptsByUserId(String accessToken, String userId);
    
    

    2.2 消息通知

    DingCorpAddressService提供钉钉消息通知相关方法

        /**
         * 发送工作通知消息-文本消息
         * @param accessToken
         * @param sendWorkTextMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkTextMessage(String accessToken , SendWorkTextMessageDTO sendWorkTextMessageDTO);
    
        /**
         * 发送工作通知消息-图片消息
         * @param accessToken
         * @param sendWorkImageMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkImageMessage(String accessToken , SendWorkImageMessageDTO sendWorkImageMessageDTO);
    
        /**
         * 发送工作通知消息-语音消息
         * @param accessToken
         * @param sendWorkVoiceMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkVoiceMessage(String accessToken , SendWorkVoiceMessageDTO sendWorkVoiceMessageDTO);
    
        /**
         * 发送工作通知消息-文件消息
         * @param accessToken
         * @param sendWorkFileMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkFileMessage(String accessToken , SendWorkFileMessageDTO sendWorkFileMessageDTO);
    
        /**
         * 发送工作通知消息-链接消息
         * @param accessToken
         * @param sendWorkLinkMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkLinkMessage(String accessToken , SendWorkLinkMessageDTO sendWorkLinkMessageDTO);
    
        /**
         * 发送工作通知消息-OA消息
         * @param accessToken
         * @param sendWorkOAMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkOAMessage(String accessToken , SendWorkOAMessageDTO sendWorkOAMessageDTO);
    
        /**
         * 发送工作通知消息-markdown消息
         * @param accessToken
         * @param sendWorkMarkDownMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkMarkDownMessage(String accessToken ,SendWorkMarkDownMessageDTO sendWorkMarkDownMessageDTO);
    
        /**
         * 发送工作通知消息-整体跳转卡片消息
         * @param accessToken
         * @param sendWorkWholeCardMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkWholeCardMessage(String accessToken, SendWorkWholeCardMessageDTO sendWorkWholeCardMessageDTO);
    
        /**
         * 发送工作通知消息-独立跳转卡片消息
         * @param accessToken
         * @param sendWorkIndependentCardMessageDTO
         * @return
         */
        SendWorkMessageResultDTO sendWorkIndependentCardMessage(String accessToken ,SendWorkIndependentCardMessageDTO sendWorkIndependentCardMessageDTO);
    
        /**
         *  查询工作通知消息的发送进度
         * @param accessToken
         * @param workProgressAndResultMessageDTO
         * @return
         */
         WorkProgressMessageResultDTO getWorkProgressMessage(String accessToken, WorkProgressAndResultMessageDTO workProgressAndResultMessageDTO);
    
        /**
         * 查询工作通知消息的发送结果
         * @param accessToken
         * @param workProgressAndResultMessageDTO
         * @return
         */
        WorkResultMessageDTO getWorkResultMessage(String accessToken, WorkProgressAndResultMessageDTO workProgressAndResultMessageDTO );
    
        /**
         * 工作通知消息撤回
         * @param accessToken
         * @param workMessageRecallDTO
         * @return
         */
       DefaultResultDTO getWorkMessageRecall(String accessToken, WorkMessageRecallDTO workMessageRecallDTO);
    
        /**
         * 发送群消息-文本消息
         * @param accessToken
         * @param sendGroupTextMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupTextMessage(String accessToken, SendGroupTextMessageDTO sendGroupTextMessageDTO);
    
        /**
         * 发送群消息-图片消息
         * @param accessToken
         * @param sendGroupImageMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupImageMessage(String accessToken, SendGroupImageMessageDTO sendGroupImageMessageDTO);
    
        /**
         * 发送群消息-语音消息
         * @param accessToken
         * @param sendGroupVoiceMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupVoiceMessage(String accessToken, SendGroupVoiceMessageDTO sendGroupVoiceMessageDTO);
    
        /**
         * 发送群消息-文件消息
         * @param accessToken
         * @param sendGroupFileMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupFileMessage(String accessToken, SendGroupFileMessageDTO sendGroupFileMessageDTO);
    
        /**
         * 发送群消息-链接消息
         * @param accessToken
         * @param sendGroupLinkMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupLinkMessage(String accessToken, SendGroupLinkMessageDTO sendGroupLinkMessageDTO);
    
        /**
         * 发送群消息-OA消息
         * @param accessToken
         * @param sendGroupOAMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupOAMessage(String accessToken, SendGroupOAMessageDTO sendGroupOAMessageDTO);
    
        /**
         * 发送群消息-markdown消息
         * @param accessToken
         * @param sendGroupMarkDownMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupMarkDownMessage(String accessToken, SendGroupMarkDownMessageDTO sendGroupMarkDownMessageDTO);
    
        /**
         * 发送群消息-整体跳转卡片消息
         * @param accessToken
         * @param sendGroupWholeCardMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupWholeCardMessage(String accessToken, SendGroupWholeCardMessageDTO sendGroupWholeCardMessageDTO);
    
        /**
         * 发送群消息-独立跳转卡片消息
         * @param accessToken
         * @param sendGroupIndependentCardMessageDTO
         * @return
         */
        SendGroupMessageResultDTO sendGroupIndependentCardMessage(String accessToken, SendGroupIndependentCardMessageDTO sendGroupIndependentCardMessageDTO);
    
        /**
         * 查询群消息已读人员列表
         * @param accessToken
         * @return
         */
        GetGroupMessageReadListResultDTO getGroupMessageReadList (String accessToken, String messageId, Long cursor, Integer size);
    
        /**
         * 创建会话
         * @param accessToken
         * @param createChatDTO
         * @return
         */
        CreateChatResultDTO createChat(String accessToken, CreateChatDTO createChatDTO);
    
        /**
         * 修改会话
         * @param accessToken
         * @return
         */
        DefaultResultDTO updateChat(String accessToken, UpdateChatDTO updateChatDTO);
    
        /**
         * 获取会话
         * @param accessToken
         * @param chatid
         * @return
         */
        GetChatResultDTO getChat(String accessToken, String chatid);
    
        /**
         * 发送普通消息-文本消息
         * @param accessToken
         * @param sendTextMessageDTO
         * @return
         */
        SendMessageResultDTO sendTextMessage(String accessToken, SendTextMessageDTO sendTextMessageDTO);
    
        /**
         * 发送普通消息-图片消息
         * @param accessToken
         * @param sendImageMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendImageMessage(String accessToken,SendImageMessageDTO sendImageMessageDTO);
    
        /**
         * 发送普通消息-语音消息
         * @param accessToken
         * @param sendVoiceMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendVoiceMessage(String accessToken, SendVoiceMessageDTO sendVoiceMessageDTO);
    
        /**
         * 发送普通消息-文件消息
         * @param accessToken
         * @param sendFileMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendFileMessage(String accessToken, SendFileMessageDTO sendFileMessageDTO);
    
        /**
         * 发送普通消息-链接消息
         * @param accessToken
         * @param sendLinkMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendLinkMessage(String accessToken, SendLinkMessageDTO sendLinkMessageDTO);
    
        /**
         * 发送普通消息-OA消息
         * @param accessToken
         * @param sendOAMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendOAMessage(String accessToken, SendOAMessageDTO sendOAMessageDTO);
    
        /**
         * 发送普通消息-markdown消息
         * @param accessToken
         * @param sendMarkDownMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendMarkDownMessage(String accessToken, SendMarkDownMessageDTO sendMarkDownMessageDTO);
    
        /**
         * 发送普通消息-整体跳转卡片消息
         * @param accessToken
         * @param sendWholeCardMessageDTO
         * @return
         */
    
        SendMessageResultDTO sendWholeCardMessage(String accessToken,SendWholeCardMessageDTO sendWholeCardMessageDTO);
    
        /**
         * 发送普通消息-独立跳转卡片消息
         * @param accessToken
         * @param sendIndependentCardMessageDTO
         * @return
         */
        SendMessageResultDTO sendIndependentCardMessage(String accessToken, SendIndependentCardMessageDTO sendIndependentCardMessageDTO);
    
    

    2.3 应用管理

    DingCorpAgentManageService钉钉应用管理相关方法

        /**
         * 获取应用列表
         * @param accessToken
         * @return
         */
        GetMicroappListDTO getAllMicroappList(String accessToken);
    
        /**
         * 获取员工可见的应用列表
         * @param accessToken
         * @param userid
         * @return
         */
        GetMicroappListDTO getMicroappListByUserId(String accessToken, String userid);
    
        /**
         * 获取应用的可见范围
         * @param accessToken
         * @param agentId
         * @return
         */
        GetMicroappVisibleDTO getMicroappVisible(String accessToken, Long agentId);
    
        /**
         * 设置应用的可见范围
         * @param accessToken
         * @param setMicroappVisibleDTO
         * @return
         */
        DefaultResultDTO   setMicroappVisible(String accessToken, SetMicroappVisibleDTO setMicroappVisibleDTO);
    
    

    2.4 jsapi_ticket

    DingTicketService提供钉钉jsapi_ticket相关方法

        /**
         * 获取jsapi_ticket
         * @param accessToken
         * @param type
         * @return
         */
        GetTicketResultDTO getTicket(String accessToken, String type);
    
        /**
         * 计算签名信息
         * @param ticket
         * @param nonceStr
         * @param timeStamp
         * @param url
         * @return
         */
        String signature(String ticket, String nonceStr, long timeStamp, String url);
    
    

    2.5 文件存储

    DingFileStorageService提供文件存储相关方法

        /**
         * 上传媒体文件
         * @param accessToken
         * @param type
         * @param media
         * @return
         */
        UploadMediaDTO uploadMedia(String accessToken, String type, String media);
    
        /**
         * 发送钉盘文件给指定用户
         * @param accessToken
         * @param agent_id
         * @param userid
         * @param media_id
         * @param file_name
         * @return
         */
        DefaultResultDTO sendFileToUser(String accessToken, String agent_id, String userid, String media_id, String file_name);
    
        /**
         * 新增文件到用户自定义空间
         * @param accessToken
         * @param agent_id
         * @param code
         * @param media_id
         * @param space_id
         * @param folder_id
         * @param name
         * @param overwrite
         * @return
         */
        AddFileDTO addFile(String accessToken, String agent_id, String code, String media_id, String space_id, String folder_id, String name, Boolean overwrite );
    
        /**
         * 获取企业下的自定义空间
         * @param accessToken
         * @param domain
         * @param agent_id
         * @return
         */
        GetEnterprisesSpaceDTO getEnterprisesSpace(String accessToken, String domain, String agent_id);
    
        /**
         * 获取应用自定义空间使用详情
         * @param accessToken
         * @param domain
         * @param agent_id
         * @return
         */
        getEnterprisesSpaceInfoResultDTO  getEnterprisesSpaceInfo(String accessToken, String domain, String agent_id);
    
        /**
         *  授权用户访问企业自定义空间
         * @param accessToken
         * @param agent_id
         * @param domain
         * @param type
         * @param userid
         * @param path
         * @param fileids
         * @param duration
         * @return
         */
        DefaultResultDTO  getAuthorizedUserSpace(String accessToken, String agent_id, String domain, String type, String userid, String path, String fileids, Integer duration );
    
        /**
         *  单步上传文件
         * @param accessToken
         * @param agent_id
         * @param file_size
         * @return
         */
        UploadFileDTO singleUploadFile(String accessToken, String agent_id, Integer file_size);
    
        /**
         * 开启分块上传事务
         * @param accessToken
         * @param agent_id
         * @param file_size
         * @param chunk_numbers
         * @return
         */
        UploadFileTransactionDTO openUploadFileTransaction(String  accessToken, String agent_id, Integer file_size, Integer chunk_numbers);
    
        /**
         * 上传文件块
         * @param accessToken
         * @param agent_id
         * @param upload_id
         * @param chunk_sequence
         * @return
         */
        DefaultResultDTO chunkUploadFile(String  accessToken, String agent_id, String upload_id, Integer chunk_sequence);
    
        /**
         * 提交文件上传事务
         * @param accessToken
         * @param agent_id
         * @param file_size
         * @param chunk_numbers
         * @param upload_id
         * @return
         */
        UploadFileDTO uploadFileTransaction(String  accessToken, String agent_id, Integer file_size, Integer chunk_numbers, String upload_id);
    
    

    2.6 通讯录同步

    DingCorpSyncService提供hzero通讯录增量同步到钉钉的相关方法

        /**
         * 获取token且redis缓存
         * @param appId 钉钉应用id
         * @param appSecret 钉钉应用secret
         * @return
         */
        TokenDTO getTokenWithCache(String appId, String appSecret);
    
        /**
         * 获取token
         * @param appId 钉钉应用id
         * @param appSecret 钉钉应用secret
         * @return
         */
        TokenDTO getToken(String appId, String appSecret);
    
        /**
         * 从第三方 获取企业微信的token
         * @param authUrl 第三方地址,参数需自己拼接
         * @return
         */
        TokenDTO getTokenFromThirdPart(String authUrl);
    
        /**
         *同步企业组织架构
         * @param ddSyncDeptDTOList 钉钉部门
         * @param ddSyncUserDTOS 钉钉用户
         * @param fileName 日志输出文件名
         * @param useGeneratedDeptId 是否使用自动生成的部门id
         * @param accessToken 授权Token
         * @return
         */
        SyncCorpResultDTO syncCorp(List<DingSyncDeptDTO> ddSyncDeptDTOList, List<DingSyncUserDTO> ddSyncUserDTOS,
                        String fileName, Boolean useGeneratedDeptId, String accessToken);