Best practice e limitazioni

Tieni in considerazione queste linee guida quando utilizzi BatchJobService.

Migliorare il throughput

  • È preferibile un numero ridotto di job più grandi rispetto a molti job più piccoli.

  • Ordina le operazioni caricate per tipo di operazione (ad eccezione delle operazioni interdipendenti che devono essere raggruppate consecutivamente in sub-batch atomici). Ad esempio, se il tuo lavoro contiene operazioni per aggiungere campagne standard, gruppi di annunci e criteri dei gruppi di annunci, ordina le operazioni nel caricamento in modo che tutte le operazioni della campagna vengano eseguite per prime, seguite da tutte le operazioni del gruppo di annunci e infine da tutte le operazioni dei criteri del gruppo di annunci.

  • All'interno di operazioni dello stesso tipo, può migliorare il rendimento raggruppandole per risorsa padre. Ad esempio, se hai una serie di oggetti AdGroupCriterionOperation, è più efficiente raggruppare le operazioni per gruppo di annunci anziché mescolare operazioni che influiscono sui criteri del gruppo di annunci in gruppi di annunci diversi.

Atomicità nella suddivisione dei batch

L'API Google Ads suddivide le operazioni in un job batch inviato in batch più piccoli per l'elaborazione. Mentre i batch secondari standard vengono eseguiti con l'attivazione dell'errore parziale, i batch secondari per determinate operazioni interdipendenti vengono elaborati in modo atomico come una singola transazione:

Per i sottogruppi di creazione di AssetGroup e Performance Max Campaign (fino a 1000 operazioni totali per sottogruppo; le operazioni create secondarie oltre 999 vengono trasferite al sottogruppo non atomico successivo):

  • L'operazione create principale (resource_name su AssetGroup o Campaign) e le relative operazioni create secondarie consecutive (asset_group su AssetGroupAsset o campaign su CampaignAsset) devono specificare lo stesso ID temporaneo negativo.
  • Inserisci le operazioni di AssetOperation (create) prerequisito per le nuove risorse Asset prima del AssetGroupOperation o CampaignOperation (create) padre, mai tra il create padre e le operazioni di collegamento figlio create (che chiuderebbero immediatamente il batch secondario atomico e separerebbero la creazione della risorsa padre dalle risorse collegate).

Quando un batch secondario atomico non va a buon fine, il BatchJobResult.status dell'operazione che ha causato l'errore contiene l'errore di convalida sottostante, mentre le operazioni rimanenti nel batch secondario vengono eseguite con rollback con l'errore di transazione corrispondente per il batch secondario. Esamina le voci adiacenti BatchJobResult che condividono lo stesso ID AdGroup, AssetGroup o Campaign per identificare l'errore di causa principale.

Se le operazioni correlate in uno di questi gruppi non vengono aggiunte consecutivamente, l'API Google Ads le suddivide in batch secondari separati, causando il mancato rispetto dei requisiti minimi delle risorse o lasciando incompleti gli alberi dei gruppi di schede. Per maggiori dettagli, consulta Utilizzare i filtri dei gruppi di schede nei job batch e Elaborazione batch di Performance Max.

Raggruppamento logico

Quando modifichi una gerarchia di targeting dei prodotti (AssetGroupListingGroupFilterOperation nelle campagne Performance Max o AdGroupCriterionOperation nelle campagne Shopping) o crei un nuovo AssetGroup o Campaign Performance Max, raggruppa tutte le operazioni di targeting della stessa risorsa principale (AssetGroup, AdGroup o Campaign) in sequenza. Ciò riduce la contesa dei blocchi di backend e mantiene uniti gli alberi interdipendenti.

Coerenza dei dati

Poiché gli alberi dei filtri dei gruppi di schede e i requisiti degli asset Performance Max vengono convalidati alla fine di ogni transazione di sub-batch atomico, evita di dividere gli aggiornamenti alla stessa risorsa principale in intervalli discontinui in un job o in job simultanei.

