分页

X API 对返回多页结果的端点（例如时间线、搜索等）采用分页机制。每次 API 调用的响应都会包含一个 meta 对象，其中带有 result_count、previous_token 和 next_token。XDK 会基于 next_token 自动执行多次 API 调用，因此开发者只需指定所需的数据量，无需手动发起多次请求。

SDK 通过以下方式加以简化：

• 内置迭代器：使用生成器函数无缝获取多页数据。
• 显式令牌处理：在需要时传入 pagination_token，以实现灵活的手动控制。
• 最大结果数约束：遵循每次调用的 max_results（受 API 限制，例如搜索最多为 100）。

​

自动分页（推荐）

对分页响应使用 iterate() 方法，以惰性方式获取全部结果。

示例：分页搜索

from xdk import Client

client = Client(bearer_token="your_bearer_token")

# 使用自动分页搜索
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # 每页
    tweetfields=["created_at", "author_id"]  # 可选的 expansions
):
    all_posts.extend(page.data)
    print(f"已获取 {len(page.data)} 条 Post（累计：{len(all_posts)}）")

print(f"Post 总数：{len(all_posts)}")

• 迭代器会自动处理 next_token。
• 如果没有 next_token 则停止。
• 支持速率限制退避以避免出现 429 errors。

​

手动分页

如果你需要为了某些自定义逻辑（例如逐页处理）精确控制结果，你仍然可以使用 next_token，并按如下所示手动执行分页：

response = client.posts.search_recent(
    query="xdk python sdk",
    max_results=100,
    pagination_token=None  # 第一页
)

print(f"第一页：{len(response.data)} 条 Post")
next_token = response.meta.next_token

if next_token:
    next_response = client.posts.search_recent(
        query="xdk python sdk",
        max_results=100,
        pagination_token=next_token
    )
    print(f"第二页：{len(next_response.data)} 条 Post")

提示：

• 始终指定 max_results 以进行优化（默认值因端点不同而异）。
• 监控 meta.result_count 以便调试。
• 对于超大型查询，考虑使用异步迭代以避免阻塞。