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 esercitare un carico eccessivo sul 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 i 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 le origini dati degli elenchi accounts.dataSources.list ha un proprio gruppo di quote dedicato.
  • Più metodi per gruppo (raggruppamento): 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 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 una volta rispetto alla quota. Ad esempio, una richiesta batch contenente 500 richieste insert viene addebitata come 500 singole richieste del metodo insert.

Eccezione per il batch di regioni dedicato: i metodi batch di regioni specializzati (batchCreate, batchUpdate, batchDelete) vengono conteggiati come una singola chiamata API rispetto al gruppo di quote merchant_regions, indipendentemente dal numero di operazioni di regione 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 di elenco 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. Devi distribuire uniformemente le chiamate durante la giornata per rispettare la quota al minuto.
  • Per impostazione predefinita, puoi aggiornare i tuoi subaccount solo fino a due volte al giorno. La quota di aggiornamento giornaliera dei subaccount è un limite aggregato basato sul numero totale di subaccount consentiti.
  • Per impostazione predefinita, puoi chiamare i metodi di 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 di quota giornalieri 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 di quota al minuto utilizzano una finestra mobile, in cui il periodo di applicazione inizia dal momento in cui viene effettuata la prima chiamata API per il metodo e la risorsa. Ad esempio, se effettui una chiamata alle 10:01:30, la finestra della quota al minuto per quel metodo dura fino alle 10:02:30.
  • Utilizzo giornaliero (quotaUsage): il numero di richieste che sono già state effettuate e conteggiate rispetto al limite giornaliero per il giorno corrente. Se il campo non è presente, significa che non è stata ancora utilizzata alcuna quota per questo gruppo.

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

I limiti giornalieri e al minuto specifici variano notevolmente 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 dell'account, potrebbero avere limiti inferiori.

Assegnazione 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 rispetto alla quota dell'account.
    • Esempio: un commerciante Shoe Store A esegue l'autenticazione utilizzando il proprio account di servizio per chiamare products.insert con target il proprio account (accounts/12345). La quota viene utilizzata dal pool di quote di Shoe Store A's.
  • Account avanzati: l'autenticazione come account avanzato utilizza la quota del pool dell'account avanzato, anche quando il target è un subaccount.
    • Esempio: un'agenzia Retail Management Account (ID account avanzato: 12345) gestisce un subaccount Clothing Store B (ID account: 11111). L'agenzia esegue l'autenticazione utilizzando le proprie credenziali e chiama products.insert con target Clothing Store B (accounts/11111). La quota viene utilizzata 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 del subaccount. Il funzionamento è lo stesso di un account autonomo, anche se è gestito da un account avanzato principale.
    • Esempio: utilizzando la stessa configurazione precedente, se Clothing Store B (ID account: 11111) esegue l'autenticazione utilizzando le credenziali configurate appositamente per il proprio subaccount per chiamare products.insert con target il proprio account (accounts/11111), la quota viene utilizzata dal pool di quote individuale di Clothing Store B's, lasciando intatto il pool dell'agenzia principale.

Eccezioni alle regole generali

Esistono alcune eccezioni specifiche che si applicano alle regole generali di assegnazione delle quote:

  • 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 standard dell'API Merchant Center. Se hai un account avanzato, ti consigliamo di utilizzare il accounts.listSubaccounts metodo, che viene conteggiato rispetto alla quota degli account avanzati.
  • Metodi di risoluzione dei problemi: questi metodi vengono sempre conteggiati rispetto alla quota dell'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 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 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 utilizzata direttamente dal pool di quote di Europe Shopping Group.
    • Un dominio CSS TopDeals CSS (ID account: 20002) esegue l'autenticazione per chiamare un metodo con target uno dei suoi account commerciante associati (accounts/30003) per assegnare un'etichetta. La quota viene utilizzata dal pool di quote di TopDeals CSS, non dal pool dell'account commerciante.

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

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

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

Regolazione automatica 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 nelle regolazioni automatiche delle quote sono:

Servizi prodotti

  • Tutti i gruppi di quote dei metodi correlati alle risorse products e productInputs.
  • La quota di chiamata giornaliera è in genere impostata su 2 volte la quota di offerta di cui dispone il commerciante. Si presume che un commerciante possa 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 chiamata giornaliera aggregata.

Servizi account

  • Tutti i gruppi di quote dei metodi correlati alle varie risorse granulari correlate all'account nell'API Merchant.
  • La quota di chiamata giornaliera è impostata sul numero massimo di subaccount consentiti per l'account. Ciò consente fino a due chiamate di lettura per subaccount al giorno.

Servizi di origine dati

  • Tutti i gruppi di quote dei metodi correlati alle risorse correlate all'origine dati nell'API Merchant, ad esempio list o create, che un account avanzato esegue sui propri subaccount.
  • La quota di chiamata giornaliera è in genere impostata su 2 volte il numero di subaccount di cui dispone l'account avanzato. Si presume che un commerciante possa aggiornare le origini dati di ciascuno dei suoi subaccount fino a due volte al giorno.

Solo i servizi descritti in precedenza hanno regolazioni automatiche delle quote. Gli altri servizi hanno una quota predefinita e gli 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, gli errori verranno visualizzati nelle risposte API e nella pagina di diagnostica all'interno 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 correnti per 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 quotaGroups risorse 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 Contatta l'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 di destinazione e la giustificazione commerciale.

  • 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 le stagioni di shopping con traffico elevato. Non accettiamo aumenti permanenti delle quote per questi tipi di risorse.
  • Per tutte le altre risorse senza quote automatiche: richiedi aumenti di quota in base alle esigenze.

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

Best practice

L'implementazione di queste best practice contribuisce a garantire il buon funzionamento dell'integrazione, a evitare errori di quota imprevisti e a utilizzare in modo efficiente le risorse di Merchant Center.

Ottimizzare la distribuzione delle richieste

  • Distribuire uniformemente le richieste: evita di inviare grandi burst di richieste. Distribuisci uniformemente le chiamate API giornaliere durante la giornata per rimanere entro i limiti di quota al minuto (quotaMinuteLimit).
  • Limitazione proattiva: implementa la limitazione della frequenza lato client (throttling) nella tua applicazione. Non fare affidamento esclusivamente sui server di Google per rifiutare il traffico in eccesso. Controlla il tasso di richieste all'origine.

Gestione degli errori con grazia

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

Ridurre al minimo le chiamate ridondanti

  • Evitare chiamate obsolete (404 NOT_FOUND): evita di richiedere o eliminare risorse che non esistono più. Anche le chiamate non riuscite utilizzano la quota API. Monitora gli errori NOT_FOUND nella diagnostica dell'API Merchant Center per rilevare il monitoraggio dello stato obsoleto o il polling non necessario.
  • Verificare prima dell'aggiornamento: prima di inviare una richiesta di aggiornamento, verifica se i dati sono effettivamente cambiati. Evita di inviare aggiornamenti che scrivono gli stessi valori.
  • Utilizzare la memorizzazione nella cache: memorizza nella cache le risposte di lettura (ad es. dettagli del prodotto, impostazioni) localmente, quando appropriato, per evitare chiamate get o list ripetitive per i 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 rispetto al pool condiviso degli account avanzati.
  • Utilizzare listSubaccounts: per gli account avanzati, utilizzare 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 rispetto alla quota dell'AMC.
Indietro
Overview
Avanti
Merchant Center limits