钉钉开发文档

JAVA版QuickStart

更新时间: 2018-9-17

本quick start为第三方企业E应用接入钉钉的JAVA版本的示例代码(此外还有php版本node版本),用于满足开发者40分钟左右快速体验钉钉开发。在此demo中,您会获取到用户信息和企业基础信息。

开发者需要对以下技术栈有最基本了解,环境配置合理。

项目 内容 备注
演示者OS MacOS 与linux/unix接近。windows执行命令会有较大不同,开发者酌情调整。
代码库 Github 请自行配置好git,也可以直接用http形式从代码仓库下载demo代码。
服务端语言 Java 请自行安装JDK7或以上,配置JAVA环境如JAVA_HOME,把java命令加入系统执行PATH。
代码构建 Maven 请自行安装和配置Maven。注意maven库是国外仓库,构建时可能会在下载依赖jar上耗费较长时间。有些网络加速工具会起到作用,请自行解决。
内网穿透 内网穿透工具 非必需。本demo代码包含钉钉回调应用示例(但本文不演示),若需在没有公网IP或域名的服务器上(比如您自己的办公电脑)调试回调URL,可借助本工具映射一个可公网访问的地址,注意仅用于测试开发阶段。测试类型的应用,回调的验证和调试对于快速体验demo为非必需,本文不再赘述,开发者可后续调试回调URL时详细了解。

通过四大步骤即可完成应用的开发体验,最终本应用会获取到用户信息和企业基础信息展示在前端:

创建和设置应用 -> 下载前后端示例代码 -> 设置和启动服务端 -> 前端设置和应用开通体验

1.创建和设置应用

建议创建测试应用,以免正式应用强制校验suiteTicket。可省去验证钉钉回调应用+应用获取正式suiteTicket环节。

创建应用

获取本机ip,设置到E应用的安全域名中

E应用前端向服务端发起网络请求时是直连安全域名或IP的,因此假如您的前端demo和服务端demo都在一个办公环境内(比如都在您的PC电脑上),是可以直接互通的,因此可以设置任何您的前端所在环境能连接到的域名或IP为安全域名。
您也可以通过钉钉提供的内网穿透工具生成一个临时二级域名给测试应用使用。

image.png

2.下载代码

用git clone代码,也可以直接用http形式从代码仓库下载。

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

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

3.设置和启动服务端

3.1 服务端项目配置

3.1.1 更改com.config.Constant.java文件

在您的IDE中找到类文件com.config.Constant.java,修改以下2个常量的参数值

/**
 * 应用的SuiteKey,登录开发者后台,点击应用管理,进入应用详情可见
 */
public static final String SUITE_KEY="";
/**
 * 应用的SuiteSecret,登录开发者后台,点击应用管理,进入应用详情可见
 */
public static final String SUITE_SECRET="";
/**
 * 回调URL加解密用。应用的数据加密密钥,登录开发者后台,点击应用管理,进入应用详情可见
 */
public static final String ENCODING_AES_KEY="";
/**
 * 回调URL签名用。应用的签名Token, 登录开发者后台,点击应用管理,进入应用详情可见
 */
public static final String TOKEN="";

SUITE_KEY、SUITE_SECRET参数请在开发者后台E应用-第三方企业应用获取。

进入开发者后台,点击头部“应用开发”,再点击左侧“E应用”,进入第三方企业应用列表,如下图

image.png

在第三方企业应用列表中点击右侧齿轮设置图片,进入下图所示页面,

image.png

再点击查看详情,进入下图

1534932319347-a088d199-438a-4868-bd7c-d904cf23d0e4.png

3.1.2 更改application.properties(非必要)

#服务启动端口号。
server.port=8080

3.2 服务端代码编译打包

进入项目文件路径,代码编译。

本步骤会从国外maven中心仓库下载依赖jar包,可能会比较耗时。有些网络加速/翻越工具会起到作用,请自行解决。

mvn clean compile -U

代码打包,生成可运行的jar文件

mvn clean package -Dmaven.test.skip=true

image.png

3.3 启动服务端程序

执行java命令启动程序(jar文件执行路径请根据您所在目录酌情选择)

java -jar target/eapp-isv-quick-start-1.0.0.jar

程序启动成功如下图所示

image.png

检查服务端启动成功页面
访问 http://localhost:8080/welcome 地址。打开页面如下图

image.png

4.前端设置和应用开通体验

4.1 下载E应用IDE,导入前端代码

请参考E应用前端IDE使用,下载、安装、使用IDE。
打开IDE后选择您下载的前端项目eapp-isv-quick-start-fe文件夹,选择开发的应用类型,
打开后在右上角点击登录,出现扫码登录界面,使用钉钉扫码登录IDE。

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

image.png

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

image.png

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

image.png

4.2 修改E应用前端配置

修改文件eapp-isv-quick-start-fe/page/index/index.js。
IP端口为本机的IP和PORT,注意url中的IP或域名必须是开发者平台中设置的本应用的安全域名。

let url = "http://30.xxx.xx.54:8080";

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

重要:面向企业的E应用必须企业开通才能进行体验,您需要创建专门的体验组织并为此组织开通本应用。
请注意:此处添加的体验组织是创建全新的测试组织,并不能添加已有组织为体验组织-比如本应用所在的开发组织。
测试应用可以直接开通。而正式应用需要验证回调有效性并设置好回调URL才能开通。本demo建议创建的是测试应用,因此可以暂时忽略验证回调有效性,可直接开通本应用。

依照本节前述的示例,进入到开发者后台的左侧菜单的E应用菜单,并选择进入应用详情页找到版本管理,可通过“添加体验组织”来创建全新体验组织和开通应用。也可以直接通过左侧“体验账号管理”来添加或删除体验组织。有了体验组织后在版本管理界面可以开通应用。如果您希望为体验组织添加成员,请登录钉钉管理后台,为体验组织添加成员,添加方法见注册账号

image.png

4.4.前端IDE模拟器上体验应用

在IDE上方,选择已经开通本应用的体验组织(如未出现尝试重启IDE),如下图:

image.png

接着再选择关联应用,IDE会重新编译前端代码并载入页面,

image.png

如果获取到用户信息userid则表示E应用运行成功。
祝贺,您已经成功体验本quick start。