Bulk-Mutations

Wenn Sie mehrere Ressourcentypen in einer einzigen Anfrage ändern oder alle Änderungen an einen einheitlichen Endpunkt senden möchten, verwenden Sie GoogleAdsService.Mutate. Eine vollständige Liste der unterstützten Vorgänge finden Sie in der MutateOperation-Referenz.

Änderungsvorgänge

Jedes MutateGoogleAdsRequest akzeptiert ein wiederholtes MutateOperation im Feld mutate_operations:

  • Ressourcenänderungsvorgänge: Jeder Eintrag kann einen einzelnen create-, update- oder remove-Vorgang für einen Ressourcentyp angeben.
  • Aktionsvorgänge: In jedem Eintrag kann auch ein Aktionsvorgang angegeben werden, z. B. book_campaigns_operation oder quote_campaigns_operation.

Wenn Sie abhängige Entitäten (z. B. eine Kampagne und eine Anzeigengruppe) in einem einzigen GoogleAdsService.Mutate-Aufruf erstellen möchten, erstellen Sie zwei MutateOperation-Einträge. Einer enthält eine CampaignOperation und der andere eine AdGroupOperation. Weisen Sie der Kampagne einen temporären Ressourcennamen mit einer negativen ID (z. B. customers/CUSTOMER_ID/campaigns/-1) zu, damit der Anzeigengruppenvorgang im selben Request darauf verweisen kann:

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

Atomarität und teilweise fehlgeschlagene Vorgänge

Standardmäßig werden Vorgänge in einer GoogleAdsService.Mutate-Anfrage atomar ausgeführt: Entweder sind alle Vorgänge erfolgreich oder die gesamte Anfrage schlägt fehl, wenn ein Vorgang einen Fehler enthält.

Wie einzelne Ressourcendienste unterstützt dieser Endpunkt die folgenden Optionen:

  • Teilweiser Fehler (partial_failure = true): Gültige Vorgänge werden festgeschrieben und Fehler für fehlgeschlagene Vorgänge in partial_failure_error werden zurückgegeben.
  • Validierungsmodus (validate_only = true): Prüft Vorgänge auf Fehler, ohne Änderungen am Konto vorzunehmen:
    • Ressourcenänderungsvorgänge: Es werden nur Validierungsfehler zurückgegeben und Ergebnisse werden weggelassen.
    • Aktionsvorgänge: Gibt das Aktionsergebnis (z. B. quote_campaigns_result oder book_campaigns_result) zurück, wenn die Validierung erfolgreich ist. Wenn Validierungsfehler auftreten, wird das Aktionsergebnis in MutateOperationResponse weggelassen (ein Angebot kann jedoch weiterhin in ErrorDetails.reservation_error_details zurückgegeben werden). Beachten Sie, dass quote_campaigns_operation validate_only = true und partial_failure = false erfordert.
Zurück
Ressource wird mutiert
Weiter
Best Practices