跳转到主要内容

​
介绍

当 X API v2 的某些端点需要返回的结果多于单个响应所能容纳时，会使用分页。此时，data 会以一系列“页面”的形式返回。分页指的是通过编程方式请求所有页面，以获取完整的结果数据集。并非所有 API 端点都支持或需要分页，但在结果集较大时常用。

​
分页的用例

检索某个请求的全部结果： 应使用分页来获取与特定请求及其参数相关的所有数据。当匹配结果数量超过该请求的 max_results 时，需要使用分页。通过携带分页令牌循环发送请求，可以检索全部结果。当返回的响应中不再包含 next_token 值时，可视为已遍历完所有结果。不要将分页用于轮询目的。若要获取自上次请求以来的最新结果，请参阅使用 since_id 的轮询方法。 遍历某个请求的结果： 分页通过响应中的 next_token 和 previous_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 有默认值和最大值。
    • 任何分页实现都需要从响应负载中解析令牌，以便用于后续请求。
    • 在某些情况下，每页返回的数量可能少于 max_results。不要假设每页结果总是等于 max_results 参数值。
    • 获取完整结果的最佳分页方式是：在集成代码中使用循环逻辑，或使用支持 X API v2 的库。

​
分页示例

在此示例中，由于将 max_results 设置为 100，且在 2019 年 1 月 1 日 17:00:00（UTC）至 12 月 12 日 00:00:00（UTC）期间，用户 ID 2244994945（@XDevelopers）共创建了约 295 条 Post，因此会有三页结果。第一页的第一条 Post（1337498609819021312）是最新的，第三页最后一条 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

​
序列表

首次请求第二页第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": "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直接从响应中读取 value（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 值，并将其设置为下一次请求的 pagination_token。previous_token直接从响应中读取该值（77qpw8l）并将其设为pagination_token用于下一次请求。