開発ガイド対象範囲と権限について
本ドキュメントは、以下のタイプのアプリに適用されます。- 社内アプリ：企業が自社で開発し、自社内でのみ使用するアプリ。
- サードパーティ社内アプリ：ISV（独立系ソフトウェア開発業者）が開発し、複数の企業がインストールして使用するアプリ。
- サードパーティ個人アプリ：プロダクトソリューションプロバイダーの開発者が開発し、DingTalk 上の個人ユーザー向けに提供するアプリ。
権限について
DingTalk OpenAPI を呼び出す前に、アプリが該当インターフェースの呼び出し権限を持っていることを確認してください。 DingTalk オープンプラットフォームのコンソールで、以下の操作を実施してください。- 対象アプリの詳細ページへ移動します。
- ベーシック情報 > 認証情報とベーシック情報 をクリックします。
- 「権限管理」モジュールで、必要な 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パラメータは1回のリクエストで返却される最大レコード数を制限するために使用します。レスポンス遅延を回避するため、500を超えないことを推奨します。- ディープページングはパフォーマンス低下を引き起こす可能性があるため、時間ウィンドウのフィルタ条件と組み合わせてデータ量を削減することを推奨します。
推奨される利用シーン
- データ同期タスク（連絡先同期、ログ取得など）
- 大規模データセットのエクスポート
- データの完全性が重視されるシーン
方式二：pageSize 方式
従来のページングロジックを採用し、フロントエンドのリスト表示系インターフェース（ユーザーリスト、部門リスト、承認フォームなど）に適しています。ページ番号とページサイズによってデータの分割読み込みを制御します。リクエストフローについて
- 初回リクエストでは
pageNumber=1を設定し、pageSizeで1ページあたりのレコード数を指定します。 - リクエストごとに
pageNumberをインクリメントし、返却データ量がpageSizeを下回るまで継続します。これは通常、最終ページに到達したことを示します。
説明
- 初回呼び出しは
pageNumber=1から開始し、ページごとにインクリメントします。 - この方式は、大量データを高頻度で取得するシーンには適しておらず、サーバーサイドのパフォーマンスに影響を与える可能性があります。
主要用語の説明
pageNumber：現在リクエストするページ番号で、1から数え始めます。pageSize：1ページあたりに返却されるデータエントリ数で、推奨範囲は 10～200 です。
推奨される利用シーン
- フロントエンドのページングコントロール連携（テーブルページングなど）
- 小規模な静的データの表示
- ユーザーが能動的にトリガーするページ単位の閲覧操作
選定推奨とベストプラクティス
選定の推奨事項
- 増分同期系インターフェース（イベントサブスクリプションの取得、変更ログの取得など）：nextToken 方式 を優先的に使用し、データが繰り返さない、漏れがないことを保証します。
- リスト表示系インターフェース（社員リスト、承認フォームリストなど）：pageSize 方式 を使用すると、フロントエンドのページングコンポーネントとの連携が容易です。
ベストプラクティスまとめ
- 増分同期系インターフェースには、方式一：nextToken 方式 の使用を推奨します。データが繰り返さない、漏れがないことを保証します。
- リスト表示系インターフェースには 方式二：pageSize 方式 を使用でき、フロントエンドのページングコントロールとの統合が容易です。
- クライアントサイドで自動リトライ機構を実装することを推奨します。
nextTokenの失効により失敗した場合は、初回リクエストに戻して再取得してください。 - 過大な
maxResultsやpageSizeは避けてください。推奨値は 10～200 で、ネットワーク伝送効率とレスポンス速度を両立できます。