介绍
分页的使用场景
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请求参数用于配置每个响应页返回的 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）是最早的。
初始请求
序列表格
| 首次请求 | 第二页 | 第三页 | 第四页 | |
|---|---|---|---|---|
| 请求参数 | - 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": "Thanks to everyone who tuned in today..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "It’s now easier to understand Tweet impact..." } ], "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": "Our developer community is full of inspiring ideas..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "Soon, we'll be releasing tools in..." } ], "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": "We know that some people who receive a large volume of replies may..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Updates to Grid embeds..." } ], "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。 |