Quote

Questo documento elenca le quote che si applicano all'API Merchant.

L'API Merchant utilizza le quote per garantire un ambiente stabile ed equo per tutti gli utenti. Le quote impediscono a un singolo utente dell'API di sovraccaricare il sistema, garantendo prestazioni elevate. Comprendere queste quote è fondamentale per gestire i dati di prodotto e ampliare la tua attività su Google.

Concetti generali

Le quote dell'API Merchant vengono gestite tramite gruppi di quote.

I metodi API sono mappati ai gruppi di quote. La struttura di questa mappatura può variare:

  • Singolo metodo per gruppo: alcuni gruppi di quote si applicano a un singolo metodo API. Ad esempio, il metodo per elencare le origini dati accounts.dataSources.list ha un proprio gruppo di quote dedicato.
  • Più metodi per gruppo (aggregazione): spesso i metodi correlati vengono raggruppati in un unico gruppo di quote. Tutti i metodi all'interno di questo gruppo condividono gli stessi limiti giornalieri e al minuto. Esempi più comuni:
    • Raggruppamento di tutte le operazioni di lettura per metodi e risorse correlati, ad esempio merchant-accounts-read-methods.
    • Raggruppamento di tutte le operazioni di scrittura per metodi e risorse correlati, ad esempio merchant-accounts-write-methods.

Ogni chiamata al metodo viene conteggiata una volta, indipendentemente dal tipo. Una richiesta list di 250 elementi viene conteggiata una sola volta, non come 250 richieste get.

Il batch HTTP integrato non influisce sulla quota. Ogni singola richiesta all'interno di un batch di richieste viene conteggiata come una richiesta rispetto alla quota. Ad esempio, una richiesta batch contenente 500 richieste insert viene addebitata come 500 richieste di metodi insert individuali.

Eccezione per il raggruppamento in batch di regioni dedicate: i metodi di raggruppamento in batch di regioni specializzate (batchCreate, batchUpdate, batchDelete) vengono conteggiati come una singola chiamata API rispetto al gruppo di quote merchant_regions, indipendentemente dal numero di operazioni sulle regioni contenute nel payload.

Per gestire efficacemente l'integrazione, devi esaminare il gruppo di quote specifico associato a ogni metodo API che intendi utilizzare. Puoi trovare questi dettagli nel metodo list delle quote. Per saperne di più, consulta Monitoraggio e visibilità.

Aggiorna policy

L'API Merchant applica le seguenti norme in termini di aggiornamenti:

  • Per impostazione predefinita, puoi aggiornare i tuoi prodotti fino a due volte al giorno. Dovresti distribuire le chiamate in modo uniforme nel corso della giornata per rispettare la quota al minuto.
  • Per impostazione predefinita, puoi aggiornare i tuoi sub-account solo fino a due volte al giorno. La tua quota di aggiornamento giornaliero dei subaccount è un limite aggregato basato sul numero totale di subaccount consentiti.
  • Per impostazione predefinita, puoi chiamare i metodi dell'origine dati per i tuoi subaccount, ad esempio list o create, solo fino a due volte al giorno per subaccount.

Quote di frequenza

Ogni gruppo di quote ha due tipi di limiti (e utilizzo giornaliero):

  • Limite giornaliero (quotaLimit): il numero massimo di richieste consentite al giorno. I limiti della quota giornaliera vengono reimpostati alle 12:00 UTC.
  • Limite al minuto (quotaMinuteLimit): il numero massimo di richieste consentite al minuto, che controlla la frequenza delle richieste. I limiti della quota al minuto utilizzano una finestra temporale, in cui il periodo di applicazione inizia dal momento in cui viene effettuata la prima chiamata API per quel metodo e quella risorsa. Ad esempio, se effettui una chiamata alle 10:01:30, la finestra della quota al minuto per quel metodo viene eseguita fino alle 10:02:30.
  • Utilizzo giornaliero (quotaUsage): il numero di richieste che sono già state effettuate e conteggiate ai fini del limite giornaliero per il giorno corrente. Se il campo non è presente, non è stata ancora utilizzata alcuna quota per questo gruppo.

