Mutations groupées

Pour modifier plusieurs types de ressources dans une seule requête ou envoyer toutes les modifications à 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 : chaque entrée peut spécifier une seule opération create, update ou remove pour un type de ressource.
• Opérations d'action : chaque entrée peut également spécifier une opération d'action, telle que book_campaigns_operation ou quote_campaigns_operation.

Pour créer des entités dépendantes (telles qu'une campagne et un groupe d'annonces) dans un seul appel GoogleAdsService.Mutate, créez deux entrées MutateOperation (une contenant un CampaignOperation et une autre contenant 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 la requête entière échoue si une opération contient une erreur.

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

• Échec partiel (partial_failure = true) : valide les opérations valides et renvoie des erreurs pour les opérations ayant échoué dans partial_failure_error.
• Mode de validation (validate_only = true) : vérifie si les opérations comportent des erreurs sans appliquer les modifications au compte :
  • Opérations de modification de ressources : ne renvoie que les erreurs de validation et omet les résultats.
  • Opérations d'action : renvoie 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.