目前,Zendesk 为其当前几乎所有的 REST API 端点提供了基于偏移量的分页。虽然这对于大多数小规模用例(例如,数据价值不超过 10 页的请求)来说都很好,但当以高页面偏移量大规模使用时,它会给基础设施带来指数级压力。这些高偏移量请求会导致响应时间长和性能下降,因为对于每个请求的新页面,仍然需要先进行组装所有以前页面的工作。
为了向我们的客户提供更好的开发者体验和更快的性能,我们很快将主要迁移到基于光标的分页,并对非常高的页面偏移请求实施限制。
什么是基于光标的分页?
基于光标的分页通过使用指向数据集中特定项目的指针来标记您的进度。从本质上讲,这就像一种书签,使您可以通过在后续请求上提供光标来请求数据集中的下一批项目。您提供上一个响应中给出的光标,而不是让下一页遍历项目。这样做的好处是可以更快地获得大量结果。
我们如何以及为什么进行这些更改?
在不久的将来,Zendesk 将进行更改,以提高大规模 API 的使用。这包括广泛使用基于光标的分页,从我们的 用户、工单和工单标签 端点,直到 2021 年最终添加我们的大多数端点。
基于偏移量的分页将继续提供,但范围和深度都非常有限。这包括限制非常高的偏移量请求(超过 1,000 个页面的请求),这将对我们 API 的重度消费者产生各种结果——最积极的结果。
基于光标的分页的好处包括:
- 请求将不再受到页码非常高的请求时出现的极高超时。这将为几乎所有需要逐页查看整个资源集的整合带来更快的性能。
- 使用基于光标的分页请求将不再给基础设施带来基于页面偏移量高的分页所带来的风险,从服务中断到由于基础设施压力导致的事务。
- 对于使用基于偏移量的分页来导出整个资源集的整合,切换到基于光标的分页将相对容易,只需最少的返工即可为切换准备整合。而不是抓取 next_page 参数,则整合可以将 光标 参数用于新页面。
请参阅 此页面 了解更详细的比较。
基于偏移量的分页限制
Zendesk 希望所有可使用基于光标的分页的流量不再使用基于偏移的分页。
为鼓励这种转变,自 2021 年 9 月 15 日起,Zendesk 将对超过 1,000 页 (100,000 资源)。对于所有超过 1,000 页的请求,帐户将限于 每分钟 10 个请求。
这将减慢(但不会停止)对我们的基础架构造成过度负担的请求。如果请求超过 1,000 个页面,速度超过每分钟 10 次,则会给出 429 响应,并且需要稍后重试请求。错误消息还将说明用户提交下一个请求并继续搜索之前的剩余时间。
使用基于光标的分页发出的请求将没有类似的限制,并且比高页面偏移量请求执行得更快。
如何开始实施这些更改?
我们建议您计划切换到基于光标的分页 尽快。请参阅 使用基于光标的分页对列表进行分页。在您查看这些更改并进行内部讨论后,请您审阅以下项目:
- 确保将继续使用基于偏移量的分页的整合在我们的 限制范围内使用。
- 审阅整合中专门使用 API 收集所有可用数据或仅报告更改的任何部分。这些通常是数据仓库的理想选择。
- 如果使用端点抓取所有可用数据,请开始切换到基于光标的分页。
- 如果使用 API 报告每日更改,请开始使用我们的 增量 API,这样就可以有大量与此用例相关的所有数据。使用基于光标的分页进行初始导出,然后切换到增量 API 以捕获更改,将大大减少收集相关数据所需的调用。
- 如果当前并行请求多个页面,请考虑上述增量选项,因为不支持并行分页,并且对我们的基础架构非常繁重。
支持哪些端点?
有关支持光标分页分页的端点列表,请参阅公告中关于基于偏移量的分页限制的 具有 CBP 功能 的端点。
如果您在审阅此内容后有任何其他问题或疑问,我们很乐于与您以及您的工程和整合团队讨论。
感谢您阅读这些要点。我们期待在不久的将来与您合作,打造更好、更快、更具可扩展性的工具,更好地为您的客户服务。
翻译免责声明:本文章使用自动翻译软件翻译,以便您了解基本内容。 我们已采取合理措施提供准确翻译,但不保证翻译准确性
如对翻译准确性有任何疑问,请以文章的英语版本为准。