Hub per sviluppatoriStato dell'APISupporto

Piani di utilizzo e limiti tariffari

Scopri i piani di utilizzo e come vengono utilizzati i limiti di velocità in SP-API.

L'affidabilità delle API dipende dal dimensionamento della capacità e delle risorse per soddisfare le mutevoli esigenze dell'applicazione nel tempo. Per questo motivo, la Selling Partner API (SP-API) definisce piani di utilizzo per controllare il numero di richieste che puoi fare a un'operazione entro un determinato periodo di tempo.

I piani di utilizzo dipendono da diversi fattori. Questi fattori possono includere l'account del partner di vendita, l'applicazione che chiama l'SP-API per conto dell'account del partner di vendita, il marketplace e così via.

Questo documento descrive l'algoritmo di limitazione della velocità dell'API SP, i fattori che determinano i piani di utilizzo, come trovare il piano di utilizzo e le domande frequenti su come rispettare i limiti di tariffa.

Per indicazioni su come ottimizzare i carichi di lavoro delle applicazioni per sfruttare in modo efficiente i limiti di velocità per ciascuna operazione SP-API, fare riferimento a Ottimizza i limiti di velocità per i carichi di lavoro delle applicazioni.

Terminologia

I seguenti termini si riferiscono alla limitazione della velocità nell'SP-API:

  • Limite di velocità: Il numero massimo di richieste che l'SP-API consente di effettuare per una determinata operazione al secondo. Per evitare limitazioni, rimanete al di sotto di questo limite.
  • Limite di raffica: Il numero massimo di richieste per una determinata operazione che puoi accumulare nel tempo e quindi inviare contemporaneamente.
  • Piano di utilizzo: La combinazione di limite di velocità e limite di scoppio che si applica a un'operazione specifica. Per ulteriori informazioni, fare riferimento a Tipi di piano di utilizzo e Fattori che determinano i piani di utilizzo.
  • Algoritmo Token Bucket: L'algoritmo utilizzato dall'SP-API per limitare la frequenza delle richieste, basato su un'analogia dello scambio di token con richieste API. Per una panoramica sull'algoritmo, fare riferimento a Algoritmo di limitazione della velocità.
  • Limitazione: Il caso in cui l'SP-API respinga temporaneamente le tue richieste quando superi il limite di velocità. Una richiesta limitata genera una risposta di errore HTTP 429. Puoi riprovare le richieste limitate in un secondo momento.
  • Account: L'account del partner di vendita per conto del quale l'applicazione per sviluppatori chiama l'SP-API. Specifichi l'account fornendo un sellerId quando si chiamano determinate operazioni SP-API.
  • Applicazione: L'applicazione per sviluppatori che chiama l'SP-API per conto di un partner di vendita. Nella console per sviluppatori del partner di vendita, puoi trovare l'ID dell'applicazione dopo il nome dell'applicazione.
  • Operazioni senza concessione: Operazioni che non richiedono un sellerId come parte della richiesta. Per le operazioni senza concessione, il partner di vendita non è un fattore nel piano di utilizzo di tale operazione. Per un elenco delle operazioni senza concessione, fare riferimento a Operazioni senza concessione.

Algoritmo di limitazione della velocità

L'SP-API utilizza l'algoritmo token bucket per limitare la frequenza delle richieste all'API. L'algoritmo si basa sull'analogia di un bucket che contiene token, in cui è possibile scambiare ogni token con una richiesta all'API.

In questa analogia, l'SP-API aggiunge automaticamente i token al bucket a una velocità prestabilita al secondo fino a raggiungere la dimensione massima del bucket. La dimensione massima viene anche chiamata velocità di burst.

Quando si chiama l'SP-API, l'SP-API recupera il piano di utilizzo (limite di velocità e limite di burst) per tale operazione in base al token di accesso che identifica l'identità del chiamante nell'intestazione della richiesta. Ogni richiesta effettuata all'SP-API sottrae un token dal bucket. La limitazione si verifica quando si effettua una richiesta per la quale non è disponibile alcun token perché il bucket è vuoto. Una richiesta limitata genera una risposta di errore.

