钉钉开发文档

线下调试实践

更新时间: 2018-8-23

本文主要示范了ISV开发第三方企业E应用过程中的开发调试过程。ISV可以在此基础上进行二次开发。
本文在QuickStart的基础上,新增了以下功能的演示:
1.设置钉钉云数据推送并且处理钉钉推送的数据。
2.使用SDK调用钉钉服务端API的示例代码。
3.上传并且发布E应用的前端版本。
4.给自己发送一条OA消息,并且在钉钉APP端点击该OA消息,实现打开E应用。
所以在阅读本文之前,建议您花费一些时间了解一下QuickStart文档。

文档对应视频

请扫码关注钉钉开放平台官方应用

image.png

1.创建和设置应用

注意:
1.选择创建测试应用。请选择应用类型为“测试应用”。只有测试应用支持线下调试。
2.创建应用的时候请选择“钉钉云推送”。不要选择”使用HTTP推送”。不推荐使用HTTP方式的回调。
参考文档创建应用,创建一个三方企业E应用。应用创建完成之后,打开应用详情页面进行设置。
3.设置“开发人员”,输入自己的手机号码,添加自己为开发人员。
4.设置”安全域名”,输入自己工作电脑的IP。

2.创建钉钉云推送数据库

a.准备公网能够访问的Mysql数据库,参考文档设置测试的数据库,设置一个用于开发调试的Mysql数据库。
 注意:此处设置的Mysql数据库不是钉钉云环境中的RDS,只能用于开发测试。
如下图所示,点击按钮“添加Mysql实例”,输入账号密码添加一个Mysql实例。
注意:输入的账号密码为文档设置测试的数据库中设置的账号密码。

image.png

3.设置应用的回调

回到E应用详情页面,点击编辑,到E应用编辑页面。
勾选回调事件。如果勾选框为灰色,请点击右上角的“权限管理”申请权限。
选择回调RDS,在下拉列表中选择已经设置好的钉钉云推送数据库。
注意:只有测试应用才能选择非钉钉云的推送数据库。

image.png

4.开通应用

参考QuickStart的4.3 章节添加体验组织并开通应用
应用开通之后登录钉钉客户端,可以在钉钉客户端的“工作台”界面看到开通成功的应用。

image.png

5.下载E应用服务端和前端的工程代码

下载代码。

E应用最佳实践服务端代码
git clone https://github.com/opendingtalk/eapp-isv-project.git

E应用最佳实践前端代码
git clone https://github.com/opendingtalk/eapp-isv-project-fe.git

6.设置和启动服务端

6.1创建ISV的业务数据库。

参见工程中的eapp-isv-project/src/eapp-isv-project.sql文件

CREATE DATABASE isv_dingtalk_biz DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

CREATE TABLE `biz_lock` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
  `gmt_create` datetime NOT NULL COMMENT '创建时间',
  `gmt_modified` datetime NOT NULL COMMENT '修改时间',
  `lock_key` varchar(128) NOT NULL COMMENT '锁Key',
  `expire` bigint(20) unsigned NOT NULL COMMENT '锁过期时间戳',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_lock` (`lock_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='同步业务锁';

CREATE TABLE `authed_corp` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'ID',
  `gmt_create` datetime NOT NULL COMMENT '创建时间',
  `gmt_modified` datetime NOT NULL COMMENT '更新时间',
  `corp_name` varchar(128) NOT NULL COMMENT '企业名称',
  `corp_id` varchar(64) NOT NULL COMMENT '企业ID',
  `access_token` varchar(128) NOT NULL COMMENT '企业访问AccessToken',
  `access_token_expire` bigint(20) NOT NULL COMMENT '企业访问AccessToken过期时间毫秒',
  `permanent_code` varchar(128) NOT NULL COMMENT '企业访问开通应用的永久授权码',
  `suite_key` varchar(128) NOT NULL COMMENT '企业开通的应用/套件',
  `agent_id` bigint(20) unsigned DEFAULT NULL COMMENT '企业开通应用实例id',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_corp_suite` (`corp_id`,`suite_key`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=17 DEFAULT CHARSET=utf8mb4 COMMENT='授权开通应用套件的企业';

6.2修改服务端代码配置。

参见工程中的eapp-isv-project/src/main/resources/application.properties文件。

#钉钉云推送数据源驱动
datasource.ding.driverClassName = com.mysql.jdbc.Driver
#钉钉云数据推送数据源地址
datasource.ding.url = jdbc:mysql://ip:port/ding_cloud_push?useUnicode=true&characterEncoding=utf-8
#钉钉云数据推送ding_cloud_push数据库的数据源账号
datasource.ding.username = xx
#钉钉云数据推送ding_cloud_push数据库的数据源密码
datasource.ding.password = xxx

#ISV业务数据源驱动
datasource.biz.driverClassName = com.mysql.jdbc.Driver
#ISV业务DB数据源地址
datasource.biz.url = jdbc:mysql://ip:port/isv_dingtalk_biz?useUnicode=true&characterEncoding=utf-8
#ISV的数据库的数据源账号
datasource.biz.username = xxx
#ISV的数据库的数据源密码
datasource.biz.password = xx


#服务启动端口号。
server.port=8080
#当前程序运行环境。默认为日常
environment=daily
#日志配置路径
logging.config=classpath:logback.xml
#配置各个LOG的输出级别
logging.level.root=info
logging.level.com.mapper.ding=debug

#配置项目运行的钉钉应用信息。
suiteId=0
suiteKey=0
suiteSecret=0
#配置预发环境下处理的企业。注意线上不对这些企业的数据进行处理!
#如果这个列表配置的是空数组。那么预发和线上处理是相同的
preEvnCorpIdList=[]

6.3打包

mvn clean package -Dmaven.test.skip=true

6.4启动

java -jar target/eapp-isv-project-1.0.0.jar

6.5查看启动页面

image.png

7.设置和启动前端

7.1下载IDE导入程序

参考QuickStart的4.1章节 下载IDE,导入前端代码

7.2修改前端配置

参考QuickStart的4.2章节 修改E应用前端配置

7.3添加体验组织并开通应用

参考QuickStart的4.3章节 添加体验组织并开通应用

7.4前端IDE模拟器上体验应用

参考QuickStart的4.4章节 前端IDE模拟器上体验应用

7.5上传程序包

注意“选择组织”和“选择应用”选项中,选择和创建的E应用对应的创建组织和应用。

image.png

8.设置前端发布版本

8.1设置版本为体验版

进入三方企业E应用详情页面,点击“版本管理”TAB。选择刚刚上传的前端版本设置为体验版。
设置为体验版之后,可以在对应企业下扫码打开该前端版本的应用。

image.png

8.2扫码体验

选择一个体验企业。钉钉扫码体验该版本E应用。
注意:1.你要是该企业的员工 2.该企业要已经开通该应用

image.png

钉钉客户端打开效果:

image.png

点击“测试发消息”按钮,可以在钉钉客户端的“工作通知中”看到发出的消息。
点击消息,链接打开E应用。并且在应用中去到页面中传递的参数。

image.png

8.3发布灰度版本

在验证E应用体验版正常之后。E应用版本管理页面点击“灰度”按钮,将此版本的E应用发布成为线上灰度包。
发布过程中需要填写corpid信息。表示对应的corpid企业在打开的E应用版本是该灰度版。
此时开发者可以邀请该企业下的员工进行灰度版本体验。

image.png

8.4发布线上版

灰度测试完成,点击发布,将该版本的E应用正式发布上线。

image.png