Evitare problemi di concorrenza

  • Quando invii più job simultanei per lo stesso account, riduci la probabilità che i job operino sugli stessi oggetti contemporaneamente mantenendo dimensioni elevate dei job. Molti job non completati con lo stato RUNNING che tentano di modificare lo stesso insieme di oggetti possono portare a condizioni di deadlock, con conseguente rallentamento e persino errori del job.

  • Non inviare più operazioni che modificano lo stesso oggetto nello stesso job, in quanto il risultato può essere imprevedibile.

Recuperare i risultati in modo ottimale

  • Non eseguire il polling dello stato del job troppo spesso, altrimenti rischi di raggiungere il limite di frequenza e ricevere errori.

  • Lascia page_size non impostato (o impostalo sul valore massimo di 1000) quando chiami ListBatchJobResults per ridurre al minimo i round trip di paginazione e imposta response_content_type solo su MUTABLE_RESOURCE se la tua applicazione ispeziona i campi delle risorse restituite oltre resource_name.

  • L'ordine dei risultati è lo stesso dell'ordine di caricamento.

Indicazioni aggiuntive per l'utilizzo

  • Puoi impostare un limite superiore per la durata di esecuzione di un job batch prima che venga annullato. Quando crei un nuovo job batch, imposta il campo metadata.execution_limit_seconds sul limite di tempo che preferisci, in secondi. Se metadata.execution_limit_seconds non è impostato, non è previsto un limite di tempo predefinito.

  • Sebbene il limite del protocollo sia di 10.000 operazioni per richiesta, ti consigliamo di aggiungere non più di 1000 operazioni per AddBatchJobOperationsRequest e di utilizzare sequence_token per caricare il resto delle operazioni nello stesso job. A seconda delle dimensioni delle operazioni, l'invio di un numero eccessivo di operazioni in un singolo AddBatchJobOperationsRequest può causare un errore BatchJobError.REQUEST_TOO_LARGE. Puoi gestire questo errore riducendo il numero di operazioni e riprovando a AddBatchJobOperationsRequest.

Limitazioni

  • Ogni BatchJob supporta fino a un milione di operazioni. Il superamento di questo limite durante la chiamata di AddBatchJobOperations restituisce un errore ResourceCountLimitExceededError.RESOURCE_LIMIT (con ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB in ErrorDetails.resource_count_details).

  • Ogni account può avere fino a 100 job attivi o in attesa contemporaneamente. Il superamento di questo limite durante la creazione di un job batch con MutateBatchJob restituisce un errore ResourceCountLimitExceededError.RESOURCE_LIMIT (con ResourceLimitType.BATCH_JOBS_PER_CUSTOMER in ErrorDetails.resource_count_details).

  • I lavori in attesa più vecchi di 7 giorni vengono rimossi automaticamente.

  • Ogni AddBatchJobOperationsRequest ha un limite rigido di 10.000 operazioni di modifica per richiesta. Il superamento di 10.000 operazioni in una singola richiesta restituisce un errore BatchJobError.REQUEST_TOO_LARGE.

  • Per il campo page_size in ListBatchJobResultsRequest:

  • Ogni AddBatchJobOperationsRequest ha una dimensione massima di 41.937.920 byte. Se superi questo limite, ricevi un errore BatchJobError.REQUEST_TOO_LARGE (o un errore INTERNAL_ERROR se il rifiuto avviene a livello di trasporto). Puoi determinare le dimensioni serializzate della richiesta prima dell'invio e intraprendere l'azione appropriata se è troppo grande:

    Java

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C#

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

Dimensioni di una singola operazione di modifica

Sebbene la richiesta complessiva possa essere di massimo 41.937.920 byte, la dimensione serializzata di un singolo MutateOperation all'interno del batch è limitata a 10.484.504 byte (10 MiB meno 1256 byte). Il superamento di questo limite restituisce un errore BatchJobError.REQUEST_TOO_LARGE. Tieni presente che, sebbene la documentazione di riferimento per BatchJobError.REQUEST_TOO_LARGE citi la soglia di 10.484.504 byte, AddBatchJobOperations restituisce lo stesso codice di errore quando viene superata una delle tre soglie di richiesta (41.937.920 byte totali della richiesta, 10.484.504 byte per singola operazione o 10.000 operazioni per chiamata), con il campo message dell'errore che specifica quale limite è stato violato.

Indietro
Filtri dei gruppi di schede