如何调用新版服务端API

钉钉提供了不同规范的API，DingTalk OpenAPI是全新一代的钉钉API，以资源为中心进行开放，提供更加简单、安全、高效的使用方式。调用钉钉新版规范服务端API前，需要先申请接口权限并获取API调用凭证。本文提供了API调用示例，供开发者参考。

重要

如果开发者需调用新版服务端，可以查看本文调用流程，流程和如何调用服务端API的流程基本相同。

文档格式约定

每个接口文档会按照如下格式提供信息：

请求：
    权限
    请求方法
    Header参数
    Path参数
    Query参数
    Body参数
响应：
    返回参数
    返回示例
    错误码

调用 API 的详细入参说明，参数使用风格遵循 RESTFul，请注意不同参数在调用时的位置。

{HTTP method} https://api.dingtalk.com/{version}/{resource}?{query-parameters}

请求方法：{HTTP method}，API请求中使用的HTTP方法。

Header参数：主要包含调用 API 所需要使用的访问凭证（access_token）以及 HTTP Content-Type。

版本：{version}，正在使用的API版本。

Path参数：{resource}，正在使用的资源，例如user, event等。这部分参数需要放置在 URL 中，在文档中一般以{ }表示。

Query参数：{query-parameters}，这部分参数需要在 URL 后使用?进行连接，多个查询参数以&分割。

Body参数：这部分参数需要放在 HTTP 请求的 Body 中，一般为 JSON 格式。

状态码：表示成功或失败的HTTP状态码。

响应消息：请求获取的数据或操作结果。某些操作，响应消息可能为空。

HTTP方法

DingTalk OpenAPI通过请求中的HTTP方法来确定请求正在执行的操作。DingTalk OpenAPI支持以下HTTP方法：

方法	说明
GET	从资源中读取数据。
POST	创建新的资源或执行某个操作。
PUT	替换为新资源。
DELETE	删除资源。

API版本

DingTalk OpenAPI版本采用大版本号+小版本号组合的形式，例如1.0、2.1。

小版本号升级（例如从1.0升级到1.1）意味着发布了不向后兼容的API升级。

大版本号升级时（例如从1.0升级到2.0），上一个版本的API将在一段时间后停止支持。SDK和文档将取消上一个大版本API的入口。

重要

当大版本发布后，开发者需尽快升级至最新版本以便获得更好的支持。

SDK版本

SDK版本采用大版本+小版本+补丁版本的形式表示，例如1.0.0、2.0.11。

大版本和小版本号与SDK中调用的API保持一致。

对于补丁版本号，当API发布了可兼容性变更时，会相应升级SDK补丁版本号。

请参考安装SDK下载DingTalk OpenAPI SDK。

资源

资源是你要操作的一个实体。每个资源都有自己的属性定义，例如一个user资源可包含name、id、department等属性。

在操作不同的资源时，你需要根据具体的接口要求，申请对应的操作权限。

接口调用流程

如下图所示，在调用钉钉服务端接口前，您需要完成以下准备工作：

创建一个钉钉应用，获取AppKey和AppSecret等，详情请参考应用类型介绍。

企业内部应用请参考开发流程。

添加接口调用权限。

应用创建后默认只开放登录和消息通知接口的调用权限。

其他的接口权限，您需要根据开发场景，进行添加。详情请参考添加接口调用权限。

获取企业内部应用的访问凭证access_token。

根据第1步获取的AppKey和AppSecret，调用接口获取企业内部应用的accessToken，通过access_token来鉴权调用者身份。

查看各产品模块的文档，调用服务端接口。如通讯录管理，OA审批概述等。

调试工具

钉钉开放平台提供了API Explorer和SDK方便开发者调用服务端API。

API Explorer调试工具：

API Explorer是可视化在线API调用工具，可实时查看API请求和返回结果。

SDK 下载

钉钉开放平台提供了 SDK，方便开发者调用服务端 API。

新版服务端API提供了Java、Node.js、PHP、Go、C#和Python 6种编程语言的SDK，下载新版服务端 SDK。

新版服务端 API 调用示例

以开发企业内部应用，调用通讯录相关API示例，调用流程如下。

步骤一：成为钉钉开发者。

步骤二：登录钉钉开发者后台，创建企业内部应用，详见创建应用。

步骤三：获取应用凭证，Clinet ID（原Appkey）和 Client Secret（原AppSecret）。

步骤四：单击开发配置 > 权限管理，搜索通讯录部门成员读权限，并单击申请权限。

步骤五：开发者可以先通过调试工具体验API。以根据步骤三获取的AppKey和AppSecret，调用获取企业内部应用的accessToken为例。

说明

此步骤，非必须。开发者可以根据实际情况选择是否使用调试工具。

步骤六：点击下载新版服务端 SDK。

步骤七：根据步骤三获取的AppKey和AppSecret，调用获取企业内部应用的accessToken。

说明

为便于开发者调用，获取企业内部应用accessToken接口同时提供了2个版本。开发者可以根据实际情况选择以下任一版本使用。

服务端API，获取企业内部应用的access_token。

新版规范服务端API，获取企业内部应用的accessToken。

以选择新版服务端API版本为例，调用获取企业内部应用的accessToken，token为ba4ff8c485593xxxxxxxxxdb66a84076c3。

步骤八：调用创建钉钉待办任务接口，新增钉钉待办任务。

接口请求参数如下：

POST /v1.0/todo/users/cHtUYN1bxxxx/tasks?operatorId=cHtUYN1bxxxx HTTP/1.1
Host:api.dingtalk.com
x-acs-dingtalk-access-token:String
Content-Type:application/json

{
  "sourceId" : "dingtalk",
  "subject" : "接入钉钉待办",
  "creatorId" : "cHtUYN1bxxxx",
  "description" : "待办描述",
  "dueTime" : 1638356272000L,
  "executorIds" : [ "xW5ItJxxxx" ],
  "detailUrl" : {
    "appUrl" : "https://www.dingtalk.com",
    "pcUrl" : "https://www.dingtalk.com"
  },
  "isOnlyShowExecutor" : false,
  "priority" : 40,
  "notifyConfigs" : {
    "dingNotify" : "1"
  }
}

接口返回结果如下：

 "body":
      {
        "bizTag":"todo_open_dingxxxxx",
        "createdTime":1638263305464,
        "creatorId":"cHtUYN1bxxxx",
        "description":"待办描述",
        "detailUrl":
            {
              "appUrl":"https://www.dingtalk.com",
              "pcUrl":"https://www.dingtalk.com"
             },
        "done":false,
        "dueTime":1638356272000,
        "executorIds":["xW5ItJxxxx"],
        "finishTime":0,
        "id":"task86e68644789bd6xxxxxxx",
        "isOnlyShowExecutor":false,
        "modifiedTime":1638263305464,
        "modifierId":"cHtUYN1bxxxx",
        "participantIds":["cHtUYN1bxxxx","xW5ItJxxxx"],
        "priority":40,
        "requestId":"4244C7DD-870A-7850-8E38-xxxxxx",
        "source":"todo_open_dingzuws6w3mi5svgwky",
        "sourceId":"dingtalk",
        "startTime":0,
        "subject":"接入钉钉待办"
}

如何调用新版服务端API

文档格式约定#

HTTP方法#

API版本#

SDK版本#

资源#

接口调用流程#

调试工具#

SDK 下载#

新版服务端 API 调用示例#