钉钉第三方企业应用开发快速入门

钉钉第三方企业应用开发快速入门

快速启动入门

1. 创建小程序

1.1. 登录开发者后台

登录钉钉开发者后台，选择应用开发-第三方企业应用-小程序，点击创建应用。

1.2. 填写基础信息

填写应用基本信息，包括应用名称、应用Logo、应用类型和应用简介。

1.3. 查看应用信息

创建成功后，可以在应用列表查看创建的应用。点击应用还可以查看应用的详细信息，如下图所示：

2. 设置安全域名

小程序需要事先设置一个或多个服务端安全域名（或IP），小程序前端只能通过这些安全域名（或IP）与服务端进行网络通信。当安全域名更新时，需要在IDE重新打包上传版本，设置的域名才会生效。

本质上，小程序前端与后端的网络通信是同普通的H5前后端一样的。因此在您做快速体验时，可以填写小程序前端所在环境能访问的任何域名/IP地址，比如可以是您自己的办公电脑本机地址或者局域网内地址。

就是将你服务器的域名或地址添加进去

3. 设置接口权限

钉钉开放了丰富的服务端接口能力，开发者可以使用这些接口能力，实现企业系统与钉钉的集成打通。在调用接口前，需要先申请并设置接口调用权限，包括通讯录权限、外部联系人权限、审批权限及内购开发权限等。如下图所示。

4. 开发管理(创建回调)

设置回调URL用于激活接口，没有公网域名可以使用内网穿透的方式对外暴露，以便钉钉回调

5. 下载源码

使用命令git clone下载代码，也可以直接用HTTP形式从代码仓库下载。

服务端代码
git clone https://github.com/opendingtalk/eapp-isv-quick-start-java.git

前端代码
git clone https://github.com/opendingtalk/eapp-isv-quick-start-fe.git

6. 设置与修改源码

6.1. 服务器端

6.1.1. 配置代码

修改com.config.Constant.java类中的配置

/**
 * 项目中的常量定义类
 */
public class Constant {
    /**
     * 应用的SuiteKey，登录开发者后台，点击应用管理，进入应用详情可见
     */
    public static final String SUITE_KEY="凭证与基础信息页面中SuiteKey的值";

    /**
     * 应用的SuiteSecret，登录开发者后台，点击应用管理，进入应用详情可见
     */
    public static final String SUITE_SECRET="凭证与基础信息页面中SuiteSecret的值";

    /**
     * 回调URL签名用。应用的签名Token, 登录开发者后台，点击应用管理，进入应用详情可见
     */
    public static final String TOKEN = "自定义要与开发管理中的 `Token` 保持一致";

    /**
     * 回调URL加解密用。应用的"数据加密密钥"，登录开发者后台，点击应用管理，进入应用详情可见
     */
    public static final String ENCODING_AES_KEY = "自定义要与开发管理中 `数据加密密钥` 保持一致";

    /**
     * 用于暂时保存钉钉发来的TICKET值
     */
    public static String TICKET;

}

6.1.2. 业务代码

修改com.controller.CallbackController.java类中的dingCallback方法

//在 else if (EVENT_SUITE_TICKET.equals(eventType)) {}中添加如下代码
//用于更新Ticket
Constant.TICKET = String.valueOf(callBackContent.get("SuiteTicket"));

//在else if (EVENT_TMP_AUTH_CODE.equals(eventType)) {}中添加如下代码，也可以抽取成方法调用
//用于激活应用，当你在版本管理与发布中 点击开通应用时被调用
try {
    //根据回调数据类型做不同的业务处理
    String authCode = callBackContent.getString("AuthCode");
    String authCorpId = callBackContent.getString("AuthCorpId");

    //bizLogger.info("收到审批任务进度更新: " + plainText);
    //获取第三方企业凭证suite_access_token
    DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_suite_token");
    OapiServiceGetSuiteTokenRequest request = new OapiServiceGetSuiteTokenRequest();
    request.setSuiteKey(Constant.SUITE_KEY);
    request.setSuiteSecret(Constant.SUITE_SECRET);
    request.setSuiteTicket("suiteTicket");

    OapiServiceGetSuiteTokenResponse response = client.execute(request);
    JSONObject jsonObject = JSONObject.parseObject(response.getBody());
    String suite_access_token = jsonObject.getString("suite_access_token");
    System.out.println("得到的suite_access_token===" + suite_access_token);
    
    //获取永久授权码
    DingTalkClient client1 = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_permanent_code?suite_access_token=" + suite_access_token);
    OapiServiceGetPermanentCodeRequest req = new OapiServiceGetPermanentCodeRequest();
    req.setTmpAuthCode(authCode);
    OapiServiceGetPermanentCodeResponse rsp = client1.execute(req);
    System.out.println(rsp.getBody());
    JSONObject jsonObject1 = JSONObject.parseObject(rsp.getBody());
    String permanent_code = jsonObject1.getString("permanent_code");
    System.out.println("得到的永久授权码===" + permanent_code);
    //String permanent_code = jsonObject1.getString("permanent_code");
    //激活应用
    DingTalkClient client3 = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/activate_suite?suite_access_token=" + suite_access_token);
    OapiServiceActivateSuiteRequest req3 = new OapiServiceActivateSuiteRequest();
    req3.setSuiteKey(Constant.SUITE_KEY);
    req3.setAuthCorpid(authCorpId);
    req3.setPermanentCode(permanent_code);
    OapiServiceActivateSuiteResponse rsp3 = client3.execute(req3);
    
    System.out.println("激活应用结果===" + rsp.getBody());
    //todo: 实现审批的业务逻辑，如发消息
} catch (ApiException e) {
    e.printStackTrace();
}

修改com.controller.IndexController.java类中的getSuiteTicket(String suiteKey)方法

private String getSuiteTicket(String suiteKey) {
    //返回钉钉推送来的Ticket值
    return Constant.TICKET;
}

6.2. 前端

下载钉钉小程序开发者工具IDE，安装并打开

打开IDE后选择您下载的前端项目eapp-isv-quick-start-fe文件夹，选择开发的应用类型，

打开后在右上角点击登录，出现扫码登录界面，使用钉钉扫码登录IDE。

注意：如果开发者已经打开IDE，请关闭重新打开，初次打开才可以选择打开新工程。

选择项目类型即要开发的应用类型。

点击右上角登录按钮使用钉钉扫码登录。

6.2.1. 修改前端配置

修改文件eapp-isv-quick-start-fe/page/index/index.js。

IP端口为本机的IP和PORT，注意url中的IP或域名必须是开发者平台中设置的本应用的安全域名。

let domain = "https://sakura.xxxxxxxxxx";//设置为内网穿透的地址就行

7. 添加体验组织并开通应用

重要：面向企业的应用必须企业开通才能进行体验，您需要创建专门的体验组织并为此组织开通本应用。

请注意：此处添加的体验组织是创建全新的测试组织，并不能添加已有组织为体验组织-比如本应用所在的开发组织。

测试应用可以直接开通。而正式应用需要验证回调有效性并设置好回调URL才能开通。本demo建议创建的是测试应用，因此可以暂时忽略验证回调有效性，可直接开通本应用。

添加一个非当前应用持有者的团队，然后点击开通应用此时要保证你的服务器端是开启的

8. 推送Ticket

此时要保证你的服务器端是开启的

9. 项目关联钉钉应用

然后启动前端项目（启动之前要确保开通应用与推送Ticket已经完成并且成功（就是第7、8步）），如果获取到用户信息userid则表示应用运行成功。

注意：关联的小程序，和体验组织（这里的体验组织是第七步创建并开通的而不是创建此项目的团队）