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 riepiloga alcuni dei limiti e delle quote importanti da tenere presenti.

Limiti di 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 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 potrebbe 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 genereranno un GoogleAdsError, ma 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 ai fini della quota di operazioni giornaliere dell'utente, una richiesta mutate non può contenere più di 10.000 operazioni mutate per richiesta. Le richieste che violano questa limitazione vengono rifiutate con l'errore: TOO_MANY_MUTATE_OPERATIONS.

Di seguito sono riportati 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 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 paginazione che contengono un token di pagina scaduto o non valido genereranno un'eccezione e verranno conteggiate ai fini della quota di operazioni giornaliere.

Per ulteriori dettagli sull'impaginazione, consulta Scorrere i risultati.

Altri tipi di richieste

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

Ecco alcuni esempi di queste richieste:

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

Richieste che restituiscono eccezioni API

Le richieste rifiutate con un GoogleAdsFailure vengono comunque conteggiate ai fini del calcolo della quota giornaliera di operazioni dell'utente.

Le richieste non riuscite che non restituiscono un errore GoogleAdsFailure, ad esempio a causa di un errore a livello di rete, non verranno conteggiate ai fini della quota di operazioni giornaliere dell'utente, in quanto le richieste non raggiungeranno mai il servizio. Un esempio di questo è un errore di connettività di rete.

Servizio di pianificazione delle parole chiave

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

• Limitata a 1 richiesta al secondo per ID cliente:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  Le richieste che violano queste limitazioni vengono rifiutate con l'errore: RESOURCE_EXHAUSTED.

• 1 QPS viene calcolato come 60 richieste ogni 60 secondi.

• Limitato a 2 richieste al secondo per ID cliente:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

Servizio Statistiche sul pubblico

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

• Limitato a circa 200 richieste al giorno per ID cliente:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• Limitato a 2 richieste al secondo per progetto Google Cloud:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

Servizio di caricamento delle conversioni

• Limitato a 2000 conversioni di chiamata o clic per richiesta:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

Servizio di caricamento degli aggiustamenti delle conversioni

• Limitato a 2000 aggiustamenti delle conversioni per richiesta:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

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

Regole per i valori di conversione

• Limite di 100.000 regole per i valori di conversione per account.

  Le richieste che violano questo limite vengono rifiutate con l'errore ResourceCountLimitExceededError.ACCOUNT_LIMIT.

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 affinché diventino attive. Se non esiste un insieme di regole per i valori di conversione, 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.

• Per le richieste di modifica è consentita solo 1 operazione.

  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. L'apporto di modifiche prima che siano trascorse 12 ore potrebbe comportare errori irreversibili che possono essere risolti solo dal rappresentante del tuo account Google Ads.

Inviti agli account cliente

I nuovi utenti possono essere invitati in account cliente esistenti con il CustomerUserAccessInvitationService. Poiché questa funzionalità invia email di invito ad altri utenti, ha il potenziale di essere utilizzata in modo improprio, pertanto 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 con 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 genera un errore OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS o UserDataError.TOO_MANY_USER_IDENTIFIERS.

Gestire 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, come 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 dell'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, minuscole, nessuno spazio bianco) 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 rispettare 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 utilizzando 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. 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 dividendo 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.