ページネーションの変更について - Zendesk API

現在、Zendeskでは、ほぼすべてのREST APIエンドポイントでオフセットベースのページネーションを提供しています。これは、小規模なユースケース（データ量が10ページを超えないリクエストなど）では問題ありませんが、ページオフセットが大量にある大規模なユースケースでは、インフラへの負荷が指数関数的に増大します。このようにオフセットの多いリクエストは、応答時間が長くなり、パフォーマンスが低下します。これは、新しいページがリクエストされるたびに、以前のすべてのページを組み立てる作業が最初に必要になるためです。

開発者のエクスペリエンスを改善し、カスタマーのパフォーマンスを向上させるために、近々、主にページネーションをカーソルベースに移行し、大量のページオフセットのリクエストに対する制限を導入する予定です。

• カーソルベースのページネーション
• 移行の行程と変更する理由
• オフセットベースのページネーションの制限事項
• 移行を実施するタイミング

カーソルベースのページネーション

カーソルベースのページネーションは、データセット内の特定の項目にポインタを設定し、進捗状況をマークすることで機能します。基本的に、これは一種のブックマークとして機能し、後続のリクエストにカーソルを提供することで、データセット内の次の項目のバッチをリクエストすることができます。次のページを取得して項目を反復処理する代わりに、前のレスポンスで指定されたカーソルを提供します。これにより、大量のデータをより速く処理できるという利点があります。

移行の行程と変更する理由

近い将来、ZendeskはAPIの大規模な利用を促進する変更を行う予定です。この移行には、カーソルベースのページネーションを広く利用できるようにする作業が含まれます。まずはユーザー、チケット、タグの各エンドポイントから開始し、最終的には2021年中に大部分のエンドポイントを追加する予定です。

オフセットベースのページネーションは、範囲と階層を大幅に制限して引き続き提供されます。これには、オフセット数が非常に多いリクエスト（1,000ページ以上のリクエスト）に対する制限も含まれており、当社のAPIのパワーユーザーのお客様にとっては、さまざまな結果（最もポジティブな結果）がもたらされます。

カーソルベースのページネーションの利点は次のとおりです。

• ページ数が非常に多いリクエストで発生していた極端に長いタイムアウトが解消されました。これにより、リソースセット全体を1ページずつ処理する必要があるほとんどすべてのインテグレーションで、処理能力が向上します。
• カーソルベースのページネーションを使用するリクエストでは、サービスの停止やインフラへの負荷によるインシデントなど、オフセットベースのページネーションで発生していたインフラへのリスクが解消されます。
• オフセットベースのページネーションを使用してリソースセット全体をエクスポートしているインテグレーションでは、カーソルベースのページネーションへの切り替えは比較的容易で、切り替えのためにインテグレーションを準備するための作業は最小限で済みます。next_pageパラメータを取得する代わりに、インテグレーションでは新しいページにcursorパラメータを使用できます。

より詳細な比較については、こちらのページをご覧ください。

オフセットベースのページネーションの制限事項

理想的には、カーソルベースのページネーションを使用できるすべてのトラフィックを、オフセットベースのページネーションからカーソルベースへ移行したいものです。

この移行を促進するため、Zendeskは2021年9月15日より、1,000ページ（10万リソース）を超えるリクエストに対してAPI制限を適用します。1,000ページを超えるリクエストについては、アカウントからのリクエスト数が1分あたり10件に制限されます。

これにより、Zendeskのインフラに過度の負担をかけるリクエストの処理を減速することができます（停止はしません）。1,000ページを超えるリクエストが10回/分を超える速度で行われた場合は、429エラーが返され、後でリクエストを再試行する必要があります。エラーメッセージには、ユーザーが次のリクエストを送信して検索を続行できるようになるまでの時間も表示されます。

カーソルベースのページネーションを使用したリクエストには上述のような制限はなく、ページオフセットの大量のリクエストよりも高速に処理されます。

移行を実施するタイミング

できるだけ早くカーソルベースのページネーションに切り替えることをお勧めします。変更点を確認し、社内で話し合いを行ったあとで、以下の項目の内容を確認してください。

• インテグレーションでオフセットベースのページネーションを引き続き使用する場合、それらが制限内で実行されることを確認します。
• このAPIを使用して、利用可能なすべてのデータを収集したり、単に変更をレポートしたりするインテグレーションの部分をすべて確認します。これらの部分は通常、データウェアハウスの理想的な候補です。
• エンドポイントを使用して利用可能なすべてのデータをスクレイピングしている場合は、カーソルベースのページネーションに移行する作業を開始してください。
• APIを使用して日々の変更をレポートしている場合は、インクリメンタルAPIの使用を開始してください。このユースケースに関連するすべてのデータを大量に処理できるようになります。最初のエクスポートでカーソルベースのページネーションを使用し、変更をキャプチャするためにインクリメンタルAPIに切り替えると、関連データの収集に必要なコール数が大幅に減少します。
• 現在、複数のページに並行してリクエストを行っているのであれば、上記のインクリメンタルオプションを検討してください。並列化されたページネーションはZendeskのインフラへの負担が大きいため、サポートされていません。

このページをご覧になった後で、さらにご質問やご不明な点がございましたら、お客様とお客様のエンジニアリングチームやインテグレーションチームとZendeskとでご相談させていただければ幸いです。

以上につきまして、お時間を割いてご検討いただきありがとうございました。カスタマーにより良いサービスを提供するためのより優れた、より高速でスケーラブルなツールを構築するために、近い将来お客様と協力できることを楽しみにしています。