Best practice e limitazioni

Tieni presente queste linee guida quando utilizzi BatchJobService.

Migliora il throughput

  • È preferibile un numero ridotto di job di grandi dimensioni rispetto a molti job di piccole dimensioni.

  • Ordina le operazioni caricate in base al tipo di operazione (ad eccezione delle operazioni interdipendenti che devono essere raggruppate consecutivamente in sub-batch atomici). Ad esempio, se il job 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 relative alle campagne siano le prime, seguite da tutte le operazioni relative ai gruppi di annunci e infine da tutte le operazioni relative ai criteri dei gruppi di annunci.

  • Nell'ambito di operazioni dello stesso tipo, può migliorare le prestazioni raggrupparle per risorsa padre. Ad esempio, se hai una serie di oggetti AdGroupCriterionOperation, è più efficiente raggruppare le operazioni per gruppo di annunci anziché combinare operazioni che influiscono sui criteri dei gruppi di annunci in gruppi di annunci diversi.

Atomicità nella suddivisione dei batch

L'API Google Ads suddivide le operazioni di un job batch inviato in batch secondari più piccoli per l'elaborazione. Mentre i sub-batch standard vengono eseguiti con l'errore parziale attivato, i sub-batch per determinate operazioni interdipendenti vengono elaborati in modo atomico come un'unica 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 tutte le operazioni 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 sub-batch atomico e separerebbero la creazione della risorsa padre dagli asset collegati).

Quando un sub-batch atomico non va a buon fine, l'operazione incriminata BatchJobResult.status contiene l'errore di convalida sottostante, mentre viene eseguito il rollback delle operazioni rimanenti nel sub-batch con l'errore di transazione corrispondente per quel sub-batch. Esamina le voci BatchJobResult adiacenti che condividono lo stesso ID AdGroup, AssetGroup o Campaign per identificare l'errore della 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, il che comporta il mancato rispetto dei requisiti minimi degli asset o l'incompletezza degli alberi dei gruppi di schede. Per maggiori dettagli, consulta Utilizza i filtri dei gruppi di schede nei job batch ed 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 che hanno come target la stessa risorsa principale (AssetGroup, AdGroup o Campaign) in modo consecutivo. In questo modo si riduce la contesa dei blocchi del backend e si mantengono 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 atomica di un sub-batch, evita di suddividere gli aggiornamenti della stessa risorsa principale in intervalli non continui in un job o in job simultanei.

Evita problemi di contemporaneità

  • Quando invii più job contemporaneamente per lo stesso account, riduci la probabilità che i job operino sugli stessi oggetti nello stesso momento, mantenendo al contempo 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 simili a un deadlock, con conseguente grave rallentamento e persino errori dei job.

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

Recuperare i risultati in modo ottimale

  • Non eseguire il polling dello stato del job troppo di frequente, altrimenti rischi di riscontrare errori di limitazione di frequenza.

  • 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 su MUTABLE_RESOURCE solo se la tua applicazione ispeziona i campi delle risorse restituiti oltre resource_name.

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

Indicazioni aggiuntive per l'utilizzo

  • Puoi impostare un limite superiore approssimativo per il tempo di esecuzione di un job batch prima che venga annullato. Quando crei un nuovo job batch, imposta il campo metadata.execution_limit_seconds su un numero intero positivo per il limite di tempo che preferisci, in secondi. Se metadata.execution_limit_seconds non è impostato, non esiste un limite di tempo predefinito.

  • Sebbene il limite del protocollo sia di 10.000 operazioni per richiesta, ti consigliamo di non aggiungere 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 troppe operazioni in un singolo AddBatchJobOperationsRequest può causare un errore BatchJobError.REQUEST_TOO_LARGE. Puoi gestire questo errore riducendo il numero di operazioni e riprovando l'operazione AddBatchJobOperationsRequest.

Limitazioni

  • Ogni BatchJob supporta fino a un milione di operazioni. Il superamento di questo limite quando chiami 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 quando crei un job batch con MutateBatchJob restituisce un errore ResourceCountLimitExceededError.RESOURCE_LIMIT (con ResourceLimitType.BATCH_JOBS_PER_CUSTOMER in ErrorDetails.resource_count_details).

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

  • Ogni AddBatchJobOperationsRequest ha un limite massimo di 10.000 operazioni di modifica per richiesta. Se superi le 10.000 operazioni in una singola richiesta,viene restituito 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 rifiutato a livello di trasporto). Puoi determinare le dimensioni serializzate della richiesta prima di inviarla e intraprendere l'azione appropriata se sono troppo grandi:

    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)

# Supports both proto-plus (use_proto_plus=True) and native protobuf
# (use_proto_plus=False) messages.
pb = type(request).pb(request) if hasattr(type(request), "pb") else request
size_in_bytes = pb.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 di richiesta totali, 10.484.504 byte di 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