> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据分页

> DingTalk OpenAPI 支持 nextToken 与 pageSize 两种分页方式，开发者可按接口与业务场景选型，以提升获取效率并保障稳定性。

DingTalk OpenAPI 支持两种分页方式，不同接口可能采用不同的分页机制。开发者应根据具体 API 的文档说明及业务场景选择合适的分页模式，以提升数据获取效率、降低服务端压力并保障系统稳定性。

## 适用对象与权限说明

本文档适用于以下类型的应用：

* **企业内部应用**：由企业自主开发并仅供本企业使用的应用。
* **第三方企业应用**：由ISV（独立软件开发商）开发，供多个企业安装使用的应用。
* **第三方个人应用**：产品方案商开发者开发，提供给钉钉上个人用户使用的应用。

### 权限说明

调用任何 DingTalk OpenAPI 前，需确保应用已具备相应接口的调用权限。

请在钉钉开放平台控制台中完成以下操作：

1. 进入目标应用详情页。
2. 点击 **基础信息 > 凭证与基础信息**。
3. 在“权限管理”模块中添加所需 API 权限（如“读取通讯录”、“获取日程列表”等）。

参考文档：[如何申请API权限](/zh/open/development/add-api-permission)

### 认证前置条件

所有接口调用前必须获取有效的 `access_token`，用于身份认证和权限校验。

* 使用 **AppKey / AppSecret** 或 **Client ID / Client Secret** 获取 `access_token`。
* `access_token` 有效期通常为 7200 秒，建议缓存并定期刷新。
* 错误的或过期的 `access_token` 将导致接口返回 `40001` 或 `40014` 错误码。

参考文档：[如何调用API](https://open.dingtalk.com/document/development/how-to-call-apis)

## 方式一：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，兼顾网络传输效率与响应速度。