はじめに
ページネーションのユースケース
max_results を超える場合は、ページネーションが必要です。ページネーション用トークンを用いたループ処理により、すべての結果を取得できます。レスポンスに next_token が含まれない場合は、すべての結果のページングが完了したと見なせます。ページネーションはポーリング目的には使用しないでください。前回のリクエスト以降の最新結果を取得するには、since_id を用いたポーリングの説明を参照してください。
リクエストの結果を順にたどるため: ページネーションは、レスポンスの next_token および previous_token の値を使用して、リクエスト結果を前後に移動するための手段を提供します。これらのトークンは、次または前のページの結果に移動するために、次のリクエストの pagination_token として設定できます。
ページネーション用トークンの定義
next_token- ページネーションをサポートする endpoint のレスポンス内の meta オブジェクトに含まれる不透明な文字列。追加の結果が存在することを示し、次のリクエストで結果の次ページを取得するためにpagination_tokenパラメータとして使用できる。結果の最終ページにはnext_tokenは含まれない。previous_token- ページネーションをサポートする endpoint のレスポンス内の meta オブジェクトに含まれる不透明な文字列。結果の前のページが存在することを示し、次のリクエストで前のページを取得するためにpagination_tokenパラメータとして指定できる。pagination_token- ページネーション用のリクエストで使用するパラメータ。結果の次ページを取得する場合はnext_tokenの値を、前のページを取得する場合はprevious_tokenの値を設定する。
ページネーションの基本
- ページネーションを使用するendpointは、最初のリクエストに対して最初の結果ページを返し、追加の結果ページがある場合はJSONレスポンスのmetaオブジェクト内に
next_tokenを含めます。すべての結果を取得するには、レスポンスにnext_tokenが含まれなくなるまでこの処理を繰り返してください。- 結果は新しいものから古いものへと並ぶ逆時系列で返されます。これは個々のページ内だけでなく、複数ページにまたがる場合でも同様です。
- 最初のレスポンスの先頭のPostが最も新しいものです。
- 最後のレスポンスの末尾のPostが最も古いものです。
- リクエストパラメータ
max_resultsにより、レスポンス1ページあたりに返されるPostsの数を指定できます。max_resultsには既定値と上限があります。 - どのページネーション実装でも、レスポンスのペイロードからトークンをパースし、後続のリクエストで使用します。
- 状況によっては、1ページあたりの結果数が
max_results未満になることがあります。1ページあたりの結果数が常にmax_resultsパラメータの値と一致することを前提にしないでください。 - 完全な結果を取得するための最適な方法は、統合コード内でループ処理を用いるか、X API v2をサポートするライブラリを使用することです。
- 結果は新しいものから古いものへと並ぶ逆時系列で返されます。これは個々のページ内だけでなく、複数ページにまたがる場合でも同様です。
ページネーションの例
max_results が 100 に設定されており、2019年1月1日 17:00:00 UTC から12月12日 00:00:00 UTC までの間にユーザー ID 2244994945（@XDevelopers）によって作成された Posts が約295件あるため、結果は3ページに分かれています。1ページ目の最初の Post（1337498609819021312）が最新で、3ページ目の最後の Post（1082718487011885056）が最も古いものです。
初期リクエスト
シーケンステーブル
| 最初のリクエスト | 2ページ目 | 3ページ目 | 4ページ目 | |
|---|---|---|---|---|
| リクエストパラメータ | - max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z | - max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140w | - max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140k9 | - max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 71408hi |
| レスポンス | json { "data": [ { "created_at": "2020-12-11T20:44:52.000Z", "id": "1337498609819021312", "text": "本日ご視聴いただいた皆さま、ありがとうございました..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "Tweet の影響をこれまで以上に理解しやすくなりました..." } ], "meta": { "oldest_id": "1258085245091368960", "newest_id": "1337498609819021312", "result_count": 100, "next_token": "7140w" } } | json { "data": [ { "created_at": "2020-04-29T17:01:44.000Z", "id": "1255542797765013504", "text": "私たちの開発者コミュニティは、刺激的なアイデアであふれています..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "まもなく、ツールをリリースします..." } ], "meta": { "oldest_id": "1197549579035496449", "newest_id": "1255542797765013504", "result_count": 100, "next_token": "7140k9", "previous_token": "77qp8" } } | json { "data": [ { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549578418941952", "text": "大量の返信を受け取る一部の方々が直面する課題を私たちは理解しています..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Grid 埋め込みのアップデート..." } ], "meta": { "oldest_id": "1082718487011885056", "newest_id": "1197549578418941952", "result_count": 95, "next_token": "71408hi", "previous_token": "77qplte" } } | json { "meta": { "result_count": 0, "previous_token": "77qpw8l" } } |
| 次のリクエストで取るべきアクション | 次のページを取得するには、レスポンスの next_token の値（7140w）をそのまま取得し、次回のリクエストの pagination_token に設定します。 | すべての結果を継続取得するには、レスポンスの next_token の値（7140k9）をそのまま取得し、次回のリクエストの pagination_token に設定します。前のページへ移動するには、レスポンスの previous_token の値（77qp8）をそのまま取得し、次回のリクエストの pagination_token に設定します。 | すべての結果を継続取得するには、レスポンスの next_token の値（71408hi）をそのまま取得し、次回のリクエストの pagination_token に設定します。前のページへ移動するには、レスポンスの previous_token の値（77qplte）をそのまま取得し、次回のリクエストの pagination_token に設定します。 | next_token がないことに注意してください。これは、すべての結果を受信済みであることを示します。前のページへ移動するには、レスポンスの previous_token の値（77qpw8l）をそのまま取得し、次回のリクエストの pagination_token に設定します。 |