メインコンテンツへスキップ

はじめに

ページネーションは、単一のレスポンスで返せる件数を超える結果を返す X API v2 のエンドポイントで利用される機能です。その場合、data は複数の「ページ」に分割されて返されます。ページネーションとは、プログラムからすべてのページを順次リクエストして、結果のデータセット全体を取得する手法を指します。すべての API エンドポイントがページネーションをサポートしたり必要としたりするわけではありませんが、結果セットが大きい場合によく使用されます。

ページネーションのユースケース

リクエストの全結果を取得するため: 特定のリクエストとパラメータに関連するすべてのデータを取得するには、ページネーションを使用します。リクエストの max_results を超える一致結果がある場合は、ページネーションが必要です。ページネーション用トークンでリクエストを繰り返すことで、すべての結果を取得できます。レスポンスに next_token が含まれない場合は、すべての結果を取得し終えたと判断できます。ページネーションはポーリングには使用しないでください。前回のリクエスト以降の最新結果を取得するには、since_id を使ったポーリングを参照してください。 リクエスト結果を前後に移動するため: ページネーションは、レスポンスの next_tokenprevious_token を使って、リクエストの結果を前後にナビゲートするための手段を提供します。これらのトークンは、次または前の結果ページへ移動するために、次回のリクエストで pagination_token として設定できます。

ページネーション・トークンの定義

  • next_token - ページネーション対応のエンドポイントで、レスポンスの meta オブジェクト内に含まれる不透明な文字列。さらに結果が存在することを示し、次のリクエストで pagination_token パラメータに指定すると次ページの結果を取得できる。最終ページの結果には next_token は含まれない。
    • previous_token - ページネーション対応のエンドポイントで、レスポンスの meta オブジェクト内に含まれる不透明な文字列。前のページの結果が存在することを示し、次のリクエストで pagination_token パラメータに指定すると前ページの結果を取得できる。
    • pagination_token - ページネーション・リクエストで使用するパラメータ。次ページの結果には next_token の値を、前ページの結果には previous_token の値を設定する。

ページネーションの基礎

  • ページネーション対応のエンドポイントは、最初のリクエストに対して最初のページの結果を返し、追加のページがある場合は JSON レスポンスの meta オブジェクト内に next_token を含めます。すべての結果を取得するには、レスポンスに next_token が含まれなくなるまでこの処理を繰り返してください。
    • 結果は新しいものから古いものへと逆時系列で並びます。これは各ページ内でも、ページをまたいだ全体でも同様です。
      • 最初のレスポンスの最初の Post が最新です。
      • 最後のレスポンスの最後の Post が最古です。
    • max_results リクエストパラメータで、レスポンスの各ページに含める Post の件数を指定できます。max_results には既定値と上限があります。
    • すべてのページネーション実装では、レスポンスのペイロードからトークンを抽出し、後続のリクエストで使用します。
    • 状況によっては、1 ページあたりの件数が max_results 未満になることがあります。1 ページあたりの件数が常に max_results の値と一致することを前提にしないでください。
    • 完全な結果を取得するための最良の方法は、統合コードでループ処理を実装するか、X API v2 に対応した ライブラリ を利用することです。

ページネーションの例

ここでは、max_results100 に設定されており、2019年1月1日 17:00:00 UTC から12月12日 00:00:00 UTC までの間に、ユーザー ID 2244994945(@XDevelopers)によって作成された Post が約295件あるため、結果は全3ページになります。1ページ目の先頭の Post(1337498609819021312)が最新で、3ページ目の末尾の Post(1082718487011885056)が最も古いものです。

初期リクエスト

      https://api.x.com/2/users/2244994945/tweets?tweet.fields=created_at&max_results=100&start_time=2019-01-01T17:00:00Z&end_time=2020-12-12T01:00:00Z

シーケンス表

最初の要求2ページ3ページ目4ページ目
リクエストパラメーターmax_results=100tweet.fields=created_atstart_time=2019-01-01T17:00:00Zend_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=7140wmax_results=100tweet.fields=created_atstart_time=2019-01-01T17:00:00Zend_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": "グリッド埋め込みの更新…" } ], "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レスポンスから value を直接(7140w) に設定するpagination_token次回のリクエスト呼び出しに向けて設定します。すべての結果を引き続き取得するには、次を行ってください:next_tokenレスポンスから直接値(7140k9)として設定するpagination_token次回のリクエスト呼び出し用。 前のページに移動するには、次を実行します:previous_tokenレスポンスから値を直接 (77qp8) にして、次のリクエスト呼び出しの pagination_token として設定しますpagination_token次回のリクエスト呼び出しに備えて。すべての結果を引き続き取得するには、次を実行してください:next_tokenレスポンスから値を直接(71408hi)を次回のリクエストの pagination_token に設定しますpagination_token次のリクエスト呼び出しのために。前のページへ移動するには、次を取得しますprevious_tokenレスポンスから値を直接 (77qplte)として設定して、pagination_token次回のリクエスト呼び出しに備えて。なお、~は存在しないことにご留意くださいnext_token、これはすべての結果を受け取り終えたことを示します。 前のページへ移動するには、レスポンスから previous_token の値(77qpw8l)をそのまま取得し、次のリクエスト呼び出しの pagination_token に設定します。previous_tokenレスポンスから値を直接 (77qpw8l) を取得し、次回のリクエストで pagination_token に設定しますpagination_token次回のリクエスト呼び出しのために。