API 中的分页是如何工作的？

Scrapeless Agent Browser 使应用程序能够在收集结果需要浏览器状态或 JavaScript 执行时，与分页的 Web 界面进行交互。

API 中的分页是如何工作的？

API 分页将一个集合划分为结果窗口，并为客户端提供请求下一个窗口的方式。API 定义了排序方式、页面大小策略、续传机制以及完成信号。客户端遵循该约定，直到集合结束或达到其自身允许的集合边界为止。

分页限制了与每个请求相关的工作量和响应大小。它也带来了一个一致性问题：当客户端在遍历集合时，如果记录发生了变化，会发生什么？一个完整的分页设计既要解释客户端如何向前翻页，也要说明所得记录代表的是集合的哪个版本。

页码和偏移量是如何工作的？

页码分页标识的是一个带编号的窗口，而偏移量分页标识的是在返回一个有限结果集之前要跳过多少个按顺序排列的结果。页码在内部可能会被转换为偏移量，但这种映射关系和编号基准属于 API 合同的一部分。不要假设不同服务中第一页总是由相同的数字表示。

这些模式对于需要直接导航到可见页面的界面来说很方便。当在遍历过程中集合发生变化时，它们就会变得不太可预测。如果在下一个偏移量之前插入了一个项目，接下来的窗口可能会与前一个窗口重叠。如果移除了一个项目，后面的窗口可能会跳过某个项目。

排序必须是明确的。 LIMIT 和 OFFSET 的数据库行为 说明了为什么在没有唯一排序的情况下进行分页会产生不可预测的子集。仅按不唯一的创建时间排序仍可能留下未解决的并列项。当数据模型允许时，稳定的次级标识可以用来解决这些并列。

较大的偏移量也可能要求后端处理那些不会被返回的行。实际成本取决于索引、过滤器和具体实现。不要仅仅因为每个响应包含相同的最大记录数就声称页码跳转具有恒定成本。

Cursor 和 Keyset 分页是如何工作的？

游标分页会返回一个续传值，客户端使用该值来请求下一个窗口。键集分页是一种实现技术，它基于有序值（例如最后接受的时间戳和标识符）进行相对推进。API 可以对外暴露一个不透明的游标，同时在之后更改其内部实现。

游标可以编码一个位置、一个快照引用或服务器端状态。客户端不应通过解码来推断其含义。不透明值是一种接口边界，其看似可读并不意味着其内部字段构成受支持的公共约定。

这 GraphQL 连接分页模式 描述了 edges、cursors 和页面信息。作为一种语言，GraphQL 并不强制每个 API 都采用这种模式。客户端仍然需要实际的模式以及特定服务器的约束条件。

键集遍历减少了由偏移量引起的一些移动问题，但它并不是自动的冻结快照。如果排序字段发生变化，某个条目可能会跨越遍历边界移动。如果在边界之后插入了新条目，它们可能会位于当前遍历之外。请明确说明服务器实际提供的一致性保证。

下一步链接和令牌应如何被跟随？

按照 API 文档中关于 location 和 request 的规则继续进行。响应可以在其正文中携带一个令牌、在元数据中提供下一个 URL，或者在 HTTP 头中提供一个带类型的链接。 网页链接模型 定义了带类型的链接及其关系语义，但客户端仍然必须理解该 API 的分页约定。

在需要时保留过滤器、排序和其他上下文。为一个集合生成的令牌不应与不相关的过滤器组合。如果某个服务允许在遍历过程中更改页面大小，则使用该文档许可；否则请保持请求的一致性。

在将凭证附加到下一个 URL 之前验证目标。返回的链接是数据，而不是将机密转发到其所指示任何主机的许可。使用集成所定义的允许服务来源和身份验证范围。避免通过连接未转义的光标文本来构造 URL。

将继续点与其上下文一起检查点保存。没有集合、过滤条件、排序规则和可接受输出边界的已存储令牌，在后续使用时很难被正确处理。一些游标会过期，因此仅靠持久化并不能保证可恢复性。

客户端如何知道集合已完成？

当满足 API 文档中规定的结束信号时，客户端就知道集合已完成。该信号可能是缺少 next 链接、空的 next 令牌，或显式的页面信息标志。只有在契约声明其足够时，短页面或空数组才被视为足够。

AIP 分页指南 提供了一个具体示例：响应中返回的结果数量可以少于请求的数量，甚至可以没有任何结果，但仍然返回一个续传令牌。此行为并非普遍适用，但它推翻了“空页面总是意味着遍历已结束”这一假设。

分别跟踪终止原因。源结束、客户端记录上限、耗时限制、无效令牌和访问失败描述的是不同的结果。受上限约束的运行是一个有界采样或部分收集。仅仅因为循环正常停止，它不应被标记为已完成。

防止重复的续写。如果一次响应返回相同的标记且没有实质性进展，客户端应在未解决状态下停止，而不是无限循环。稳定的记录标识符有助于检测重叠，而页面指纹有助于识别重复的响应。二者都不能单独证明已完全覆盖。

一个正确的遍历记录保留了什么？

遍历记录保留了足够的上下文，以说明遍历了哪个集合以及接受了哪些输出。在一个示例性的活动导出设计中，存储集合标识、过滤条件、排序顺序、已接受的记录键，以及与上一次持久化输出边界关联的续传标记。

在推进持久进度标记之前先提交记录。否则，进程可能会将进度记录在那些它从未保存过的记录之后。对于无法在同一事务中同时涵盖输出和检查点存储的情况，需要定义系统如何检测并弥合这一差距。

按正确的标识进行去重。对于最新状态的导出，资源标识符可能就足够了。事件流可能需要事件标识。历史导出可能需要同时包含资源和版本。从带版本历史中删除重复的资源标识符，可能会移除合法的变更。

记录服务器的一致性承诺。如果服务器实现了快照分页，它可以提供一个稳定的视图。实时游标遍历可能表示一个不断变化的集合。使用方应了解导出的是快照、有界遍历，还是持续变化的流。

API 分页与网站分页有何关系？

网站分页在数据序列之上添加了一层交互。下一页按钮可以请求一个 API 游标、替换页面、追加卡片，或仅更新部分 DOM。可见的分页标签并不能揭示完整的连续性约定。

Scrapeless 代理浏览器 在工作流需要这些浏览器交互时是相关的。 云端浏览器功能 支持导航动态页面；你的采集器仍然拥有身份、停止规则和完整性报告的控制权。

The 网页抓取分页模式 显示常见的接口形式。当适用时，直接使用获得授权且有文档记录的 API。仅因为在浏览器开发者工具中可见某个请求，并不意味着就自动获得许可，可以在预期界面之外使用它。

从支持的限制和实际处理需求中选择页面大小。较大的页面可以减少请求数量，但会增加响应大小并降低检查点的粒度。 无爬取定价 当涉及浏览器集合时，并评估源 API 的独立配额和访问策略。

结论

一个可靠的 API 分页客户端会遵守连续性约定，保留稳定的排序上下文，并记录遍历结束的原因。在将导出标记为完成之前，需要确定它代表的是哪个集合版本，以及有哪些证据可以排除被遗漏的窗口。