API 调用频率限制

给第三方开发者的使用指导

为了尽可能保证印象笔记平台服务的性能，我们对第三方应用和服务作了 API 调用的API 调用频率限制。本文档概述了API 调用频率限制、超出限制时会采取的措施以及应当如何处理超出请求次数上限后返回的错误。

API 调用频率限制概述

第三方应用是用它们的 API Key 来标识的，在沙箱环境和生产环境中都是这样。用户请求会通过它们的认证凭据来标识。对印象笔记 API 的请求限制是按照某个时间间隔内使用某个 API Key 的某个用户来计算的。这意味着 API 限制了第三方应用在一小时内为每个独立的用户可调用 API 的次数。

例如：假设 Bob 使用一个叫 Fake 的应用，它整合了印象笔记的服务。并且 Fake 这款应用还调用印象笔记 API 对 Bob 的帐户发出一系列的请求。如果这些 API 请求的次数超出了印象笔记设定的一小时内的请求次数上限，那么任何后续时间窗口内的 API 请求都会导致印象笔记 API 抛出异常（我们马上会详细说明这一点）。

这并不代表 Bob 就不能访问他自己的印象笔记的数据了——只是 Fake 这款应用在这一小时内会被禁止发出请求，直到限制数被重置。所有 Bob 使用的其他应用或服务仍然能够不受影响地访问他印象笔记的数据（除非它们也超出了API 调用频率限制）。

限制 API 调用频率的目的

正如前面提到的，我们的主要目的是：当开发者和用户要访问他们自己印象笔记帐户的数据时，能为他们提供一个可迅速响应的接口。因为每个 API 请求都会带来计算开销，将开销尽可能减少到最小程度对印象笔记和开发者都是有好处的。

限制 API 调用频率也会鼓励开发者在构建应用时节省要调用的 API 请求。

限制 API 调用频率的措施与处理方法

API 调用频率限制会被应用在所有的授权 API 调用上——即那些携带有 authenticationToken 参数的 API 调用。如果在超出API 调用频率限制之后又发出请求，那么就会抛出错误代码为 RATE_LIMIT_REACHED 的 EDAMSystemException 异常。另外，EDAMSystemException 实例的 rateLimitDuration 属性会被赋值。这个值的单位是秒，代表距发出下次 API 请求必须经过的时间间隔。

处理好上述情况是非常重要的。实际情况中，用户大多数情况下并不熟悉 API 调用频率限制这一概念，而且也不会理解为什么他们的请求会不成功。如果此次失败的请求涉及到改变用户帐户中的某些东西（例如 NoteStore.createNote），那么推荐的做法是：应用程序将这些请求存至队列中，等过了 rateLimitDuration 秒之后，再次发送请求。

沙箱环境与生产环境

唯一的区别是：如果连接到沙箱环境的应用超出了允许的 API 请求数目，该应用只需要等待最多15秒就可以重试被拒绝的请求。它会收到与在生产环境中一样的异常，并且 EDAMUserException 实例的 rateLimitDuration 属性会被设置为相应的值。这样，开发者就可以迅速测试并处理 API 调用频率限制导致的异常，而不需要等一小时的时间间隔结束后才能与 API 通信。

API 调用频率限制生效日期

API 调用频率限制对从2013年8月14日开始新申请的 API Key 生效。对于目前已经在生产环境中激活的 API Key，API 调用频率限制会在2013年11月1日生效。

超出调用频率上限的常见原因

有几种情况可能导致开发者不必要地超出 API 调用频率上限：

1. 不停地重试失败了的 API 调用—— 有一点尤其重要：第三方应用应当密切注意抛出异常时返回的错误代码，并分别处理这些不同的异常类型。特别的，当你的应用捕捉到 EDAMUserException 后，这意味应用的请求自身出了问题，而不是 API 的错误。
2. 对变更使用轮询——尽管周期性地调用 NoteStore.getSyncState 是一种接收用户帐户变更通知的方法，但对于想要完成这种轮询操作的第三方开发者来说，应当考虑使用 webhooks 来接收用户帐户的变更通知。
3. 效率低下的算法——确保你的应用程序最大程度地利用了每一次 API 请求。比方说，如果你使用 NoteStore.getNote 来获取单条笔记的全部内容（包括相关的 Resources），那么请尝试在调用 NoteStore.getNote 时设置上 withResourceData 标志，这样所有的 Resource 数据都会包含在响应中，而不应该对每一个笔记中的 Resource 都分别调用 NoteStore.getResource（这样会导致每个 Resource 都消耗一次请求）。

对于要同步的客户端

几乎可以肯定的是，那些需要完整同步用户所有信息的第三方应用会超出 API 调用频率限制。如果你的应用需要完整同步一个用户帐户，那么请与我们联系，为你的 API Key 协商一个更宽松的 API 调用频率限制。

有疑问？请与我们联系

如果你对于限制 API 调用频率的工作方式有疑问，或者你想要为你的应用争取一个特许 API 调用频率上限，那么请联系印象笔记开发者支持。