Mutasi massal

Untuk mengubah beberapa jenis resource dalam satu permintaan atau mengirim semua mutasi ke endpoint terpadu, gunakan GoogleAdsService.Mutate. Untuk mengetahui daftar lengkap operasi yang didukung, lihat referensi MutateOperation.

Operasi mutasi

Setiap MutateGoogleAdsRequest menerima MutateOperation berulang di kolom mutate_operations-nya:

• Operasi mutasi resource: Setiap entri dapat menentukan satu operasi create, update, atau remove untuk satu jenis resource.
• Operasi tindakan: Setiap entri juga dapat menentukan operasi tindakan, seperti book_campaigns_operation atau quote_campaigns_operation.

Untuk membuat entitas dependen (seperti kampanye dan grup iklan) dalam satu panggilan GoogleAdsService.Mutate, buat dua entri MutateOperation (satu berisi CampaignOperation dan satu lagi berisi AdGroupOperation). Tetapkan nama resource sementara dengan ID negatif (seperti customers/CUSTOMER_ID/campaigns/-1) ke kampanye sehingga operasi grup iklan dapat mereferensikannya dalam permintaan yang sama:

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

Atomisitas dan kegagalan parsial

Secara default, operasi dalam permintaan GoogleAdsService.Mutate dijalankan secara atomik: semua operasi berhasil bersama-sama, atau seluruh permintaan gagal jika ada operasi yang berisi error.

Seperti layanan resource individual, endpoint ini mendukung opsi berikut:

• Kegagalan parsial (partial_failure = true): Melakukan commit operasi yang valid dan menampilkan error untuk operasi yang gagal di partial_failure_error.
• Mode validasi (validate_only = true): Memeriksa operasi untuk menemukan error tanpa menerapkan perubahan pada akun:
  • Operasi mutasi resource: Hanya menampilkan error validasi dan menghilangkan hasil.
  • Operasi tindakan: Menampilkan hasil tindakan (seperti quote_campaigns_result atau book_campaigns_result) saat validasi berhasil; jika terjadi error validasi, hasil tindakan akan dihilangkan dari MutateOperationResponse (meskipun kuotasi mungkin masih ditampilkan di ErrorDetails.reservation_error_details). Perhatikan bahwa quote_campaigns_operation memerlukan validate_only = true dan partial_failure = false.