钉钉开发文档

开发E应用

更新时间: 2019-2-13

前端开发

项目创建

下载钉钉E应用开发者工具IDE,安装并打开。打开IDE后,选择新建项目或者打开项目(比如已有项目或Demo),
image.png
选择要开发的应用类型“钉钉”-“第三方企业应用”;
如果你初次编写E应用代码,可以使用我们提供的“组件/API示例”模板创建项目
image.png
点击下一步填写项目名称和项目路径,然后点击完成即可。

代码编写

打开项目,会默认进入代码编辑模式。从左到右,依次是文件操作区、代码编辑区和预览区。
image.png

  • 代码编辑

代码编辑区可以对当前项目进行代码编写和文件的添加、删除以及重命名等基本操作。

  • 实时预览

在代码编辑区修改任何代码都会重新编译,然后自动刷新应用。

  • 自动补全

IDE工具针对dd接口和axml提供了大量的自动补全提示,以帮助开发者提高效率。

本地调试

  • 预览区

这里可真实模拟在钉钉应用里的表现,并针对绝大部分的API提供了模拟功能。

  • 调试模式

点击下方的“调试器”,可切换到调试模式。
image.png
E应用调试工具提供了axml和acss的支持,支持组件层级、属性回写等功能;同时也包含了Chrome调试工具中的网络请求、DOM元素检查、源码Debug等。

  • 出错反馈

当开发者在axml或者配置文件里编译出错时,保存后会对错误的信息以redbox的形式呈现给开发者。

真机预览

使用“钉钉扫码登录”并“关联应用”后,在开发者工具右上角点击“预览”按钮,选择“确认推送”,生成预览二维码,使用手机钉钉扫码预览即可。注意:请确保左上角已经正确关联了应用和组织,才能推送成功。
image.png
image.png

发布版本

在开发者工具右上角点击“上传按钮即可。
image.png
image.png
发布成功后,可以在开发者后台E应用的版本管理进行灰度、发布到线上等版本管理。
image.png

服务端开发

开通授权应用

  • 企业授权开通应用事件

此事件用于通知应用“哪个组织开通了本应用”,应用此时必须快速异步地初始化企业信息。

当企业管理员开通您开发的应用时,钉钉会把开通的企业标识corpId给推送下来,此推送称之为开通事件,应用应该把corpId持久化到数据库。
如果是HTTP回调方式,开发者必须立即发送(1秒内)成功处理的http response给钉钉服务器,而不应该在本事件内做大量耗时操作,从而给管理员开通应用流程提供更好的产品体验。

  • 应用主动获取企业信息

应用即便没有接收到“企业授权开通应用”回调事件,或者没有处理好回调事件,钉钉的开通流程也会走完,并且会在钉钉客户端的工作页内出现此应用图标。在此情况,应用依然可以通过API补偿获取企业信息。


当企业内某员工第一次点击此应用图标进入到应用首页后,应用的前端可以通过dd.corpId获取到当前企业的corpId,此时通过应用服务端查询数据库,以检查是否有此corpId对应的开通记录。如果应用没有开通记录,则可通过调用“获取企业授权的凭证”接口来检查企业开通情况,成功返回凭证则可存入数据库。当无法获取到accessToken时,证明此企业没有给应用授权。

获取企业授权的凭证

企业授权凭证access_token用来后续调用钉钉服务端API。

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_corp_token?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
	"auth_corpid":"auth_corpid_value",
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 三方应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉推送的suiteTicket。测试应用可以随意填写。
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中。签名计算说明
auth_corpid Http body 授权企业corpId,组装为JSON结构置于http post body部分

SDK请求示例(JAVA)

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_corp_token");
OapiServiceGetCorpTokenRequest req = new OapiServiceGetCorpTokenRequest();
req.setAuthCorpid("dingc365fcabbf733c3535c2f4657eb6378f");
OapiServiceGetCorpTokenResponse execute = client.execute(req,"suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
	"access_token":"xxxxxx",
	"expires_in":7200
}

返回结果说明:

参数 说明
access_token 授权方(企业)corp_access_token
expires_in access_token超时时间

获取授权信息

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_auth_info?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
	"auth_corpid":"auth_corpid_value"
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉推送的suiteTicket,测试应用可以随便填写
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中签名计算说明
auth_corpid Http body 授权企业方corpId,组装为JSON结构置于http post body部分