Puoi trovare i tre campi descritti in precedenza (quotaLimit, quotaMinuteLimit e quotaUsage) nella risposta del metodo quotas.list.

I limiti giornalieri e al minuto specifici variano in modo significativo tra i diversi gruppi di quote. Le operazioni con un volume previsto più elevato o un costo di sistema inferiore, come la lettura dei dati di prodotto, in genere hanno limiti più elevati. Al contrario, le operazioni più intensive o sensibili, come le modifiche all'account, potrebbero avere limiti inferiori.

Allocazione e gerarchia delle quote

Questa sezione spiega per conto di chi l'API Merchant monitora e applica l'utilizzo della quota:

In generale, la quota viene addebitata in base all'utente che effettua la richiesta API.

  • Account autonomi: per gli account autonomi che autenticano una chiamata API, la richiesta viene conteggiata ai fini della quota dell'account.
    • Esempio: un commerciante Shoe Store A (ID account: 12345) esegue l'autenticazione utilizzando il proprio service account per chiamare products.insert scegliendo come target il proprio account (accounts/12345). La quota viene consumata dal pool di quote di Shoe Store A.
  • Account avanzati: l'autenticazione come account avanzato consuma la quota dal pool dell'account avanzato, anche se il target è un subaccount.
    • Esempio: un account "gestore" della vendita al dettaglio di un'agenzia (ID account avanzato: 12345) gestisce un subaccount Negozio di abbigliamento B (ID account: 11111). L'agenzia esegue l'autenticazione utilizzando le proprie credenziali e chiama products.insert scegliendo come target Negozio di abbigliamento B (accounts/11111). La quota viene consumata dal pool dell'agenzia principale (ID account avanzato: 12345), non dal pool del subaccount.
  • Subaccount: quando le chiamate API vengono autenticate utilizzando le credenziali di un subaccount, la quota viene addebitata al pool individuale di quel subaccount. Questo account funziona allo stesso modo di un account autonomo, anche se è gestito da un account avanzato principale.
    • Esempio: utilizzando la stessa configurazione di prima, se Clothing Store B (ID account: 11111) esegue l'autenticazione utilizzando le credenziali configurate specificamente per il proprio subaccount per chiamare products.insert scegliendo come target il proprio account (accounts/11111), la quota viene consumata dal pool di quote individuale di Clothing Store B, lasciando invariato il pool dell'agenzia principale.

Eccezioni alle regole generali

Esistono alcune eccezioni specifiche alle regole generali di allocazione della quota:

  • Accounts.list: la quota per questo metodo viene addebitata all'utente autenticato o al service account che effettua la chiamata, non all'ID account Merchant Center. L'utilizzo della quota non sarà visibile nella pagina di diagnostica dell'API Merchant Center standard. Se hai un account avanzato, ti consigliamo di utilizzare il metodo accounts.listSubaccounts, che viene conteggiato ai fini della quota di account avanzati.
  • Metodi Issueresolution: questi metodi vengono sempre conteggiati ai fini della quota per l'account per cui vengono richiesti i problemi, anche se la richiesta viene autenticata da un account diverso.

Gerarchia di allocazione

  • Servizi di shopping comparativo (CSS): i CSS sono siti web che aggregano le offerte di prodotti e indirizzano gli utenti ai siti web dei rivenditori per effettuare gli acquisti. Quando effettui chiamate API, le quote vengono applicate al gruppo di CSS, al dominio CSS, all'account o al subaccount specifico per cui esegui l'autenticazione.

    Esempi:

    • Un gruppo di CSS denominato Europe Shopping Group (ID account: 10001) vuole elencare i domini CSS associati. Eseguendo l'autenticazione con le proprie credenziali per effettuare questa chiamata API, la quota viene consumata direttamente dal pool di quote di Europe Shopping Group.
    • Un dominio CSS TopDeals CSS (ID account: 20002) esegue l'autenticazione per chiamare un metodo che ha come target uno dei suoi account commerciante associati (accounts/30003) per assegnare un'etichetta. La quota viene consumata dal pool di quote di TopDeals CSS, non da quello dell'account commerciante.

  • Marketplace: i marketplace sono piattaforme online che ospitano più commercianti individuali. Funzionano come account avanzati speciali che ti consentono di creare subaccount individuali per ciascuno dei tuoi venditori.

