Bulk-Mutations

Wenn Sie mehrere Ressourcentypen in einer einzelnen 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.

Mutationsvorgänge

Jedes MutateGoogleAdsRequest akzeptiert ein wiederholtes MutateOperation im Feld mutate_operations:

  • Ressourcenänderungsvorgänge (alle unterstützten Versionen): Jeder Eintrag kann einen einzelnen create-, update- oder remove-Vorgang für einen Ressourcentyp angeben.
  • Aktionsvorgänge (Version 23 und höher): Für jeden Eintrag kann auch ein Aktionsvorgang angegeben werden, z. B. book_campaigns_operation oder quote_campaigns_operation (in Version 22 unterstützt MutateOperation nur Vorgänge zum Ändern von Ressourcen).

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 (einen mit einem CampaignOperation und einen mit einem AdGroupOperation). Weisen Sie der Kampagne einen temporären Ressourcennamen mit einer negativen ID (z. B. customers/CUSTOMER_ID/campaigns/-1) zu, damit in der Anzeigengruppenoperation im selben Request darauf verwiesen werden 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 partielle Fehler

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

Wie bei einzelnen Ressourcendiensten werden an diesem Endpunkt die folgenden Optionen unterstützt:

  • Teilweiser Fehler (partial_failure = true): Es werden gültige Vorgänge übernommen und Fehler für fehlgeschlagene Vorgänge in partial_failure_error zurückgegeben.
  • Validierungsmodus (validate_only = true): Vorgänge werden auf Fehler geprüft, ohne dass Änderungen am Konto vorgenommen werden:
    • Mutationsvorgänge für Ressourcen:Es werden nur Validierungsfehler zurückgegeben und Ergebnisse werden ausgelassen.
    • Vorgänge für Aktionen (Version 23 und höher): Gibt das Ergebnis der Aktion zurück (z. B. quote_campaigns_result oder book_campaigns_result), wenn die Validierung erfolgreich ist. Bei Validierungsfehlern wird das Ergebnis der Aktion aus MutateOperationResponse entfernt. Ein Angebot kann jedoch weiterhin in ErrorDetails.reservation_error_details zurückgegeben werden. Für quote_campaigns_operation sind validate_only = true und partial_failure = false erforderlich.
Zurück
Ressource wird mutiert
Weiter
Best Practices