适用对象与权限说明
本文档适用于以下类型的应用：- 企业内部应用：由企业自主开发并仅供本企业使用的应用。
- 第三方企业应用：由ISV（独立软件开发商）开发，供多个企业安装使用的应用。
- 第三方个人应用：产品方案商开发者开发，提供给钉钉上个人用户使用的应用。
权限说明
调用任何 DingTalk OpenAPI 前，需确保应用已具备相应接口的调用权限。 请在钉钉开放平台控制台中完成以下操作：- 进入目标应用详情页。
- 点击 基础信息 > 凭证与基础信息。
- 在“权限管理”模块中添加所需 API 权限（如“读取通讯录”、“获取日程列表”等）。
认证前置条件
所有接口调用前必须获取有效的access_token，用于身份认证和权限校验。
- 使用 AppKey / AppSecret 或 Client ID / Client Secret 获取
access_token。 access_token有效期通常为 7200 秒，建议缓存并定期刷新。- 错误的或过期的
access_token将导致接口返回40001或40014错误码。
方式一：nextToken方式
通过nextToken 设置查询凭证实现连续数据读取。首次请求无需传入nextToken，后续请求需将上次接口响应中的nextToken值复制到本次请求中，即可继续获取后续数据。
请求流程说明
- 首次请求无需传入
nextToken，服务端将返回第一批数据及一个nextToken值。 - 后续请求需将上一次响应中的
nextToken值填入查询参数中，用于获取下一页数据。 - 当响应中不再返回
nextToken时，表示已读取全部数据。
GET /v1.0/edu/grades/{identifier}/classes?nextToken=bGFzdD0xMTExMExMSZdGhlcnBhcmFtPXh4eCYuLi4u&maxResults=20
关键术语说明
nextToken：服务端生成的不透明字符串凭证，标识当前查询的上下文位置，客户端仅需透传，不可解析或修改。maxResults：客户端建议的最大返回条目数，非精确值；实际返回数量可能小于该值，受服务端限制或剩余数据量影响。
说明
maxResults参数用于限制单次返回的最大记录数，建议不要超过500以避免响应延迟。- 深度翻页可能导致性能下降，建议结合时间窗口过滤条件减少数据量。
推荐使用场景
- 数据同步任务（如通讯录同步、日志拉取）
- 大数据集导出
- 对数据完整性要求高的场景
方式二：pageSize方式
采用传统分页逻辑，适用于前端列表展示类接口（如用户列表、部门列表、审批单据等）。通过页码和每页大小控制数据分段加载。请求流程说明
- 首次请求设置
pageNumber=1，pageSize指定每页记录数。 - 每次请求递增
pageNumber，直至返回数据量小于pageSize，通常表示已达末页。
说明
- 首次调用从
pageNumber=1开始，逐页递增。 - 该方式不适合高频拉取大量数据的场景，可能影响服务端性能。
关键术语说明
pageNumber：当前请求的页码，从 1 开始计数。pageSize：每页返回的数据条目数量，建议范围为 10～200。
推荐使用场景
- 前端分页控件集成（如表格分页）
- 小规模静态数据展示
- 用户主动触发的按页浏览操作
推荐选型与最佳实践
| 维度 | nextToken 方式 | pageSize 方式 |
|---|---|---|
| 数据一致性 | 高（基于游标） | 中（基于偏移，易受写入影响） |
| 适用数据量 | 大数据集（万级以上） | 小到中等数据集（千级以内） |
| 网络开销 | 较低（可设较大 maxResults） | 中等（受限于推荐 pageSize 上限） |
| 实现复杂度 | 中（需维护 token 状态） | 低（简单递增页码） |
| 典型场景 | 后台同步、数据迁移 | 前端展示、交互式查询 |
选型建议
- 增量同步类接口（如事件订阅拉取、变更日志获取）：优先使用 nextToken 方式，保证数据不重复、不遗漏。
- 列表展示类接口（如员工列表、审批单列表）：可使用 pageSize 方式，便于与前端分页组件对接。
最佳实践总结
- 增量同步类接口，推荐使用 方式一：nextToken 方式，保证数据不重复、不遗漏。
- 列表展示类接口可使用 方式二：pageSize方式，便于前端分页控件集成。
- 建议在客户端实现自动重试机制：若因
nextToken失效导致失败，应回退至首次请求重新拉取。 - 避免过大的
maxResults或pageSize，推荐值为10~200，兼顾网络传输效率与响应速度。