ID документа: KB-EV4-API-01 | Продукт/Сервис: EloView 4 REST API | Аудитория: Интеграторы, разработчики, корпоративные клиенты
EloView 4 API: Ограничения по частоте и лучшие практики интеграции высокого объема
REST API EloView позволяет корпоративным клиентам и партнерам по интеграции программно получать информацию о устройствах, контролировать состояние флота, управлять контентом и разворачивать приложения. Эта статья описывает ограничения частоты API EloView 4, поведение аутентификации и архитектурные лучшие практики для надежных интеграций API высокого объема.
💡 Быстрый обзор
EloView 4 не применяет индивидуальные ограничения по API для конкретных клиентов. Для оптимальной надежности интеграции должны кэшировать OAuth токены, предпочитать пакетные/многопользовательские запросы, ограничивать количество параллельных потоков и реализовать экспоненциальную повторную попытку с колебанием для обработки ошибок.
1. Ограничения по частоте API EloView 4
EloView 4 не накладывает ограничения по частоте для отдельных учетных данных OAuth, клиентских учетных записей, IP-адресов источника или конечных точек API. Базовый URL продакшн API:
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}для каждого киоска. - Интервалы опроса (Неактивные): Для рутинной проверки состояния и здоровья интервалы опроса каждые несколько минут достаточны.
-
Мониторинг активных развертываний: Чтобы отслеживать активные установки, запрашивайте
GET /device/{serial}/content/statusс интервалом 1-2 минуты. Прекратите опрос, как только развертывание достигнет окончательного состояния (Успех или Ошибка).
4. Развертывание приложений на несколько устройств
Конечная точка POST /deployments поддерживает целевые установки для многих устройств одновременно.
- Форматы целей: Укажите получателей в одной нагрузке запроса, используя список серийных номеров, групп устройств или критерии запроса.
- Пустой целевой запрос: Оставив целевой запрос пустым, вы автоматически нацелите все устройства в учетной записи. Используйте этот параметр с крайней осторожностью.
- Ограничения по пакетам: Хотя конечная точка не накладывает жесткое ограничение на серийные номера, полезные нагрузки продолжают быть подверженными настройкам размера пакета вашей учетной записи и разрешениям на пакетные операции учетных данных OAuth.
-
Ответы о превышении лимита: Превышение лимитов вашей учетной записи может вызвать ошибку
400 BATCH_LIMIT_EXCEEDEDили потребовать ручной проверки, если настроеноPENDING_FOR_APPROVAL.
5. Параллелизм, ошибки API и повторные попытки
Интеграции должны поддерживать консервативный профиль параллелизма. Ограничьте активные параллельные запросы до 5–10 одновременных соединений. Используйте очереди и пакетную обработку для передачи данных, а не выполнения тысяч параллельных конечных точек.
Общие ответы API и действия
| HTTP статус API | Значение и рекомендуемое действие |
|---|---|
| HTTP 401 Unauthorized | Ошибка аутентификации (например, токен истек или был отозван). Проверьте учетные данные аутентификации и запросите новый токен. |
| HTTP 429 Too Many Requests | Троттлинг по частоте платформы. Реализуйте логику повторной попытки с использованием экспоненциальной задержки с рандомизированным колебанием. |
| 400 BATCH_LIMIT_EXCEEDED | Размер полезной нагрузки превышает допустимые лимиты выполнения пакетов. Проверьте настройки учетной записи и разделите транзакцию. |
⚙️ Стратегия задержки повторной попытки
При обработке ответов HTTP 429 настройте свое расписание повторных попыток прогрессивно (например, 1с, 2с, 4с, 8с, 16с, 32с, до максимума 60с) и применяйте случайную задержку (колебание), чтобы предотвратить локализованные наводнения в сервисе. Примечание: возврат заголовка 'Retry-After' от платформы не подтвержден.
6. Устранение неожиданных ошибок API
Если ваша интеграция испытывает постоянные сбои, пройдите этот краткий контрольный список по устранению неполадок:
-
Проверьте базовый URL: Убедитесь, что вы вызываете шлюз EloView 4 (
https://secure-api.eloview.com), а не устаревший хост EloView 3. -
Проверьте статусные коды: Изолируйте проблемы с авторизацией (
HTTP 401) от затруднений в инфраструктуре (HTTP 429). - Просмотрите операционные метрики: Просмотрите сроки повторного использования токенов, частоту опроса отдельных киосков, использование пакетных конечных точек и количество одновременных потоков.
📞 Эскалация в техническую поддержку
Если неожиданные проблемы с API продолжаются, свяжитесь с технической поддержкой Elo. Чтобы ускорить расследование, пожалуйста, предоставьте:
- Базовый URL API и конкретную вызываемую конечную точку
- Ваши публичные исходящие IP-адреса источников
- Точные временные метки событий (включая часовой пояс)
- Возвращенные коды HTTP статуса и полные полезные нагрузки ответов
Please report any broken links by emailing elo.support@zebra.com and include a link to the knowledge article