> ## 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 は2種類のページング方式をサポートしており、インターフェースによって異なるページング機構を採用する場合があります。開発者は、各 API のドキュメント説明および業務シーンに応じて適切なページングモードを選択し、データ取得効率の向上、サーバーサイドの負荷軽減、システムの安定性確保を実現してください。

## 対象範囲と権限について

本ドキュメントは、以下のタイプのアプリに適用されます。

* **社内アプリ**：企業が自社で開発し、自社内でのみ使用するアプリ。
* **サードパーティ社内アプリ**：ISV（独立系ソフトウェア開発業者）が開発し、複数の企業がインストールして使用するアプリ。
* **サードパーティ個人アプリ**：プロダクトソリューションプロバイダーの開発者が開発し、DingTalk 上の個人ユーザー向けに提供するアプリ。

### 権限について

DingTalk OpenAPI を呼び出す前に、アプリが該当インターフェースの呼び出し権限を持っていることを確認してください。

DingTalk オープンプラットフォームのコンソールで、以下の操作を実施してください。

1. 対象アプリの詳細ページへ移動します。
2. **ベーシック情報 > 認証情報とベーシック情報** をクリックします。
3. 「権限管理」モジュールで、必要な API 権限（「連絡先の読み取り」「予定リストの取得」など）を追加します。

参考ドキュメント：[API 権限の申請方法](/ja/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` パラメータは1回のリクエストで返却される最大レコード数を制限するために使用します。レスポンス遅延を回避するため、500を超えないことを推奨します。
* ディープページングはパフォーマンス低下を引き起こす可能性があるため、時間ウィンドウのフィルタ条件と組み合わせてデータ量を削減することを推奨します。

### 推奨される利用シーン

* データ同期タスク（連絡先同期、ログ取得など）
* 大規模データセットのエクスポート
* データの完全性が重視されるシーン

## 方式二：pageSize 方式

従来のページングロジックを採用し、フロントエンドのリスト表示系インターフェース（ユーザーリスト、部門リスト、承認フォームなど）に適しています。ページ番号とページサイズによってデータの分割読み込みを制御します。

### リクエストフローについて

* 初回リクエストでは `pageNumber=1` を設定し、`pageSize` で1ページあたりのレコード数を指定します。
* リクエストごとに `pageNumber` をインクリメントし、返却データ量が `pageSize` を下回るまで継続します。これは通常、最終ページに到達したことを示します。

### 説明

* 初回呼び出しは `pageNumber=1` から開始し、ページごとにインクリメントします。
* この方式は、大量データを高頻度で取得するシーンには適しておらず、サーバーサイドのパフォーマンスに影響を与える可能性があります。

### 主要用語の説明

* `pageNumber`：現在リクエストするページ番号で、1から数え始めます。
* `pageSize`：1ページあたりに返却されるデータエントリ数で、推奨範囲は 10～200 です。

### 推奨される利用シーン

* フロントエンドのページングコントロール連携（テーブルページングなど）
* 小規模な静的データの表示
* ユーザーが能動的にトリガーするページ単位の閲覧操作

## 選定推奨とベストプラクティス

| **観点**       | **nextToken 方式**        | **pageSize 方式**           |
| ------------ | ----------------------- | ------------------------- |
| **データ整合性**   | 高（カーソルベース）              | 中（オフセットベース、書き込みの影響を受けやすい） |
| **適用データ量**   | 大規模データセット（万件以上）         | 小～中規模データセット（千件以内）         |
| **ネットワーク負荷** | 低め（maxResults を大きく設定可能） | 中程度（推奨 pageSize 上限の制約あり）  |
| **実装の複雑度**   | 中（token の状態管理が必要）       | 低（ページ番号を単純にインクリメント）       |
| **典型的なシーン**  | バックエンド同期、データ移行          | フロントエンド表示、インタラクティブクエリ     |

### 選定の推奨事項

* **増分同期系インターフェース**（イベントサブスクリプションの取得、変更ログの取得など）：**nextToken 方式** を優先的に使用し、データが繰り返さない、漏れがないことを保証します。
* **リスト表示系インターフェース**（社員リスト、承認フォームリストなど）：**pageSize 方式** を使用すると、フロントエンドのページングコンポーネントとの連携が容易です。

### ベストプラクティスまとめ

* 増分同期系インターフェースには、**方式一：nextToken 方式** の使用を推奨します。データが繰り返さない、漏れがないことを保証します。
* リスト表示系インターフェースには **方式二：pageSize 方式** を使用でき、フロントエンドのページングコントロールとの統合が容易です。
* クライアントサイドで自動リトライ機構を実装することを推奨します。`nextToken` の失効により失敗した場合は、初回リクエストに戻して再取得してください。
* 過大な `maxResults` や `pageSize` は避けてください。推奨値は 10～200 で、ネットワーク伝送効率とレスポンス速度を両立できます。