SDK请求示例(JAVA):

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_auth_info");
OapiServiceGetAuthInfoRequest req = new OapiServiceGetAuthInfoRequest();
req.setAuthCorpid("dingc365fcabbf733c3535c2f4657eb6378f");
OapiServiceGetAuthInfoResponse response = client.execute(req,"suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
   "auth_corp_info":{
	  "corp_logo_url":"http://xxxx.png",
	  "corp_name":"corpid",
	  "corpid":"auth_corpid_value",
	  "industry":"互联网",
	  "invite_code" : "1001",
	  "license_code": "xxxxx",
	  "auth_channel": "xxxxx",
	  "auth_channel_type": "xxxxx",
	  "is_authenticated":false,
	  "auth_level":0,
	  "invite_url":"https://yfm.dingtalk.com/invite/index?code=xxxx"
	},
	"auth_user_info":
    {
    	"userId":""
	},
    "auth_info":{
	"agent":[{
			"agent_name":"aaaa",
			"agentid":1,
			"appid":-3,
			"logo_url":"http://aaaaaa.com",
			"admin_list":["zhangsan","lisi"]
	}
	,{
			"agent_name":"bbbb",
			"agentid":4,
			"appid":-2,
			"logo_url":"http://vvvvvv.com",
			"admin_list":[]
	}]
	},
        "channel_auth_info": {
		"channelAgent": [
				{
					"agent_name": "应用1",
					"agentid": 36,
					"appid": 6,
					"logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
				},
				{
					"agent_name": "应用2",
					"agentid": 35,
					"appid": 7,
					"logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
				}]
		},
	 "errcode":0,
	"errmsg":"ok"
}

返回结果说明:

参数 说明
auth_corp_info 授权方企业信息
corpid 授权方企业id
invite_code 邀请码,只有自己邀请的企业才会返回邀请码,可用该邀请码统计不同渠道的拉新,否则值为空字符串
industry 企业所属行业
corp_name 授权方企业名称
license_code 序列号
auth_channel 渠道码
auth_channel_type 渠道类型,为了避免渠道码重复,可与渠道码共同确认渠道(可能为空。非空时当前只有满天星类型,值为STAR_ACTIVITY)
is_authenticated 企业是否认证
auth_level 企业认证等级,0:未认证,1:高级认证,2:中级认证,3:初级认证
invite_url 企业邀请链接
auth_user_info 授权方管理员信息
corp_logo_url 企业logo
auth_info 授权信息
agent 授权的应用信息
agentid 授权方应用id
channel_auth_info 授权的服务窗应用信息列表
agent_name 授权方应用名字
logo_url 授权方应用头像
appid 应用id
auth_info.agent.admin_list 对此微应用有管理权限的管理员userid

获取应用信息

该API用于获取已授权开通的企业的某个应用的基本信息,包括LOGO、名称、描述等。

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_agent?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{   
    "suite_key":"key_value",
    "auth_corpid":"auth_corpid_value",
    "agentid":541
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉给应用推送的ticket,测试应用可以随便填写
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中签名计算说明

POST参数说明:

参数 说明
suite_key 应用套件key
auth_corpid 授权企业方corpid
agentid 授权企业方应用id

SDK请求示例(JAVA):

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_agent");
OapiServiceGetAgentRequest request = new OapiServiceGetAgentRequest();
request.setAuthCorpid("dingd610f0141e19fa4d35c2f4657eb637fxxxx");
request.setSuiteKey("suitezmpdnvsw4syq53g6xxx");
request.setAgentid("211164860xxxx");
OapiServiceGetAgentResponse response = client.execute(request, "suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
    "agentid":541,
    "name":"公告",
    "logo_url":"http://xxxxxxx/png",
    "description":"企业重要消息",
    "close":1,
    "errcode":0,
    "errmsg":"ok"
}

返回结果说明:

参数 说明
agentid 授权方企业应用id
name 授权方企业应用名称
logo_url 授权方企业应用头像
description 授权方企业应用详情
close 授权方企业应用是否被禁用(0:禁用 1:正常 2:待激活 )

设置E应用

设置开发人员

在创建应用后,默认会把当前创建应用的操作者添加为开发人员,若应用有多个开发者,我们可以通过手机号码添加该应用的开发者。添加开发人员后,该开发人员可使用开发者工具进行应用开发。
image.png

设置安全域名

E应用需要事先设置一个或多个服务端安全域名(或IP),E应用前端只能通过这些安全域名(或IP)与服务端进行网络通信。

本质上,E应用前端与后端的网络通信是同普通的H5前后端一样的。因此在您做快速体验时,可以填写E应用前端所在环境能访问的任何域名/IP地址,比如可以是您自己的办公电脑本机地址或者局域网内地址。
您也可借助内网穿透工具映射一个可公网访问的临时地址,注意:内网穿透仅用于测试开发阶段。

image.png

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!