技术通知

为了帮助维护系统稳定性并提高性能，Adobe Acrobat Sign 正在为 GET API 端点引入轮询阈值。 此策略限制客户端应用程序对 Acrobat Sign 服务进行相同 API 调用的频率。

高频轮询会给后端系统带来不必要的负载，从而降低性能并拖慢响应时间。 建议 API 开发者使用 webhook 获取近实时更新，而不是重复轮询。

更改了哪些方面

此轮询策略适用于所有针对相同调用的 GET API 端点。

系统对同一有效用户向 Acrobat Sign 发起相同 API 调用的频率施加了限制。 当同一有效用户进行相同调用的频率超过适用轮询阈值允许的频率时，系统会返回错误。

例如，对同一端点针对同一协议或库文档的重复请求被视为相同调用。 对不同协议或库文档的请求被视为不同调用，因为每个对象代表不同的请求目标。

受影响端点的示例

状态检索

• GET /agreements/{agreementId} — 检索协议的当前状态。
• GET /agreements/{agreementId}/documents/{documentId} — 检索协议中文档的文件流。

列表、事件和库文档

• GET /agreements — 检索用户的协议。
• GET /agreements/{agreementId}/events — 检索协议的事件信息。
• GET /libraryDocuments — 检索用户的库文档。
• GET /libraryDocuments/{libraryDocumentId} — 检索特定库文档的信息。

轮询策略详细信息

最小对象轮询间隔 (MOPI) 定义同一有效用户可以向 Acrobat Sign 服务进行相同 GET API 请求的频率。

默认 MOPI 因服务层级而异：

• GLOBAL、ENTERPRISE 和 DEVELOPER 层级：每 1 分钟间隔内允许 3 次相同调用。
• 所有其他层级：每 3 分钟间隔内允许 3 次相同调用。

如果同一有效用户以超过该层级允许的频率发起相同的 GET 请求，Acrobat Sign 将返回 429 Too Many Requests 响应，并附带 Retry-After 标头。

当同一有效用户在适用的轮询间隔内使用相同的请求路径和请求头发出相同的 GET 请求时，该请求被视为相同。

ETag 处理

对于支持条件 GET 请求的端点，应用程序可以继续使用 ETag 和 If-None-Match 标头。

对于在轮询阈值范围内允许的条件 GET 请求，当资源未更改时，Acrobat Sign 可能会返回 304 Not Modified。

当超出轮询阈值时，即使请求包含 If-None-Match 标头，Acrobat Sign 仍会返回 429 Too Many Requests 响应，并附带 Retry-After 标头。

必要措施

如果您的应用程序需要近乎实时的更新，请使用 Webhook，而不是轮询。 Webhooks 提供了一种更高效、更具可扩展性的方式来接收及时更新。

如果无法实施 Webhook，应用程序应使用客户端缓存机制来存储和重用 API 响应。

• 当收到 304 Not Modified 响应时，应使用缓存的数据，而不是再次发起 API 调用。
• 当收到 429 Too Many Requests 响应时，请根据 Retry-After 标头中提供的秒数，仅在该时长后重试 API 调用。

资源

• 处理 429 响应：https://developer.adobe.com/acrobat-sign/docs/overview/developer_guide/apiusage#handling-rate-limiting-http-429
• API 轮询阈值：https://developer.adobe.com/acrobat-sign/docs/overview/developer_guide/apiusage#get-endpoints

时间轴

更新的 MOPI 阈值已在生产环境中生效。

• 更新的 ETag 限流行为包含在 17.1.1 版本中。 更改后，Acrobat Sign 对限流请求返回 429 Too Many Requests，包括含有 If-None-Match 标头的条件 GET 请求。
• 沙盒环境中的新帐户轮询策略将于 2026 年 2 月 11 日设置为 ENFORCED。
• 生产环境中的新帐户轮询策略将于 2026 年 4 月 5 日设置为 ENFORCED。

如需帮助或有任何问题，请联系您的客户成功经理。