ID documento: KB-EV4-API-01 | Prodotto/Servizio: EloView 4 REST API | Pubblico: Integratori, Sviluppatori, Clienti Aziendali
EloView 4 Limiti API e Migliori Pratiche per Integrazioni ad Alto Volume
L'EloView REST API consente ai clienti aziendali e ai partner di integrazione di recuperare programmaticamente informazioni sui dispositivi, monitorare lo stato della flotta, gestire contenuti e distribuire applicazioni. Questo articolo delinea i limiti delle API EloView 4, i comportamenti di autenticazione e le migliori pratiche architetturali per integrazioni API affidabili e ad alto volume.
💡 Panoramica Veloce
EloView 4 non applica limiti API specifici per il singolo cliente. Per una maggiore affidabilità, le integrazioni dovrebbero memorizzare nella cache i token OAuth, favorire le query di tipo bulk/multi-dispositivo, limitare i thread concorrenti e implementare un backoff esponenziale con jitter per la gestione degli errori.
1. Limiti API di EloView 4
EloView 4 non applica limiti di richiesta per singolo credito OAuth, account cliente, indirizzo IP sorgente o endpoint API. L'URL base dell'API in produzione è:
https://secure-api.eloview.com
| Parametro | Limite / Capacità |
|---|---|
| Per credito, account, IP sorgente o endpoint | Nessun limite specifico applicato. |
| Richiesta di Piattaforma AWS (Condivisa) | 10.000 richieste/secondo (Condiviso globalmente da tutti i clienti). |
| Capacità di Picco di Piattaforma AWS (Condivisa) | 5.000 richieste (Condiviso globalmente da tutti i clienti). |
⚠️ Avviso Critico di Integrazione
I limiti condivisi della piattaforma mostrati sopra non sono quote riservate per il singolo cliente. Per evitare problemi di prestazioni e proteggere la stabilità della piattaforma, le integrazioni devono essere progettate per un utilizzo responsabile ed efficiente delle risorse.
2. Autenticazione OAuth e Gestione dei Token
Una gestione impropria dei token è una causa comune di sovraccarico API evitabile. Si prega di strutturare la propria logica di autenticazione secondo le seguenti regole:
-
Durata del Token: I token di accesso sono validi per 24 ore (
expires_in = 86400). - Cache & Riutilizzo: Memorizzare nella cache e riutilizzare i token di accesso per tutta la loro durata di validità. Non generare un nuovo token per ogni richiesta API.
-
Rinnovo Proattivo: Rinnovare il token memorizzato nella cache poco prima della scadenza, o immediatamente al ricevimento di una risposta
HTTP 401 Unauthorized. - Credenziali vs. Capacità: Sebbene gli amministratori degli account possano creare più credenziali OAuth, l'utilizzo di più credenziali non aumenta la capacità API complessiva.
3. Monitoraggio dello Stato della Flotta e dei Dispositivi
Quando si monitora la salute dei dispositivi e le installazioni attive su larga scala, ottimizzare il design delle query per ridurre il sovraccarico di rete:
-
Audit di Stato di Routine: Utilizzare endpoint di query bulk—come
GET /devicesoPUT /devices/search—per recuperare record di stato per più dispositivi in un'unica chiamata. Evitare di interrogareGET /devices/{serial}individualmente per ogni chiosco. - Intervalli di Polling (Idle): Per controlli di salute e stato di routine, intervalli di polling di ogni pochi minuti sono sufficienti.
-
Monitoraggio delle Installazioni Attive: Per tracciare le installazioni attive, interrogare
GET /device/{serial}/content/statusa un intervallo di 1-2 minuti. Smettere di interrogare una volta che l'installazione raggiunge uno stato finale (Successo o Fallimento).
4. Distribuzioni di Applicazioni su Più Dispositivi
L'endpoint POST /deployments supporta il targeting di molti dispositivi simultaneamente.
- Formati di Targeting: Specificare i destinatari in un singolo payload di richiesta utilizzando un elenco di numeri di serie, gruppi di dispositivi o criteri di query.
- Il Target Query Vuoto: Lasciando vuoto il target query, si mirerà automaticamente a tutti i dispositivi nell'account. Utilizzare questo parametro con estrema cautela.
- Restrizioni di Batch: Sebbene l'endpoint non imponga un limite rigido sui numeri di serie, i payload sono comunque soggetti all'impostazione della dimensione batch dell'account e ai permessi dell'operazione batch delle credenziali OAuth.
-
Risposte di Oltre Limite: Superare i limiti dell'account può attivare un errore
400 BATCH_LIMIT_EXCEEDED, o richiedere una verifica manuale sePENDING_FOR_APPROVALè configurato.
5. Concorrenza, Errori API e Riprova
Le integrazioni dovrebbero mantenere un profilo di concorrenza conservativo. Mantenere le richieste parallele attive limitate a 5-10 connessioni concorrenti. Utilizzare code e processamento in batch per trasmettere i dati piuttosto che eseguire migliaia di endpoint paralleli.
Risposte & Azioni Comuni delle API
| Stato HTTP API | Significato & Azione Raccomandata |
|---|---|
| HTTP 401 Unauthorized | Errore di autenticazione (ad es., token scaduto o revocato). Verificare le credenziali di autenticazione e richiedere un nuovo token. |
| HTTP 429 Troppi Richieste | Limitazione della piattaforma per il numero di richieste. Implementare una logica di ripetizione utilizzando un backoff esponenziale con jitter casuale. |
| 400 BATCH_LIMIT_EXCEEDED | La dimensione del payload supera i limiti di esecuzione batch consentiti. Rivedere le impostazioni dell'account e partizionare la transazione. |
⚙️ Strategia di Backoff per la Logica di Ripetizione
Quando si gestiscono risposte HTTP 429, configurare il proprio programma di ripetizione in modo progressivo (ad es., 1s, 2s, 4s, 8s, 16s, 32s, fino a un massimo di 60s) e applicare un ritardo casuale (jitter) per prevenire allagamenti di servizio localizzati. Nota: La restituzione da parte della piattaforma dell'intestazione 'Retry-After' non è confermata.
6. Risoluzione dei Problemi con Errori API Inaspettati
Se la tua integrazione subisce interruzioni persistenti, segui questa rapida checklist di risoluzione dei problemi:
-
Valida l'URL Base: Conferma di chiamare il gateway EloView 4 (
https://secure-api.eloview.com) e non un host EloView 3 legacy. -
Verifica i Codici di Stato: Isola i problemi di autorizzazione (
HTTP 401) da limitazioni infrastrutturali (HTTP 429). - Rivedi le Metriche Operative: Rivedi le durate di riutilizzo dei token, le frequenze di polling dei singoli chioschi, l'utilizzo degli endpoint bulk e il conteggio della concorrenza dei thread attivi.
📞 Escalazione al Supporto Tecnico
Se i problemi API inaspettati persistono, contatta Elo Technical Support. Per accelerare l'indagine, si prega di fornire:
- API Base URL e specifico endpoint chiamato
- I tuoi indirizzi IP sorgente pubblici in uscita
- Timestamp precisi degli eventi (incluso il fuso orario)
- Codici di stato HTTP restituiti e payload di risposta completi
Please report any broken links by emailing elo.support@zebra.com and include a link to the knowledge article