《钉钉应用开发者速成手册》之“如何调用钉钉API——服务端API”

本文涉及的产品
日志服务 SLS,月写入数据量 50GB 1个月
简介: 为了满足客户需求,钉钉目前主要提供了身份验证、通讯录管理、消息通知、智能办公四大类的服务端API接口给开发者使用。

身份验证

身份验证免登是指用户进入应用后,无需输入钉钉用户名和密码,应用程序可自动获取当前用户身份,进而登录系统的流程。身份验证的服务端API主要分为五部分,如下图所示:

image.png

  • 钉钉应用内免登实现企业内部或第三方企业应用免登,即企业员工在钉钉内使用企业内部应用或第三方企业应用时无需输入账号和密码。可通过以下步骤实现:
  1. 获取JSAPI免登授权码。
  2. 获取用户userId。
  3. 获取用户详情。
  • 管理后台免登应用管理后台免登指管理员在钉钉管理后台对应用进行设置和管理时,无需输入该应用的账号和密码,可直接登录应用的管理后台。可通过以下步骤实现:
  1. 获取免登授权码。
  2. 获取管理员身份信息。
  • 扫码登录实现扫码登录第三方网站。扫码登录指钉钉客户端扫码并确认登录web系统,在系统内获取正在访问用户的钉钉身份,无需输入账号密码的开发流程。提供了以下两种方式:
  • 直接使用钉钉提供的扫码登录页面。
  • 开发者可以将钉钉的登录二维码内嵌到自己的网站中,让用户进行扫码登录。
  • 钉钉内免登
    实现钉钉内免登第三方网站。钉钉内免登第三方网站指用户在钉钉客户端内点击H5网站链接时,无需输入账号密码系统自动获取正在访问用户钉钉身份。
  • 密码登录
    实现使用钉钉账号登录第三方网站。通过手动输入钉钉的账号密码,登录第三方独立的web系统,并获得正在访问用户的钉钉身份。

通讯录管理

通讯录是开发者接入钉钉时最常用到的一批接口,主要包含四大类接口,如下图所示:

说明

在调用通讯录相关接口前,请先添加对应的通讯录权限。开发者可以调用通讯录接口,将通讯录数据写到钉钉中,用于获取钉钉通讯录。如果企业想实时接收通讯录变更,可以注册钉钉的通讯录回调,实时接收通讯录的回调内容。

image.png

  • 用户管理
    包括增删改用户的接口,还可以获取部门下的用户,获取用户详情,获取管理员列表,跟进unionId获取userId,获取企业人数等接口。
  • 部门管理
    包括增删改部门,获取部门ID列表,获取部门详情,获取部门上级部门,获取用户上级部门等接口。
  • 角色管理
    角色分为角色和角色组,所以我们有增加删除修改角色,增加删除角色组合员工,获取角色组,获取角色列表和详情,获取角色下的员工列表等接口。
  • 外部联系人管理
    包括增删改外部联系人,获取外部联系人列表,详情,和标签列表等接口。

消息通知

消息通知主要分为三部分,如下图所示:

image.png

  • 工作通知消息是以企业工作通知会话中某个微应用的名义推送到员工的通知消息,例如审批通知,任务通知等。说明
  • 该接口是异步接口,接口返回成功并不表示用户一定会收到消息,需要通过 “查询工作通知消息的发送结果”接口查询是否发送成功。
  • 工作通知消息也有一些限流规则,具体规则可参考调用频率限制
  • 群会话消息
    是指可以调用接口,以系统名义向群里推送群聊消息。与之配合的是对应的创建群,更新群,获取群人员列表等服务端API接口。
  • 普通会话消息
    是指可以调用接口,以系统名义向群里推送群聊消息。与之配合的是对应的创建群,更新群,获取群人员列表等服务端API接口。

智能办公

智能办公包含以下七个部分,如下图所示:

image.png

  • 智能工作流
    包括发起审批实例,创建更新模板,创建更新待办,获取审批详情,审批回调,审批跳转,待办任务等接口。
  • 考勤
    可以获取考勤数据,获取请假数据,获取考勤组信息,获取排班信息等。
  • 日志
    可以获取日志数据,日志的已读、未读、评论、点赞等信息,获取日志模板。
  • 签到
    可以获取用户的签到记录
  • 智能填表
    可以获取企业智能填表的一些数据,还可以获取填表的一些模板。
  • 智能人事
    可查询待入职员工,查询在职员工,查询离职员工,还有获取花名册信息,添加待入职员工等接口。
  • 公告
    可以获取用户公告数据,包括公告的时间等。

如何调用服务端API

要调用API需要以下三个基础条件:

  • 钉钉应用
    钉钉应用作为您调用API时的身份,有AppKey和AppSecret用于验证您的身份。可以在钉钉开放平台应用开发页面创建应用,创建应用成功后,系统会自动生成AppKeyAppSecret
  • API
    在调用相关接口时,需要明确您即将需要调用的API相关参数定义。
  • 相关权限
    在调用相关接口前,您可能需要先申请对应的接口权限。您可以登陆钉钉开放平台,选择您创建的应用,选择权限管理,添加相应接口权限。

可通过以下步骤,完成服务端API接口的调用:

  1. 获取access_token。调用服务端API,首先要获取access_token。调用access_token的请求方式为GET(HTTPS),请求地址如下图所示,要输入两个参数appkey和appsecret。

说明

  • 正常情况下access_token的有效期是7200秒,有效期内重复获取会返回相同结果,并且自动续期。
  • POST请求必须在HTTP Header中设置对应的Content-Type:application/json。钉钉官方提供了统一的Java、PHP、.NET、Python对应的SDK,可参考服务端SDK下载

image.png

  1. 调用相关API接口。可通过以下方式调用服务端API接口:说明为了防止企业和ISV的应用程序错误从而引发钉钉服务器负载异常,默认情况下,每个服务端调用接口都会有一定的频率限制。当超过此限制时,调用接口会收到对应的错误码。限流规则可参考调用频率限制
  • 方式一:使用API文档中提供的SDK示例代码进行调用。
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/gettoken");
OapiGettokenRequest request = new OapiGettokenRequest();
request.setAppkey("appkey");
request.setAppsecret("appsecret");
request.setHttpMethod("GET");
OapiGettokenResponse response = client.execute(request);
System.out.println(response.getBody());
  • 方式二:自行编辑HTTP(s)请求来调用API。
请求方式: GET/POST(HTTPS)
请求地址: https://oapi.dingtalk.com/gettoken?appkey=appkey&appsecret=appsecret
请求包体:
...
参数说明:
...
SDK请求示例:
...
返回结果
...
  • 请求方式:接口有HttpGet/HttpPost两种方式。所有的请求都为HTTPS协议。
  • 请求地址:都以oapi.dingtalk.com开头。
  • 参数说明:包括字段含义、取值范围。比如HttpPost的请求包体就是request body的方式。
  • SDK请求示例:使用SDK时调用接口的Java代码示例。
  • 返回结果:钉钉所有接口的返回结果里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功。errcode为0表示调用成功,不为零表示失败,会生成对应的errmsg。开发平台文档上还有全局错误码,针对每个echo都会有一个对应解决方案的描述。