Il seguente diagramma mostra la gerarchia di gruppi di CSS, CSS, marketplace, account avanzati, account autonomi e subaccount.

Un gruppo di CSS è il livello di autenticazione generale, con la possibilità di avere singoli CSS al suo interno, account all'interno di questi e subaccount come livello più individuale.

Aggiustamento automatico della quota

L'API Merchant dispone di un sistema di gestione automatica delle quote per servizi specifici, che regola i limiti di quota per i commercianti in crescita in base all'utilizzo, all'offerta e alle dimensioni dell'account. L'API Merchant ricalcola queste quote ogni giorno.

I gruppi di quote inclusi negli aggiustamenti automatici delle quote sono:

Servizi prodotti

  • Tutti i gruppi di quote dei metodi correlati alle risorse products e productInputs.
  • La quota di chiamate giornaliere è generalmente impostata su un valore pari al doppio del numero di offerte del commerciante. Ciò presuppone che un commerciante potrebbe dover aggiornare ciascuno dei suoi prodotti fino a due volte al giorno.
  • I singoli prodotti possono essere aggiornati più di due volte, ma le chiamate API giornaliere complessive non possono superare la quota di chiamate giornaliere aggregate.

Servizi di contabilità

  • Tutti i gruppi di quote dei metodi correlati alle varie risorse granulari relative all'account nell'API Merchant.
  • La quota di chiamate giornaliere è impostata sul numero massimo di subaccount consentiti per l'account. In questo modo, è possibile effettuare fino a due chiamate di lettura per subaccount al giorno.

Servizi di origini dati

  • Tutti i gruppi di quote dei metodi correlati alle risorse correlate all'origine dati nell'API Merchant, come list o create, che un account avanzato esegue sui propri subaccount.
  • La quota di chiamate giornaliere è generalmente impostata su un valore pari al doppio del numero di subaccount dell'account avanzato. Ciò presuppone che un commerciante possa aggiornare ciascuna delle origini dati dei propri subaccount fino a due volte al giorno.

Solo i servizi descritti in precedenza hanno aggiustamenti automatici delle quote. Altri servizi hanno una quota predefinita e gli eventuali aumenti devono essere richiesti manualmente. Per saperne di più, consulta la sezione Procedura di aumento della quota.

Cosa succede quando le quote vengono superate

