Mutations groupées

Pour modifier plusieurs types de ressources dans une seule requête ou envoyer toutes les mutations à un point de terminaison unifié, utilisez GoogleAdsService.Mutate. Pour obtenir la liste complète des opérations compatibles, consultez la documentation de référence sur MutateOperation.

Opérations de mutation

Chaque MutateGoogleAdsRequest accepte un MutateOperation répété dans son champ mutate_operations :

  • Opérations de mutation de ressources (toutes les versions compatibles) : chaque entrée peut spécifier une seule opération create, update ou remove pour un type de ressource.
  • Opérations d'action (v23 et versions ultérieures) : chaque entrée peut également spécifier une opération d'action, telle que book_campaigns_operation ou quote_campaigns_operation (dans la version 22, MutateOperation ne prend en charge que les opérations de mutation de ressources).

Pour créer des entités dépendantes (comme une campagne et un groupe d'annonces) en un seul appel GoogleAdsService.Mutate, créez deux entrées MutateOperation (l'une contenant un CampaignOperation et l'autre un AdGroupOperation). Attribuez un nom de ressource temporaire avec un ID négatif (tel que customers/CUSTOMER_ID/campaigns/-1) à la campagne afin que l'opération du groupe d'annonces puisse y faire référence dans la même requête :

Python

import uuid

campaign_budget_service = client.get_service("CampaignBudgetService")
campaign_service = client.get_service("CampaignService")
googleads_service = client.get_service("GoogleAdsService")

campaign_budget_resource_name = campaign_budget_service.campaign_budget_path(
    customer_id, budget_id
)
temp_campaign_resource_name = campaign_service.campaign_path(customer_id, "-1")

mutate_operation1 = client.get_type("MutateOperation")
campaign = mutate_operation1.campaign_operation.create
campaign.resource_name = temp_campaign_resource_name
campaign.name = f"Bulk Mutate Campaign #{uuid.uuid4()}"
campaign.advertising_channel_type = (
    client.enums.AdvertisingChannelTypeEnum.SEARCH
)
campaign.status = client.enums.CampaignStatusEnum.PAUSED
campaign.manual_cpc = client.get_type("ManualCpc")
campaign.campaign_budget = campaign_budget_resource_name
campaign.contains_eu_political_advertising = (
    client.enums.EuPoliticalAdvertisingStatusEnum.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
)

mutate_operation2 = client.get_type("MutateOperation")
ad_group = mutate_operation2.ad_group_operation.create
ad_group.name = "Bulk Mutate Ad Group"
ad_group.campaign = temp_campaign_resource_name
ad_group.status = client.enums.AdGroupStatusEnum.ENABLED

response = googleads_service.mutate(
    customer_id=customer_id,
    mutate_operations=[mutate_operation1, mutate_operation2],
)

for op_response in response.mutate_operation_responses:
    result_type = op_response._pb.WhichOneof("response")
    result = getattr(op_response, result_type)
    print(f"Created {result_type}: {result.resource_name}")

Ruby

campaign_budget_resource_name =
  client.path.campaign_budget(customer_id, budget_id)
temp_campaign_resource_name =
  client.path.campaign(customer_id, -1)

mutate_operation1 = client.operation.mutate do |m|
  m.campaign_operation = client.operation.create_resource.campaign do |c|
    c.resource_name = temp_campaign_resource_name
    c.name = "Bulk Mutate Campaign #{(Time.new.to_f * 1000).to_i}"
    c.advertising_channel_type = :SEARCH
    c.status = :PAUSED
    c.manual_cpc = client.resource.manual_cpc
    c.campaign_budget = campaign_budget_resource_name
    c.contains_eu_political_advertising = :DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
  end
end

mutate_operation2 = client.operation.mutate do |m|
  m.ad_group_operation = client.operation.create_resource.ad_group do |ag|
    ag.name = "Bulk Mutate Ad Group"
    ag.campaign = temp_campaign_resource_name
    ag.status = :ENABLED
  end
end

response = client.service.google_ads.mutate(
  customer_id: customer_id,
  mutate_operations: [mutate_operation1, mutate_operation2]
)

response.mutate_operation_responses.each do |op_response|
  result = op_response.send(op_response.response)
  puts "Created #{op_response.response}: #{result.resource_name}"
end

Atomicité et échec partiel

Par défaut, les opérations d'une requête GoogleAdsService.Mutate s'exécutent de manière atomique : toutes les opérations réussissent ensemble, ou l'ensemble de la requête échoue si une opération contient une erreur.

Comme les services de ressources individuelles, ce point de terminaison accepte les options suivantes :

  • Échec partiel (partial_failure = true) : valide les opérations valides et renvoie les erreurs pour les opérations ayant échoué dans partial_failure_error.
  • Mode validation (validate_only = true) : vérifie les erreurs dans les opérations sans appliquer les modifications au compte :
    • Opérations de mutation des ressources : ne renvoient que les erreurs de validation et omettent les résultats.
    • Opérations d'action (v23 et versions ultérieures) : renvoient le résultat de l'action (par exemple, quote_campaigns_result ou book_campaigns_result) lorsque la validation réussit. Si des erreurs de validation se produisent, le résultat de l'action est omis de MutateOperationResponse (bien qu'un devis puisse toujours être renvoyé dans ErrorDetails.reservation_error_details). Notez que quote_campaigns_operation nécessite validate_only = true et partial_failure = false.
Précédent
Mutation de la ressource
Suivant
Bonnes pratiques