Bonnes pratiques et limites

Tenez compte de ces consignes lorsque vous utilisez BatchJobService.

Améliorer le débit

  • Il est préférable d'avoir moins de tâches plus volumineuses que de nombreuses tâches plus petites.

  • Triez les opérations importées par type d'opération (à l'exception des opérations interdépendantes qui doivent être regroupées consécutivement dans des sous-lots atomiques). Par exemple, si votre tâche contient des opérations permettant d'ajouter des campagnes standards, des groupes d'annonces et des critères de groupe d'annonces, ordonnez les opérations dans votre import afin que toutes les opérations de campagne soient en premier, suivies de toutes les opérations de groupe d'annonces, et enfin de toutes les opérations de critère de groupe d'annonces.

  • Pour les opérations du même type, il peut être plus efficace de les regrouper par ressource parente. Par exemple, si vous avez une série d'objets AdGroupCriterionOperation, il est plus efficace de regrouper les opérations par groupe d'annonces plutôt que de mélanger les opérations qui affectent les critères de groupe d'annonces dans différents groupes d'annonces.

Atomicité dans le fractionnement par lot

L'API Google Ads divise les opérations d'un job par lot envoyé en sous-lots plus petits pour le traitement. Alors que les sous-lots standards s'exécutent avec l'échec partiel activé, les sous-lots pour certaines opérations interdépendantes sont traités de manière atomique en tant que transaction unique :

