Quote e limiti delle API

L'API Google Ads applica limiti alle operazioni API, ad esempio il numero di operazioni che possono essere inviate in una singola richiesta di modifica. La tabella seguente riassume alcuni dei limiti e delle quote importanti di cui tenere conto.

Tipo di richiesta, limitazione e codice di errore
Operazioni con livello di accesso di test 15.000 operazioni API al giorno per gli account di test RESOURCE_EXHAUSTED
Operazioni con livello di accesso Explorer 2880 operazioni API al giorno per gli account di produzione
15.000 operazioni API al giorno per gli account di test 		RESOURCE_EXHAUSTED
Operazioni con livello di accesso di base 15.000 operazioni API al giorno sia per gli account di test sia per quelli di produzione RESOURCE_EXHAUSTED
Operazioni con livello di accesso standard Operazioni API giornaliere illimitate sia per gli account di test sia per quelli di produzione N/D
Richieste di modifica 10.000 operazioni di modifica per richiesta TOO_MANY_MUTATE_OPERATIONS
Pianificazione delle richieste di servizio 1 QPS RESOURCE_EXHAUSTED
Richieste del servizio di caricamento delle conversioni 2000 conversioni per richiesta TOO_MANY_CONVERSIONS_IN_REQUEST
Richieste di servizio relative a fatturazione e budget dell'account 1 operazione per richiesta di modifica TOO_MANY_MUTATE_OPERATIONS

Limiti giornalieri delle operazioni API

I limiti di utilizzo giornaliero dell'API si basano sul numero di operazioni API eseguite dal tuo progetto Google Cloud. Le operazioni API sono la somma totale delle richieste Search e SearchStream, delle singole operazioni di mutazione e di altre richieste di servizio. I limiti per le operazioni API giornaliere dipendono dal livello di accesso API del tuo progetto Google Cloud. La guida ai livelli di accesso e all'utilizzo consentito descrive i limiti specifici delle operazioni API per ogni livello di accesso.

Le richieste che violano questi limiti vengono rifiutate con l'errore: RESOURCE_EXHAUSTED.

Limitazioni di gRPC

Tutte le librerie client dell'API Google Ads utilizzano gRPC per generare richieste e risposte. Per impostazione predefinita, gRPC ha una dimensione del messaggio di 4 MB, ma le nostre librerie client impostano la dimensione massima del messaggio su 64 MB per aumentare l'efficienza.

Le risposte non devono superare questo limite. Ad esempio, una richiesta di ricerca che include molti campi può generare una risposta di dimensioni superiori a 64 MB. Per evitare questo limite, puoi ridurre il numero di campi selezionati o utilizzare lo streaming. Per le modifiche, invia meno operazioni per richiesta.

Le richieste che violano questa limitazione non generano un GoogleAdsError, ma generano un errore RESOURCE_EXHAUSTED (codice gRPC 8/HTTP 429). Consulta l'elenco dei codici e dei messaggi di errore gRPC.

Richieste di modifica

Oltre a essere conteggiata nella quota di operazioni giornaliere dell'utente, una richiesta di modifica non può contenere più di 10.000 operazioni di modifica per richiesta. Le richieste che violano questa limitazione vengono rifiutate con l'errore: TOO_MANY_MUTATE_OPERATIONS.

Di seguito sono riportati ulteriori limiti e considerazioni per servizi e tipi di richieste specifici.

Richieste di ricerca

Una richiesta Search o SearchStream viene conteggiata come un'operazione rispetto alla quota di operazioni giornaliere dell'utente. Una richiesta SearchStream viene conteggiata come un'operazione API, indipendentemente dal numero di batch.

Richieste impaginate

Le richieste impaginate (ad esempio, le richieste che contengono un next_page_token valido) non vengono conteggiate ai fini della quota di operazioni giornaliere di un utente. Tuttavia, le richieste di impaginazione che contengono un token di pagina scaduto o non valido genereranno un'eccezione e verranno conteggiate ai fini della quota di operazioni giornaliere.

Per maggiori dettagli sull'impaginazione, consulta Paginazione dei risultati.

Altri tipi di richieste

Una richiesta che non è una richiesta Mutate, Search o SearchStream viene conteggiata come un'operazione rispetto alla quota di operazioni giornaliere dell'utente.

Ecco alcuni esempi di queste richieste:

Richieste che restituiscono eccezioni API

Le richieste rifiutate con un codice GoogleAdsFailure vengono comunque conteggiate ai fini della quota di operazioni giornaliere dell'utente.

Le richieste che non vanno a buon fine, ma non restituiscono un GoogleAdsFailure, ad esempio a causa di un errore a livello di rete, non verranno conteggiate nella quota di operazioni giornaliere dell'utente, poiché non raggiungerebbero mai il servizio. Un esempio è un errore di connessione di rete.

Servizio di pianificazione delle parole chiave

A causa dei costi e della complessità, i seguenti metodi del servizio Keyword Planning sono soggetti a limiti separati rispetto ad altri tipi di richieste.

Tieni presente questi limiti quando crei un piano per le parole chiave.