L'illustrazione seguente mostra come funziona la limitazione della velocità in base all'algoritmo del token bucket e ai criteri di allocazione del bucket. L'esempio utilizza un'operazione con un limite di velocità di uno e un limite di burst di due.

The token bucket algorithm.

  1. Il bucket è inizialmente pieno e contiene due gettoni (limite burst). Alle 01:00:100, un'applicazione chiama un'operazione dell'SP-API per conto di un partner di vendita che opera nel mercato dell'UE. La richiesta è andata a buon fine. Il bucket ora contiene un singolo token perché la richiesta ha esaurito un token dal bucket.
  2. Dopo 100 millisecondi, alle 01:00:200, la stessa applicazione chiama la stessa operazione per conto dello stesso partner di vendita nella stessa regione. La richiesta ha esito positivo e utilizza l'ultimo token del bucket. Il bucket è ora vuoto.
  3. Dopo altri 100 millisecondi, alle 01:00:300, la stessa applicazione chiama la stessa operazione per conto dello stesso partner di vendita nella stessa regione. Questa volta, a causa dell'esaurimento dei limiti (bucket vuoto), la richiesta viene limitata.
  4. A un secondo dall'inizio di questo esempio, alle 01:01:000, l'SP-API inserisce un token nel bucket, poiché il limite di velocità è di un token al secondo. L'applicazione può ora richiamare l'operazione con successo senza subire limitazioni.
  5. Dopo un altro secondo, alle 01:02:00, l'SP-API aggiunge un altro token al bucket.
  6. Alle 01:03:00, l'SP-API non aggiunge un altro token al bucket perché il bucket ha raggiunto la sua dimensione massima (limite di burst).

I fattori che determinano i limiti di rate e burst indicano che in alcuni casi esiste un bucket di token separato. In questo esempio, due token sono disponibili alle 01:00:200 nei seguenti casi:

  • La stessa applicazione attiva la stessa operazione ma per conto di un partner di vendita diverso.
  • La stessa applicazione richiama la stessa operazione per conto dello stesso partner di vendita ma utilizzando le credenziali di un account regionale diverso.
  • Un'applicazione diversa attiva la stessa operazione per conto dello stesso partner di vendita.

La figura seguente mostra questi scenari alternativi.

Alternate scenarios.

Fattori che determinano i piani di utilizzo

I limiti di velocità e burst per ogni operazione SP-API dipendono da diversi fattori e più piani di utilizzo possono essere applicati a una singola operazione. La frequenza delle richieste è limitata dalla soglia raggiunta per prima.

L'SP-API si basa sui seguenti fattori per assegnare i piani di utilizzo:

  • Funzionamento API: Ogni operazione dell'SP-API ha la propria frequenza predefinita e i propri limiti di burst. È possibile trovare questi limiti, o un collegamento alla documentazione che elenca i limiti, nella documentazione di riferimento dell'API per ciascuna operazione.
  • Partner di vendita (account) e coppia di candidature: I limiti tariffari per la maggior parte delle operazioni si riferiscono al partner di vendita e alla coppia di applicazioni. L'applicazione chiama l'SP-API per conto del partner di vendita. Le operazioni Grantless sono eccezioni a questa regola. Le applicazioni possono chiamare operazioni grantless senza l'autorizzazione di un partner di vendita. Per le operazioni grantless, i piani di utilizzo sono definiti in base agli altri criteri di questa sezione.
  • Regioni e mercati: I piani di utilizzo sono implicitamente legati ai gruppi del marketplace in cui opera un partner di vendita e ha autorizzato un'applicazione a chiamare l'SP-API per suo conto. La natura implicita di questo fattore di limitazione delle tariffe dipende dai diversi account dei partner di vendita specifici del marketplace. I diversi account dei partner di vendita specifici del marketplace hanno ID venditore diversi.

Tipi di piani di utilizzo

