문서 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 요청 (모든 고객이 공유). |
⚠️ 중요한 통합 경고
위에 표시된 공유 플랫폼 제한은 고객별 quota가 아닙니다. 성능 문제를 피하고 플랫폼 안정성을 보호하기 위해 통합은 효율적이고 책임 있는 자원 사용을 위해 설계해야 합니다.
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 응답 및 조치
| API HTTP 상태 | 의미 및 권장 조치 |
|---|---|
| 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 기술 지원에 문의하십시오. 조사를 가속화하기 위해 다음 정보를 제공하십시오:
- API 기본 URL 및 호출된 특정 엔드포인트
- 공용 외부 출발 소스 IP 주소
- 정확한 이벤트 타임스탬프(시간대 포함)
- 반환된 HTTP 상태 코드 및 전체 응답 페이로드
Please report any broken links by emailing elo.support@zebra.com and include a link to the knowledge article