Prácticas recomendadas y limitaciones

Ten en cuenta estos lineamientos cuando uses BatchJobService.

Mejora la capacidad de procesamiento

  • Se prefiere una menor cantidad de trabajos más grandes que muchos trabajos más pequeños.

  • Ordena las operaciones subidas por tipo de operación (excepto las operaciones interdependientes que deben agruparse de forma consecutiva en sublotes atómicos). Por ejemplo, si tu trabajo contiene operaciones para agregar campañas estándar, grupos de anuncios y criterios de grupos de anuncios, ordena las operaciones en tu carga de modo que todas las operaciones de campaña aparezcan primero, seguidas de todas las operaciones de grupos de anuncios y, por último, todas las operaciones de criterios de grupos de anuncios.

  • Dentro de las operaciones del mismo tipo, puede mejorar el rendimiento agruparlas por recurso superior. Por ejemplo, si tienes una serie de objetos AdGroupCriterionOperation, es más eficiente agrupar las operaciones por grupo de anuncios que mezclar operaciones que afecten los criterios de grupos de anuncios en diferentes grupos de anuncios.

Atomicidad en la división de lotes

La API de Google Ads divide las operaciones de un trabajo por lotes enviado en sublotes más pequeños para su procesamiento. Mientras que los sublotes estándar se ejecutan con el error parcial habilitado, los sublotes para ciertas operaciones interdependientes se procesan de forma atómica como una sola transacción:

Para los sublotes de creación de AssetGroup y de campañas de máximo rendimiento Campaign (hasta 1,000 operaciones en total por sublote; cualquier operación secundaria de create que supere las 999 se transfiere al siguiente sublote no atómico):

  • La operación create superior (resource_name en AssetGroup o Campaign) y sus operaciones create secundarias consecutivas (asset_group en AssetGroupAsset o campaign en CampaignAsset) deben especificar el mismo ID temporal negativo.
  • Coloca cualquier operación AssetOperation (create) de requisitos previos para los recursos Asset nuevos antes de la operación AssetGroupOperation o CampaignOperation (create) superior, nunca entre la operación create superior y sus operaciones de vinculación secundarias create (lo que cerraría de inmediato el sublote atómico y dividiría la creación del recurso superior de sus recursos vinculados).

Cuando falla un sublote atómico, el BatchJobResult.status de la operación con errores contiene el error de validación subyacente, mientras que las operaciones restantes en ese sublote se revierten con el error de transacción correspondiente para ese sublote. Inspecciona las entradas BatchJobResult adyacentes que comparten el mismo ID de AdGroup, AssetGroup o Campaign para identificar el error de causa raíz.

Si las operaciones relacionadas de cualquiera de estos grupos no se agregan de forma consecutiva, la API de Google Ads las divide en lotes secundarios independientes, lo que hace que la modificación no cumpla con los requisitos mínimos de recursos o que los árboles de grupos de fichas queden incompletos. Consulta Cómo usar filtros de grupos de fichas en trabajos por lotes y Procesamiento por lotes de campañas de máximo rendimiento para obtener más detalles.

Agrupamiento lógico

Cuando modificas una jerarquía de segmentación por productos (AssetGroupListingGroupFilterOperation en las campañas de máximo rendimiento o AdGroupCriterionOperation en las campañas de Shopping) o creas un nuevo AssetGroup o Campaign de máximo rendimiento, agrupa todas las operaciones que se segmentan para el mismo recurso superior (AssetGroup, AdGroup o Campaign) de forma consecutiva. Esto reduce la contención de bloqueo del backend y mantiene juntos los árboles interdependientes.

Coherencia de los datos

Debido a que los árboles de filtros de grupos de fichas y los requisitos de recursos de las campañas de máximo rendimiento se validan al final de cada transacción de sublote atómica, evita dividir las actualizaciones del mismo recurso superior en rangos discontinuos en un trabajo o en trabajos simultáneos.