Ogni operazione SP-API è associata a un piano di utilizzo. Un piano di utilizzo specifica un limite di velocità e un limite di burst. Per informazioni dettagliate su come trovare il piano di utilizzo, consulta Come trovare il tuo piano di utilizzo. Esistono due tipi di piani di utilizzo: standard e dinamico.

  • Piani di utilizzo standard: La maggior parte delle API SP è regolata da piani di utilizzo standard. Con un piano di utilizzo standard, i limiti di frequenza hanno valori statici per tutti i chiamanti in base ai modelli di chiamata previsti per ciascuna operazione. Puoi trovare il piano di utilizzo, o un link alla documentazione che elenca il piano di utilizzo, nella documentazione di riferimento dell'API per ogni operazione.

  • Piani di utilizzo dinamici: Alcune API e operazioni SP hanno piani di utilizzo dinamici. Un piano di utilizzo dinamico è un piano che viene adattato automaticamente a ciascun partner di vendita in base alle esigenze aziendali attuali e storiche di quell'azienda. Poiché lo scopo dei piani di utilizzo dinamico è quello di dimensionare correttamente tali limiti nel tempo, le tariffe possono cambiare. Diverse metriche aziendali dei partner di vendita influiscono sugli aggiustamenti dei tassi. Queste metriche sono solo metriche aziendali e non includono un numero storico di richieste API. Le tariffe non aumentano in modo dinamico perché un'applicazione effettua richieste API più frequentemente.

    I piani di utilizzo dinamico si applicano solo alle seguenti API e operazioni SP.

Come trovare il tuo piano di utilizzo

Puoi trovare il tuo piano di utilizzo (limiti di velocità e burst) nei seguenti modi:

  • Documentazione SP-API: Puoi trovare questi limiti, o un link alla documentazione che li elenca, nella documentazione di riferimento dell'API per ogni operazione.

  • Intestazione della risposta: Quando si chiama un'operazione SP-API, x-amzn-RateLimit-Limit l'intestazione della risposta, se disponibile, specifica i limiti di velocità dell'operazione per coppia account-applicazione. Tuttavia, non devi dipendere dalla presenza di questa intestazione, per i seguenti motivi:

    • In alcuni casi, nonostante il massimo sforzo, l'SP-API non è in grado di recuperare i limiti di velocità. In questo caso, l'SP-API non fallisce una chiamata all'operazione altrimenti valida. L'SP-API restituisce invece la risposta senza x-amzn-RateLimit-Limit intestazione.
    • Le x-amzn-RateLimit-Limit l'intestazione della risposta è per i codici di stato HTTP 20x, 400 e 404. Le richieste non autorizzate o non autenticate non includono questa intestazione.
    • Le x-amzn-RateLimit-Limit l'intestazione non include altri limiti tariffari del piano di utilizzo.

    Pertanto, si consiglia di non basarsi sulla presenza o meno dell'x-amzn-RateLimit-Limitintestazione in una risposta. Verificare invece la presenza dell'intestazione, prima di provare a utilizzare il valore del limite di tariffa.

Domande frequenti

I limiti di tariffa per un'operazione sono troppo bassi per il mio caso d'uso. È possibile aumentare il limite?

Puntiamo a limiti di dimensioni adeguate, con l'obiettivo che gli schemi di chiamata efficienti, idealmente, non vengano mai limitati. Se la tua applicazione è costantemente limitata, potrebbe significare che puoi ottimizzare ulteriormente i tuoi schemi di chiamata. Per ulteriori informazioni, fare riferimento a Cosa devo fare se la mia applicazione viene costantemente limitata. Se ritieni che i tassi di default non siano sufficienti, consulta Strategie per ottimizzare i limiti di velocità per i carichi di lavoro delle applicazioni.

In che modo la mia applicazione gestirà una risposta 429?

Un 429 è un codice di stato riutilizzabile. Puoi riprovare, ma le ripetute richieste limitate richiedono una strategia di back-off. Usa il x-amzn-RateLimit-Limit intestazione della risposta, se disponibile, per determinare se i limiti di tariffa sono diversi dalle tue aspettative. Per informazioni dettagliate su quando questa intestazione è disponibile, consulta Come trovare il tuo piano di utilizzo.

Come posso testare la mia applicazione rispetto ai suoi piani di utilizzo?

