Quote e limiti delle API

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

Tipo di richiesta, limitazione e codice di errore
Operazioni con livello di accesso 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 Basic 15.000 operazioni API al giorno per gli account di test e di produzione RESOURCE_EXHAUSTED
Operazioni con livello di accesso Standard Operazioni API giornaliere illimitate per gli account di test e di produzione N/D
Richieste di modifica 10.000 operazioni di modifica per richiesta TOO_MANY_MUTATE_OPERATIONS
Richieste del servizio di pianificazione 1 QPS RESOURCE_EXHAUSTED
Richieste del servizio di caricamento delle conversioni 2000 conversioni per richiesta TOO_MANY_CONVERSIONS_IN_REQUEST
Richieste dei servizi di fatturazione e budget dell'account 1 operazione per richiesta di modifica TOO_MANY_MUTATE_OPERATIONS

Limiti delle operazioni API giornaliere

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 modifica 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 Livelli di accesso e 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 dei messaggi di 4 MB, ma le nostre librerie client impostano la dimensione massima dei messaggi 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 rispetto alla 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 descritti limiti e considerazioni aggiuntivi per servizi e tipi di richieste specifici.

Cerca richieste

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 paginate

Le richieste paginate (ad esempio, le richieste che contengono un next_page_token valido) non vengono conteggiate rispetto alla quota di operazioni giornaliere di un utente. Tuttavia, le richieste di paginazione che contengono un token di pagina scaduto o non valido genereranno un'eccezione e verranno conteggiate rispetto alla quota di operazioni giornaliere.

Per ulteriori dettagli sulla paginazione, consulta la sezione 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 GoogleAdsFailure vengono comunque conteggiate rispetto alla quota di operazioni giornaliere dell'utente.

Le richieste non riuscite che non restituiscono un GoogleAdsFailure, ad esempio a causa di un errore a livello di rete, non verranno conteggiate rispetto alla quota di operazioni giornaliere dell'utente, poiché le richieste non raggiungeranno mai il servizio. Un esempio è un errore di connettività di rete.

Servizio di pianificazione delle parole chiave

A causa del costo e della complessità, i seguenti metodi del servizio di pianificazione delle parole chiave sono soggetti a limiti separati rispetto ad altri tipi di richieste.

Tieni presente questi limiti quando crei un piano di parole chiave.

Oggetto del piano di 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 Statistiche sul pubblico

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

Servizio di caricamento delle conversioni

Servizio di caricamento delle modifiche alle conversioni

Regole per i valori di conversione

Se per l'account esiste già un ConversionValueRuleSet con un attachment_type di CUSTOMER, devi aggiungere tutte le nuove regole per i valori di conversione a questo insieme affinché diventino attive. Se non esiste un insieme di regole per i valori di conversione di questo tipo, devi crearne uno e aggiungervi le regole per i valori di conversione come descritto in Creare insiemi 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.

  • È consentita solo 1 operazione per le richieste di modifica.

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

  • Devi attendere almeno 12 ore tra le modifiche al budget dell'account (AccountBudget o AccountBudgetProposal) dello stesso account. Se apporti modifiche prima che siano trascorse 12 ore, potresti riscontrare errori non recuperabili che possono essere risolti solo dal rappresentante dell'account Google Ads.

Inviti agli account cliente

I nuovi utenti possono essere invitati agli account cliente esistenti con il CustomerUserAccessInvitationService. Poiché questa funzionalità invia email di invito ad altri utenti, potrebbe essere utilizzata in modo improprio. Per questo motivo, il suo comportamento è soggetto a limitazioni:

  • 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 UserDataService e OfflineUserDataJobService.

Ogni oggetto UserData in un'operazione create o remove si riferisce a un singolo utente finale. Il campo user_identifiers all'interno di un singolo oggetto UserData è limitato a un massimo di 20 identificatori. Se superi questo limite in un singolo UserData oggetto, verrà generato un OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS o UserDataError.TOO_MANY_USER_IDENTIFIERS errore.

Gestire gli utenti con più di 20 identificatori

Se un singolo utente finale possiede più di 20 identificatori che devi caricare, devi distribuirli su 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 indirizzi 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, 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 di una singola 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 in tutta la 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. Lo 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 delle 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