文档ID: KB-EV4-API-01 | 产品/服务: EloView 4 REST API | 受众: 集成商、开发者、企业客户
EloView 4 API 速率限制和高容量集成最佳实践
EloView REST API 使企业客户和集成合作伙伴能够以编程方式检索设备信息、监控设备健康、管理内容和部署应用程序。本文概述了 EloView 4 API 的速率限制、身份验证行为和可靠、高容量 API 集成的架构最佳实践。
💡 快速概述
EloView 4 不对每个客户特定的 API 施加速率限制。为了获得最佳可靠性,集成应缓存 OAuth 令牌,优先使用批量/多设备查询,限制并发线程,并在错误处理时实施指数退避和抖动。
1. EloView 4 API 速率限制
EloView 4 不对单个 OAuth 凭据、客户账户、源 IP 地址或 API 端点施加速率限制。生产 API 基础 URL 为:
https://secure-api.eloview.com
| 参数 | 限制 / 容量 |
|---|---|
| 每个凭据、账户、源 IP 或端点 | 没有施加特定的速率限制。 |
| AWS 平台请求速率(共享) | 10,000 请求/秒(全球所有客户共享)。 |
| AWS 平台突发容量(共享) | 5,000 请求(全球所有客户共享)。 |
⚠️ 关键集成警告
上述共享平台限制不是客户分配配额。为避免性能问题并保护平台稳定性,集成必须设计为高效、负责任地利用资源。
2. OAuth 身份验证和令牌管理
不当的令牌处理是可避免的 API 开销的常见原因。请根据以下规则构建您的身份验证逻辑:
-
令牌寿命:访问令牌有效期为24小时(
expires_in = 86400)。 - 缓存与重用:在整个有效期内缓存和重用访问令牌。不要为每个 API 请求生成新令牌。
-
主动续订:在到期前不久续订缓存的令牌,或在收到
HTTP 401 Unauthorized响应后立即续订。 - 凭据与容量:虽然账户管理员可以创建多个 OAuth 凭据,但使用多个凭据不会增加您整体的 API 容量。
3. 监控设备和设备状态
在大规模监控设备健康和活动部署时,优化查询设计以减少网络开销:
-
例行状态审计:使用批量查询端点——如
GET /devices或PUT /devices/search——一次调用检索多个设备的状态记录。避免为每个自助服务终端单独轮询GET /devices/{serial}。 - 轮询间隔(空闲):对于例行健康和状态检查,每几分钟的轮询间隔是足够的。
-
活动部署监控:要跟踪活动安装,请以1到2分钟的间隔查询
GET /device/{serial}/content/status。一旦部署达到最终状态(成功或失败),请停止轮询。
4. 向多个设备部署应用程序
POST /deployments 端点支持同时针对多个设备。
- 目标格式:在单个请求有效载荷中使用序列号、设备组或查询标准的列表指定接收方。
- 空查询目标:将目标查询留空将自动针对账户中的所有设备。请谨慎使用此参数。
- 批处理限制:虽然端点不施加严格的序列号限制,但有效载荷仍受您的账户批量大小设置和 OAuth 凭据的批量操作权限的限制。
-
超限制响应:超出您的账户限制可能会触发
400 BATCH_LIMIT_EXCEEDED错误,或者如果配置为PENDING_FOR_APPROVAL,则需要手动验证。
5. 并发、API错误和重试
集成应保持保守的并发配置。保持活动的并行请求限制在5-10个并发连接。使用队列和批处理来流式处理数据,而不是执行数千个并行端点。
常见 API 响应及操作
| API HTTP 状态 | 含义和推荐操作 |
|---|---|
| HTTP 401 Unauthorized | 身份验证失败(例如,令牌过期或被撤销)。验证身份验证凭据并请求新的令牌。 |
| HTTP 429 Too Many Requests | 平台速率限制。实施重试逻辑,使用指数退避和随机抖动。 |
| 400 BATCH_LIMIT_EXCEEDED | 有效载荷大小超过允许的批量执行限制。审核账户设置并分区事务。 |
⚙️ 重试逻辑退避策略
在处理HTTP 429响应时,配置您的重试计划逐步增加(例如,1s、2s、4s、8s、16s、32s,最多60s),并应用随机延迟(抖动)以防止区域性服务洪水。注意:平台返回“Retry-After”头部未确认。
6. 故障排除意外的 API 错误
如果您的集成经历持续中断,请快速检查以下故障排除清单:
-
验证基础 URL:确认您正在调用EloView 4网关(
https://secure-api.eloview.com),而不是旧版 EloView 3 主机。 -
验证状态代码:将授权问题(
HTTP 401)与基础设施限流(HTTP 429)隔离。 - 审核操作指标:审核令牌重用寿命、各自助服务终端的轮询频率、大宗端点的使用情况以及活动线程并发计数。
📞 递交技术支持请求
如果出现意外的 API 问题,请联系Elo 技术支持。要加快调查,请提供:
- API 基础 URL 和调用的具体端点
- 您的面向公众的外发源 IP 地址
- 精确的事件时间戳(包括时区)
- 返回的 HTTP 状态代码和完整响应有效载荷
Please report any broken links by emailing elo.support@zebra.com and include a link to the knowledge article