Puoi testare la gestione degli errori 429 utilizzando la sandbox dell'API Selling Partner. Tuttavia, non puoi testare i limiti di frequenza con la sandbox perché, sebbene le operazioni in produzione possano avere tassi diversi, tutte le operazioni in sandbox condividono la stessa frequenza. Puoi trovare le tariffe di utilizzo assegnate nella x-amzn-RateLimit-Limit intestazione di risposta per ogni operazione, se disponibile. Per informazioni dettagliate su quando questa intestazione è disponibile, fare riferimento a Come trovare il tuo piano di utilizzo.

È possibile evitare completamente la limitazione della mia applicazione?

No. Qualsiasi numero di fattori al di fuori del tuo controllo può provocare alcuni 429 transitori. Il codice dell'applicazione dovrebbe tenere conto di questa possibilità.

Cosa devo fare se la mia applicazione viene costantemente limitata?

Se l'applicazione è costantemente limitata, potrebbe essere necessario ottimizzare ulteriormente i modelli di chiamata. Ad esempio:

  • Chiama meno frequentemente e rispetta i limiti tariffari.

  • Affidati alle notifiche push anziché ai meccanismi di polling.

  • Utilizza le API batch laddove disponibili o prova a fare di più con meno chiamate. Ad esempio, con Mangimi e Rapporti API, puoi inviare o recuperare ulteriori informazioni per chiamata. In genere, esamina i tuoi schemi di chiamata confrontandoli con le operazioni in un'API per determinare se riesci a svolgere lo stesso lavoro con un minor numero di chiamate.

La mia applicazione verrà limitata più spesso man mano che ottengo più autorizzazioni?

No. I piani di utilizzo sono specifici per la coppia di applicazioni e partner di vendita, in modo che la produttività cresca naturalmente con i clienti.

I limiti tariffari cambieranno?

Potremmo aumentare i limiti tariffari in qualsiasi momento. Se dovessimo abbassare i limiti tariffari pubblicati nella documentazione di riferimento API, comunicheremo la modifica in anticipo per darti il tempo di aggiornare e testare le tue applicazioni prima che la modifica diventi effettiva.

I limiti di tariffa per i piani di utilizzo dinamici si regolano automaticamente verso l'alto o verso il basso a seconda del contesto aziendale.

I miei limiti tariffari aumenteranno se la mia applicazione viene costantemente limitata?

Le velocità si basano sulle metriche aziendali del partner di vendita. Se un'applicazione viene limitata costantemente, è probabile che i tuoi modelli di chiamata non siano in linea con i limiti di velocità assegnati a quel partner di vendita. Fai riferimento a Cosa devo fare se la mia applicazione viene costantemente limitata? e I limiti di velocità per un'operazione sono troppo bassi per il mio caso d'uso. È possibile aumentare il limite?.

Qual è l'obiettivo complessivo dei piani di utilizzo dinamici?

In precedenza, abbiamo osservato che i piani di utilizzo omogenei sono sovradimensionati per alcune situazioni e, peggio ancora, sottodimensionati per altre. L'obiettivo dei piani di utilizzo dinamici è sfruttare il contesto aziendale noto di una determinata chiamata per porre i limiti giusti in ogni situazione.

Quali fattori influenzano i piani di utilizzo dinamici?

In generale, i limiti tariffari sono determinati dal tipo, dalle dimensioni e dal comportamento dell'attività del partner di vendita.

Con quale frequenza vengono modificati i limiti associati a un determinato piano di utilizzo?

Il nostro obiettivo è prevenire modifiche frequenti e significative dei limiti. In genere, i limiti vengono modificati non appena rileviamo cambiamenti significativi nelle metriche aziendali di un account Selling Partner.

Come devo codificare la mia applicazione per rispettare i limiti dinamici?

I seguenti suggerimenti possono aiutare l'applicazione a gestire i limiti di velocità dinamici:

  • Leggi il x-amzn-RateLimit-Limit intestazione, se disponibile. Per informazioni dettagliate su quando questa intestazione è disponibile, consulta Come trovare il tuo piano di utilizzo.

  • Evitare di codificare i timer

  • Codifica naturalmente in base agli eventi anziché in esecuzione in loop. Se usi gli eventi, non hai bisogno di un timer. Ad esempio, aggiorna i prezzi in risposta alle notifiche sui prezzi anziché ogni determinato numero di secondi.


Questa pagina ti è stata utile?