Una volta superata una quota, verranno visualizzati errori nelle risposte dell'API e nella pagina Diagnostica del tuo account Merchant Center:

  • Al minuto: quota/request_rate_too_high
{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}
  • Al giorno: quota/daily_limit_exceeded
{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

I seguenti errori sono limiti di Merchant Center e non sono correlati alle quote dell'API Merchant. Puoi provare a richiedere una quota aggiuntiva di articoli, feed o subaccount:

  • too_many_items: quota del commerciante superata
  • too_many_subaccounts: è stato raggiunto il numero massimo di subaccount

Monitoraggio e visibilità

Per controllare le quote di chiamata e l'utilizzo attuali di un account, chiama quotas.list con il nome dell'account.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Sostituisci quanto segue:

  • ACCOUNT_ID: il tuo ID Merchant Center
  • ACCESS_TOKEN: il token di autorizzazione per effettuare la chiamata API

Se la richiesta va a buon fine, l'API restituisce un elenco di risorse quotaGroups contenenti la risorsa name del gruppo di quote, le diverse quote e i metodi a cui si applica la quota del gruppo.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Procedura di aumento della quota

Per richiedere una quota aggiuntiva, apri il modulo di contatto dell'assistenza, seleziona Richiesta di aumento della quota per il campo obbligatorio "Qual è il problema/la domanda" e compila tutti i campi obbligatori, inclusi l'ID Merchant Center, i metodi target e la motivazione aziendale.

  • Per le risorse con quote automatiche (products, accounts e datasources per gli account avanzati): puoi richiedere solo un aumento temporaneo per scenari speciali, come il lancio in un nuovo mercato o durante i periodi di acquisti con traffico elevato. Non accettiamo aumenti permanenti della quota per questi tipi di risorse.
  • Per tutte le altre risorse senza quote automatiche: richiedi aumenti delle quote in base alle tue esigenze.

Ti consigliamo di controllare periodicamente le quote per assicurarti di avere una quota sufficiente per la tua implementazione e di vedere come viene modificata automaticamente. Utilizza il metodo quotas.list per visualizzare il limite di quota giornaliero, il limite di minuti e l'utilizzo giornaliero corrente per ogni gruppo di metodi API.

Best practice

L'implementazione di queste best practice contribuisce a garantire che l'integrazione venga eseguita senza problemi, evita errori di quota imprevisti e utilizza le risorse di Merchant Center in modo efficiente.

Ottimizza la distribuzione delle richieste

  • Distribuisci le richieste in modo uniforme: evita di inviare grandi quantità di richieste contemporaneamente. Distribuisci le chiamate API giornaliere in modo uniforme nel corso della giornata per rispettare i limiti di quota al minuto (quotaMinuteLimit).
  • Limitazione proattiva: implementa la limitazione di frequenza lato client (throttling) nella tua applicazione. Non fare affidamento solo sui server di Google per rifiutare il traffico in eccesso. Controlla il tasso di richieste alla fonte.

Gestione degli errori ottimale

  • Gestisci l'errore HTTP 429: la tua applicazione deve essere preparata a gestire gli errori 429 Too Many Requests (quota/request_rate_too_high).
  • Backoff esponenziale con jitter: quando riprovi le richieste non riuscite (soprattutto dopo un errore 429), utilizza il backoff esponenziale (tempi di attesa crescenti) e aggiungi il "jitter" (ritardo casuale). Il jitter impedisce le "tempeste di nuovi tentativi", in cui più istanze client riprovano esattamente nello stesso momento, sovraccaricando nuovamente il server.
  • Rispetta i suggerimenti per i nuovi tentativi: se la risposta dell'API contiene dettagli o intestazioni per i nuovi tentativi, utilizzali per determinare quando riprendere le chiamate.

Riduci al minimo le chiamate ridondanti

  • Evita chiamate obsolete (404 NOT_FOUND): evita di richiedere o eliminare risorse che non esistono più. Anche le chiamate non riuscite consumano la quota API. Monitora gli errori NOT_FOUND in Diagnostica API di Merchant Center per rilevare il monitoraggio dello stato non aggiornato o il polling non necessario.
  • Verifica prima dell'aggiornamento: prima di inviare una richiesta di aggiornamento, controlla se i dati sono effettivamente cambiati. Evita di inviare aggiornamenti che scrivono gli stessi valori.
  • Utilizza la memorizzazione nella cache: memorizza nella cache le risposte di lettura (ad es. dettagli del prodotto, impostazioni) localmente, se opportuno, per evitare chiamate get o list ripetitive per dati invariati.
  • Account avanzati e subaccount: se hai un account avanzato, esegui l'autenticazione a livello di account avanzato se vuoi che le chiamate vengano conteggiate nel pool condiviso degli account avanzati.
  • Utilizza listSubaccounts: per gli account avanzati, utilizza accounts.listSubaccounts anziché accounts.list. La quota accounts.list viene addebitata all'utente chiamante (non all'ID MC) e non è visibile nella diagnostica standard. listSubaccounts viene conteggiato ai fini del calcolo della quota MCA.
Indietro
Overview
Avanti
Merchant Center limits