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 jobs plus volumineux que de nombreux jobs plus petits.

  • Classez 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 job contient des opérations pour ajouter des campagnes standards, des groupes d'annonces et des critères de groupe d'annonces, ordonnez les opérations dans votre importation de sorte que toutes les opérations de campagne soient placées en premier, suivies de toutes les opérations de groupe d'annonces, puis de toutes les opérations de critères de groupe d'annonces.

  • Pour les opérations du même type, vous pouvez améliorer les performances en les regroupant par ressource parente. Par exemple, si vous disposez d'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 la répartition 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 de 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 reportées dans le sous-lot non atomique suivant) :

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

Lorsqu'un sous-lot atomique échoue, l'BatchJobResult.status de l'opération incriminée 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. Inspectez les entrées BatchJobResult adjacentes partageant le même ID AdGroup, AssetGroup ou Campaign pour identifier l'erreur d'origine.

Si les opérations associées dans l'un de ces groupes ne sont pas ajoutées consécutivement, l'API Google Ads les répartit dans des sous-lots distincts. Par conséquent, la modification ne respecte 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 des jobs par lot et Traitement par lot 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 les conflits de verrouillage du backend et maintient les arbres interdépendants ensemble.

Cohérence des données

Étant donné que les arborescences de filtres de groupes de fiches et les exigences d'éléments Performance Max sont validées à la fin de chaque transaction de sous-lot atomique, évitez de diviser les mises à jour d'une 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 s'exécutent sur les mêmes objets en même temps, tout en conservant des jobs de grande taille. De nombreux jobs inachevés dont l'état est RUNNING et qui tentent de modifier le même ensemble d'objets peuvent entraîner des conditions de blocage, ce qui entraîne un ralentissement important, voire des échecs de 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 l'état du job trop fréquemment, car vous risquez de rencontrer des erreurs de limitation du débit.

  • Laissez page_size non défini (ou définissez-le sur la valeur maximale 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 de l'importation.

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. Il n'y a pas de limite de temps par défaut si metadata.execution_limit_seconds n'est pas défini.

  • Bien que la limite du protocole soit de 10 000 opérations par requête, nous vous recommandons de ne pas ajouter 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 un seul AddBatchJobOperationsRequest peut entraîner une erreur BatchJobError.REQUEST_TOO_LARGE. Vous pouvez résoudre cette erreur en réduisant le nombre d'opérations et en relançant la commande AddBatchJobOperationsRequest.

Limites

  • Chaque BatchJob accepte jusqu'à un million d'opérations. Le dépassement de cette limite lors de l'appel de AddBatchJobOperations renvoie une erreur ResourceCountLimitExceededError.RESOURCE_LIMIT (avec ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB dans ErrorDetails.resource_count_details).

  • Chaque compte peut comporter jusqu'à 100 jobs actifs ou en attente en même temps. Si vous dépassez cette limite lors de la création d'un job par lot avec MutateBatchJob, une erreur ResourceCountLimitExceededError.RESOURCE_LIMIT est renvoyée (avec ResourceLimitType.BATCH_JOBS_PER_CUSTOMER dans ErrorDetails.resource_count_details).

  • Les jobs en attente datant de plus de sept jours sont automatiquement supprimés.

  • Chaque AddBatchJobOperationsRequest est soumis à une limite stricte de 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 est renvoyée.

  • Pour le champ page_size dans ListBatchJobResultsRequest :

  • Chaque AddBatchJobOperationsRequest a une taille maximale de 41 937 920 octets. Si vous dépassez cette limite, vous recevez une erreur BatchJobError.REQUEST_TOO_LARGE (ou une erreur INTERNAL_ERROR si elle est rejetée au niveau de la couche 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 modification

Bien que la requête globale 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 ce même code d'erreur lorsque l'un des trois seuils de requête (41 937 920 octets de requête au total, 10 484 504 octets d'opération unique ou 10 000 opérations par appel) est dépassé, le champ message de l'erreur spécifiant la limite qui a été enfreinte.

Précédent
Filtres de groupes de fiches