Evita los problemas de simultaneidad

  • Cuando envíes varios trabajos simultáneos para la misma cuenta, reduce la probabilidad de que los trabajos operen en los mismos objetos al mismo tiempo y, a la vez, mantén los tamaños de los trabajos grandes. Muchos trabajos sin terminar con el estado RUNNING que intentan mutar el mismo conjunto de objetos pueden generar condiciones similares a un interbloqueo, lo que provoca una ralentización grave y, incluso, fallas en los trabajos.

  • No envíes varias operaciones que muten el mismo objeto en el mismo trabajo, ya que el resultado puede ser impredecible.

Recupera resultados de forma óptima

  • No consultes el estado del trabajo con demasiada frecuencia o corres el riesgo de alcanzar errores de límite de frecuencia.

  • Deja page_size sin configurar (o configúralo en el máximo de 1000) cuando llames a ListBatchJobResults para minimizar los viajes de ida y vuelta de paginación, y solo configura response_content_type en MUTABLE_RESOURCE si tu aplicación inspecciona los campos de recursos mostrados más allá de resource_name.

  • El orden de los resultados es el mismo que el de carga.

Orientación adicional sobre el uso

  • Puedes establecer un límite superior aproximado para el tiempo que se puede ejecutar un trabajo por lotes antes de que se cancele. Cuando crees un trabajo por lotes nuevo, establece el campo metadata.execution_limit_seconds en un número entero positivo para el límite de tiempo que prefieras, en segundos. No hay un límite de tiempo predeterminado si no se establece metadata.execution_limit_seconds.

  • Aunque el límite del protocolo es de 10,000 operaciones por solicitud, recomendamos no agregar más de 1,000 operaciones por AddBatchJobOperationsRequest y usar el sequence_token para subir el resto de las operaciones al mismo trabajo. Según el tamaño de las operaciones, enviar demasiadas en una sola AddBatchJobOperationsRequest puede causar un error BatchJobError.REQUEST_TOO_LARGE. Para controlar este error, reduce la cantidad de operaciones y vuelve a intentar la AddBatchJobOperationsRequest.

Limitaciones

  • Cada BatchJob admite hasta un millón de operaciones. Si superas este límite cuando llamas a AddBatchJobOperations, se muestra un error ResourceCountLimitExceededError.RESOURCE_LIMIT (con ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB en ErrorDetails.resource_count_details).

  • Cada cuenta puede tener hasta 100 trabajos activos o pendientes al mismo tiempo. Si superas este límite cuando creas un trabajo por lotes con MutateBatchJob, se muestra un error ResourceCountLimitExceededError.RESOURCE_LIMIT (con ResourceLimitType.BATCH_JOBS_PER_CUSTOMER en ErrorDetails.resource_count_details).

  • Los trabajos pendientes con más de 7 días de antigüedad se quitan automáticamente.

  • Cada AddBatchJobOperationsRequest tiene un límite estricto de 10,000 operaciones de mutación por solicitud. Si se superan las 10,000 operaciones en una sola solicitud, se muestra un error BatchJobError.REQUEST_TOO_LARGE.

  • Para el campo page_size en ListBatchJobResultsRequest:

  • Cada AddBatchJobOperationsRequest tiene un tamaño máximo de 41,937,920 bytes. Si excedes este límite, recibirás un error BatchJobError.REQUEST_TOO_LARGE (o un error INTERNAL_ERROR si se rechaza en la capa de transporte). Puedes determinar el tamaño serializado de la solicitud antes de enviarla y tomar las medidas adecuadas si es demasiado 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)

# 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));

Tamaño de una sola operación de mutación

Si bien la solicitud general puede ser de hasta 41,937,920 bytes, el tamaño serializado de un solo MutateOperation dentro del lote tiene un límite de 10,484,504 bytes (10 MiB menos 1,256 bytes). Si superas este límite, se muestra un error BatchJobError.REQUEST_TOO_LARGE. Ten en cuenta que,si bien la documentación de referencia de BatchJobError.REQUEST_TOO_LARGE cita el umbral de 10,484,504 bytes, AddBatchJobOperations devuelve este mismo código de error cuando se supera cualquiera de los tres umbrales de solicitud (41,937,920 bytes de solicitud totales,10,484, 504 bytes de operación única o 10,000 operaciones por llamada), y el campo message del error especifica qué límite se incumplió.

Anterior
Filtros de grupo de fichas