Perché la limitazione Rate basata sulla complessità?
I tradizionali REST API utilizzano la limitazione Rate basata su richiesta in cui ogni richiesta consuma gli stessi crediti, sia che si recuperi un campo o centinaia e che si legga o si modifichino i dati, nonostante la differenza significativa nel carico del server.
L'approccio basato sulla complessità delle query di GraphQL risolve questo problema calcolando i costi in base ai dati effettivi richiesti e alle operazioni eseguite. Ciò ti offre maggiore flessibilità nel richiedere ciò di cui hai bisogno fornendo al contempo un carico del server prevedibile.
Limite Rate
Zonos utilizza un sistema basato su punti in cui ogni query detrae punti in base alla sua complessità. Hai un pool di punti disponibili che:
- Si ricarica a 3.000 punti al secondo (30.000 punti ogni 10 secondi)
- Ha una capacità massima di 300.000 punti
Ciò consente di effettuare serie occasionali di query complesse mantenendo un ritmo di richieste sostenibile.
Come viene calcolato il costo della query
Ogni richiesta GraphQL ha un costo calcolato prima dell'esecuzione:
Costi base
- Query: 5 punti
- Mutazione: 10 punti
- Oggetto: 1 punto per oggetto restituito
- Campi scalari: 0 punti (gratuito)
I campi scalari come stringhe, numeri interi, ID e booleani non aumentano il costo. Paghi solo l'operazione base e gli oggetti restituiti.
Esempio: query semplice
query { landedCost(id: "123") { id createdBy shipToCountry }}Ripartizione dei costi: 5 (query base) + 1 (oggetto Landed Cost) = 6 punti
I campi scalari (id, name, currency) sono gratuiti.
Esempio: query con più oggetti
{ orders(first: 10, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Ripartizione dei costi: 5 (query base) + 10 (10 ordini × 1 punto ciascuno) = 15 punti
Esempio: mutazione
mutation { landedCostCalculate(input: { ... }) { id }}Ripartizione dei costi: 10 (mutazione base) + circa 50 (oggetti restituiti) = 60 punti
Un tipico calcolo Landed Cost costa circa 60 punti in termini di complessità.
Visualizzazione della complessità della query
Ogni risposta API include un'intestazione zonos-query-complexity che mostra il costo della tua query:
zonos-query-complexity: 58Questa intestazione indica esattamente quanti punti ha consumato la query. Usalo per monitorare l'utilizzo di API e ottimizzare le query costose.
Gestione dei limiti Rate
Se superi il limite Rate, riceverai un messaggio di errore. Per gestire i limiti Rate in modo efficace:
Monitora la tua complessità
Controlla l'intestazione zonos-query-complexity nelle risposte per comprendere i costi delle query e identificare modelli costosi.
Implementa la logica dei nuovi tentativi
Se raggiungi i limiti Rate, implementa il backoff esponenziale e la logica dei nuovi tentativi. Poiché il contenitore si riempie a 3.000 punti al secondo, calcola i tempi di attesa appropriati in base alla complessità della tua query.
Raggruppa in modo efficiente
GraphQL ti consente di richiedere più query in un'unica richiesta:
{ landedCost(id: "landed_cost_123") { id createdAt } order(orderId: "order_123") { id status createdAt }}Migliori pratiche
Richiedi solo ciò di cui hai bisogno
La complessità delle query è proporzionale ai dati richiesti. Struttura le tue query per recuperare solo i campi e gli oggetti che utilizzerai effettivamente.
query { order(orderId: "order_123") { id status createdAt updatedAt items { id name quantity amount } shipments { id } }}Impagina set di dati di grandi dimensioni
Quando richiedi più oggetti, utilizza dimensioni di pagina ragionevoli:
{ orders(first: 100, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Richiedi da 10 a 50 elementi alla volta e impagina i risultati secondo necessità, anziché richiedere centinaia di oggetti in un'unica query.
Evita annidamenti non necessari
Ogni oggetto nidificato aumenta la tua complessità. Richiedi i dati nidificati solo quando ne hai effettivamente bisogno.
Limitazione Rate delle API GraphQL
Scopri come Zonos calcola i costi delle query in base alla complessità.
Zonos applica un limite di Rate alle richieste GraphQL API in base alla complessità della query anziché al conteggio delle richieste. Ciò garantisce un utilizzo equo e ti consente di richiedere esattamente i dati di cui hai bisogno.