Oggetto del piano per le parole chiave Numero massimo
KeywordPlan per account 10.000
KeywordPlanAdGroup per KeywordPlan 200
KeywordPlanAdGroupKeyword per KeywordPlan 10.000
KeywordPlanCampaignKeyword (parole chiave escluse) per KeywordPlan 1000
KeywordPlanCampaign per KeywordPlan 1

Servizio di insight sul pubblico

I seguenti metodi all'interno di AudienceInsightsService sono soggetti a limiti di quota specifici.

Servizio di caricamento delle conversioni

Servizio di caricamento degli aggiustamenti delle conversioni

Regole per i valori di conversione

Se per l'account esiste già un ConversionValueRuleSet con un attachment_type di CUSTOMER, devi aggiungere eventuali nuove regole per i valori di conversione a questo insieme per attivarle. Se non esiste un set di regole per i valori di conversione, devi crearne uno e aggiungervi le regole per i valori di conversione, come descritto in Crea set di regole.

Servizi di fatturazione e budget dell'account

  • Le modifiche possono essere apportate solo agli account configurati per la fatturazione mensile.

    Le richieste che violano questa limitazione vengono rifiutate con l'errore: MUTATE_NOT_ALLOWED.

  • Per le richieste di modifica è consentita una sola operazione (1).

    Le richieste che violano questa limitazione vengono rifiutate con l'errore: TOO_MANY_MUTATE_OPERATIONS.

  • Devi attendere almeno 12 ore tra una modifica e l'altra del budget dell'account (AccountBudget o AccountBudgetProposal) per lo stesso account. Se apporti modifiche prima che siano trascorse 12 ore, potrebbero verificarsi errori non recuperabili che possono essere risolti solo dal rappresentante dell'account Google Ads.

Inviti agli account cliente

I nuovi utenti possono essere invitati ad accedere agli account cliente esistenti con CustomerUserAccessInvitationService. Poiché questa funzionalità invia email di invito ad altri utenti, potrebbe essere utilizzata in modo improprio e pertanto esistono limitazioni al suo comportamento:

  • Gli utenti non possono ricevere più di un invito in attesa per lo stesso account cliente. Se viene effettuata una richiesta successiva per inviare un invito a un utente che ha già un invito in attesa, viene restituito questo errore: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Gli account cliente non possono avere più di 70 inviti in attesa contemporaneamente. Se viene inviata una richiesta che causa il superamento di questo valore, viene restituito questo errore: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Dati utente

I dati utente vengono gestiti con l'UserDataService e l'OfflineUserDataJobService.

Ogni oggetto UserData in un'operazione create o remove riguarda un singolo utente finale. Il campo user_identifiers all'interno di un singolo oggetto UserData è limitato a un massimo di 20 identificatori. Il superamento di questo limite in un singolo oggetto UserData genererà un errore OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS o UserDataError.TOO_MANY_USER_IDENTIFIERS.

Gestisci gli utenti con più di 20 identificatori

Se un singolo utente finale possiede più di 20 identificatori che devi caricare, devi distribuirli tra più oggetti UserData. Per assicurarti che Google possa associare tutti questi identificatori allo stesso utente finale, ogni oggetto UserData per quell'utente deve includere almeno un user_identifier comune, ad esempio lo stesso hashed_email, hashed_phone_number o third_party_user_id. Google utilizza questi identificatori condivisi per collegare e unire le informazioni delle operazioni UserData separate al profilo utente finale corretto.

Se utilizzi PII come email o numeri di telefono sottoposti ad hashing, assicurati che siano normalizzati e sottoposti ad hashing in base ai requisiti dell'API Google Ads (SHA-256, lettere minuscole, senza spazi vuoti) per evitare errori di collegamento.

Ad esempio, se un utente ha 30 indirizzi email, puoi inviare due oggetti UserData che condividono un third_party_user_id comune (inserendo thirdPartyUserId più le email da 1 a 19 nel primo oggetto per rimanere entro il limite di 20 identificatori e thirdPartyUserId più le email da 20 a 30 nel secondo):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

Il limite totale per user_identifiers in tutte le operazioni in un singolo AddOfflineUserDataJobOperationsRequest è 100.000 (un OfflineUserDataJob può accettare più chiamate AddOfflineUserDataJobOperationsRequest, fino a un massimo consigliato di 1.000.000 di operazioni per job). Per i caricamenti sincroni che utilizzano UploadUserDataRequest (UserDataService.UploadUserData), ogni richiesta è limitata a un massimo di 10 operazioni e 100 user_identifiers nell'intera richiesta.

Altri tipi di limiti

Un campo ripetuto, ad esempio un elenco di operazioni, che contiene troppi elementi in una richiesta può generare l'errore: REQUEST_SIZE_LIMIT_EXCEEDED. Questo stesso messaggio di errore può essere dovuto anche ad altri problemi.

Se riscontri questa limitazione e stai effettuando richieste che utilizzano un campo ripetuto, prova a ridurre il numero di elementi nel campo ripetuto suddividendo l'elenco di operazioni in più richieste di modifica.

Quando esegui una query GAQL, il numero massimo di elementi all'interno di una clausola IN è 20.000. Se superi questo limite, viene restituito un errore FILTER_HAS_TOO_MANY_VALUES.

Indietro
Panoramica
Avanti
Limiti del sistema