Pour les sous-lots de création AssetGroup et Performance Max Campaign (jusqu'à 1 000 opérations au total par sous-lot ; toutes les opérations create enfants au-delà de 999 sont transférées dans le sous-lot non atomique suivant) :

  • L'opération create parente (resource_name sur AssetGroup ou Campaign) et ses opérations create enfant consécutives (asset_group sur AssetGroupAsset ou campaign sur CampaignAsset) doivent spécifier le même ID temporaire négatif.
  • Placez les opérations AssetOperation (create) requises pour les nouvelles ressources Asset avant les opérations AssetGroupOperation ou CampaignOperation (create) parentes, jamais entre les opérations create parentes et leurs opérations create enfants (ce qui fermerait immédiatement le sous-lot atomique et séparerait la création de la ressource parente de ses composants associés).

Lorsqu'un sous-lot atomique échoue, le BatchJobResult.status de l'opération en cause contient l'erreur de validation sous-jacente, tandis que les opérations restantes de ce sous-lot sont annulées avec l'erreur de transaction correspondante pour ce sous-lot. Examinez les entrées BatchJobResult adjacentes partageant le même ID AdGroup, AssetGroup ou Campaign pour identifier l'erreur à l'origine du problème.

Si des opérations associées dans l'un de ces groupes ne sont pas ajoutées de manière consécutive, l'API Google Ads les répartit dans des sous-lots distincts. La modification ne respecte alors pas les exigences minimales concernant les composants ou laisse les arborescences de groupes de fiches incomplètes. Pour en savoir plus, consultez Utiliser des filtres de groupes de fiches dans les jobs par lot et Traitement par lot dans Performance Max.

Regroupement logique

Lorsque vous modifiez une hiérarchie de ciblage de produits (AssetGroupListingGroupFilterOperation dans les campagnes Performance Max ou AdGroupCriterionOperation dans les campagnes Shopping) ou que vous créez un AssetGroup ou un Campaign Performance Max, regroupez toutes les opérations ciblant la même ressource parente (AssetGroup, AdGroup ou Campaign) de manière consécutive. Cela réduit la contention des verrous de backend et permet de conserver les arbres interdépendants ensemble.

Cohérence des données

Étant donné que les arborescences de filtres de groupes de fiches et les exigences concernant les composants Performance Max sont validées à la fin de chaque transaction de sous-lot atomique, évitez de répartir les mises à jour de la même ressource parente sur des plages discontinues dans un job ou sur des jobs simultanés.

Éviter les problèmes de simultanéité

  • Lorsque vous envoyez plusieurs jobs simultanés pour le même compte, réduisez la probabilité que les jobs fonctionnent sur les mêmes objets en même temps tout en conservant des tailles de job importantes. De nombreux jobs inachevés avec l'état RUNNING qui tentent de modifier le même ensemble d'objets peuvent entraîner des conditions de blocage, ce qui peut entraîner un ralentissement important, voire l'échec des jobs.

  • N'envoyez pas plusieurs opérations qui modifient le même objet dans le même job, car le résultat peut être imprévisible.

Récupérer les résultats de manière optimale

  • N'interrogez pas trop souvent l'état du job, car vous risquez de rencontrer des erreurs de limitation du taux d'utilisation.

  • Laissez page_size non défini (ou définissez-le sur le maximum de 1000) lorsque vous appelez ListBatchJobResults pour minimiser les allers-retours de pagination, et ne définissez response_content_type sur MUTABLE_RESOURCE que si votre application inspecte les champs de ressources renvoyés au-delà de resource_name.

  • L'ordre des résultats est le même que celui des importations.

Conseils d'utilisation supplémentaires

  • Vous pouvez définir une limite supérieure pour la durée d'exécution d'un job par lot avant son annulation. Lorsque vous créez un job par lot, définissez le champ metadata.execution_limit_seconds sur la limite de temps de votre choix, en secondes. Si metadata.execution_limit_seconds n'est pas défini, il n'y a pas de limite de temps par défaut.

  • Bien que la limite du protocole soit de 10 000 opérations par requête, nous vous recommandons de n'ajouter pas plus de 1 000 opérations par AddBatchJobOperationsRequest et d'utiliser sequence_token pour importer le reste des opérations dans le même job. Selon la taille des opérations, l'envoi d'un trop grand nombre d'opérations dans une seule AddBatchJobOperationsRequest peut entraîner une erreur BatchJobError.REQUEST_TOO_LARGE. Pour gérer cette erreur, vous pouvez réduire le nombre d'opérations et réessayer d'envoyer la AddBatchJobOperationsRequest.

Limites

  • Chaque BatchJob peut prendre en charge jusqu'à un million d'opérations. Si vous dépassez cette limite lorsque vous appelez AddBatchJobOperations, l'erreur ResourceCountLimitExceededError.RESOURCE_LIMIT s'affiche (avec ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB dans ErrorDetails.resource_count_details).

  • Chaque compte peut comporter jusqu'à 100 tâches actives ou en attente en même temps. Si vous dépassez cette limite lorsque vous créez un job par lot avec MutateBatchJob, l'erreur ResourceCountLimitExceededError.RESOURCE_LIMIT s'affiche (avec ResourceLimitType.BATCH_JOBS_PER_CUSTOMER dans ErrorDetails.resource_count_details).

  • Les tâches en attente datant de plus de sept jours sont automatiquement supprimées.

  • Chaque AddBatchJobOperationsRequest est limité à 10 000 opérations de mutation par requête. Si vous dépassez 10 000 opérations dans une même requête,une erreur BatchJobError.REQUEST_TOO_LARGE s'affiche.

  • Pour le champ page_size dans ListBatchJobResultsRequest :

  • Chaque AddBatchJobOperationsRequest est limité à 41 937 920 octets. Si vous dépassez cette limite, vous recevez une erreur BatchJobError.REQUEST_TOO_LARGE (ou INTERNAL_ERROR si la demande est refusée au niveau de la couche de transport). Vous pouvez déterminer la taille sérialisée de la requête avant de l'envoyer et prendre les mesures appropriées si elle est trop volumineuse :

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

Taille d'une seule opération de mutation

Bien que la taille totale de la requête puisse atteindre 41 937 920 octets, la taille sérialisée d'un seul MutateOperation dans le lot est limitée à 10 484 504 octets (10 Mio moins 1 256 octets). Si vous dépassez cette limite, l'erreur BatchJobError.REQUEST_TOO_LARGE s'affiche. Notez que, bien que la documentation de référence pour BatchJobError.REQUEST_TOO_LARGE cite le seuil de 10 484 504 octets, AddBatchJobOperations renvoie le même code d'erreur lorsque l'un des trois seuils de requête (41 937 920 octets pour la requête totale, 10 484 504 octets pour une seule opération ou 10 000 opérations par appel) est dépassé. Le champ message de l'erreur indique la limite qui a été dépassée.

Précédent
Filtres de groupes de fiches