相关实践学习
日志服务之使用Nginx模式采集日志
本文介绍如何通过日志服务控制台创建Nginx模式的Logtail配置快速采集Nginx日志并进行多维度分析。
相关文章
|
16天前
|
存储 缓存 搜索推荐
Lazada淘宝详情API的价值与应用解析
在电商行业,数据是驱动业务增长的核心。Lazada作为东南亚知名电商平台,其商品详情API对电商行业影响深远。本文探讨了Lazada商品详情API的重要性,包括提供全面准确的商品信息、增强平台竞争力、促进销售转化、支持用户搜索和发现需求、数据驱动决策、竞品分析、用户行为研究及提升购物体验。文章还介绍了如何通过Lazada提供的API接口、编写代码及使用第三方工具实现实时数据获取。
39 3
|
20天前
|
监控 搜索推荐 数据挖掘
淘宝 API 接口的调用频率限制是否会因应用类型而异?
淘宝API调用频率限制依应用类型而异。电商管理类如商家后台、商品批量上传工具,调用频次较高;数据分析类如市场调研、店铺分析工具,频次较严;导购推荐类如第三方导购平台、社交媒体导购应用,依据规模与信誉设定;其他如开发者测试、个人小型应用则限制较宽松。
|
2天前
|
搜索推荐 数据挖掘 API
API接口在电商的应用及收益
本文探讨了API接口技术在电商领域的应用及其带来的收益。API接口作为连接电商平台与外部系统的桥梁,实现了高效、实时的数据交换和集成,提升了用户体验、运营效率和市场竞争力。具体应用包括库存管理、支付网关、物流跟踪、自动化业务流程、个性化推荐和精准营销等方面。通过实战案例分析,展示了亚马逊和小型电商公司如何利用API接口实现自动化管理,提高了工作效率和客户满意度。未来,API接口技术将更加注重智能化、标准化、安全性和跨界合作。
14 3
|
14天前
|
JSON 供应链 API
京东商品评价API的获取和应用
京东商品评价API是电商数据分析的重要工具,帮助开发者和商家获取商品的用户评价数据,包括评分、评论内容和购买时间等。通过分析这些数据,商家可以优化产品和服务,提升客户满意度,制定更有效的营销策略。本文介绍了获取和应用京东商品评价API的详细步骤,包括注册账号、获取权限、阅读文档和编写代码调用API。示例代码展示了如何使用Python调用API并处理响应数据。
52 2
|
14天前
|
JSON API 开发者
淘宝商品评价API的获取与应用
在数字化时代,电商平台如淘宝成为消费者购物的主要渠道。本文介绍如何使用淘宝开放平台的商品评论API获取并利用评论数据,以优化产品和服务,提升用户体验。内容涵盖API的重要性、准备工作、调用流程及代码实现,帮助开发者高效获取和分析数据。
39 3
|
15天前
|
缓存 数据挖掘 API
淘宝商品类目API的获取与应用探索
淘宝商品类目API是淘宝开放平台提供的关键服务,允许开发者获取淘宝商品的类目信息,包括根类目、子类目及属性信息。本文介绍API的获取方法、应用场景及使用技巧,帮助电商从业者和开发者更好地利用类目数据,提升商品管理、搜索推荐及数据分析等能力。
34 1
|
17天前
|
Java API 开发工具
API参考手册
【10月更文挑战第18天】API参考手册
27 2
|
19天前
|
安全 API 数据安全/隐私保护
商品详情API接口的优势分析与应用价值
在数字化时代,商品详情API接口为商家和开发者提供了实时更新、高效集成、丰富功能、安全稳定、易于扩展及提升用户体验的解决方案,助力提高运营效率、降低成本并增强市场竞争力。
|
21天前
|
安全 数据挖掘 API
快手小店详情API接口的获取与应用
在数字化时代,电商平台竞争激烈,API接口作为连接不同系统和服务的桥梁,已成为电商生态中不可或缺的一部分。本文详细介绍快手小店详情API接口的获取与应用,帮助开发者和企业提升业务效率和用户体验。涵盖API接口定义、主要应用场景、注册与认证流程、调用方法及实际应用案例,提供最佳实践建议。
56 1
|
4天前
|
JSON 安全 API
虾皮商品详情API接口:获取与应用
虾皮(Shopee)作为东南亚领先的电商平台,为商家和开发者提供了丰富的API接口服务,尤其是商品详情API接口。该接口能够快速获取商品的详细信息,包括标题、价格、库存、描述、图片、规格参数、销量、用户评价等。本文将详细介绍虾皮商品详情API接口的功能、特点、获取方法及应用场景,并给出使用时的注意事项。
24 0

热门文章

最新文章