Mutasi massal

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

Operasi perubahan

Setiap MutateGoogleAdsRequest menerima MutateOperation berulang di kolom mutate_operations:

• Operasi perubahan resource (semua versi yang didukung): Setiap entri dapat menentukan satu operasi create, update, atau remove untuk satu jenis resource.
• Operasi tindakan (v23 dan yang lebih baru): Setiap entri juga dapat menentukan operasi tindakan, seperti book_campaigns_operation atau quote_campaigns_operation (di v22, MutateOperation hanya mendukung operasi mutasi resource).

Untuk membuat entitas dependen (seperti kampanye dan grup iklan) dalam satu panggilan GoogleAdsService.Mutate, buat dua entri MutateOperation (satu berisi CampaignOperation dan yang lain berisi AdGroupOperation). Tetapkan nama resource sementara dengan ID negatif (seperti customers/CUSTOMER_ID/campaigns/-1) ke kampanye agar 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 sebagian

Secara default, operasi dalam permintaan GoogleAdsService.Mutate dieksekusi 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 sebagian (partial_failure = true): Melakukan operasi yang valid dan menampilkan error untuk operasi yang gagal di partial_failure_error.
• Mode validasi (validate_only = true): Memeriksa error pada operasi tanpa melakukan perubahan pada akun:
  • Operasi perubahan resource: Hanya menampilkan error validasi dan menghilangkan hasil.
  • Operasi tindakan (v23 dan yang lebih baru): Menampilkan hasil tindakan (seperti quote_campaigns_result atau book_campaigns_result) jika validasi berhasil; jika terjadi error validasi, hasil tindakan akan dihapus dari MutateOperationResponse (meskipun penawaran harga masih dapat ditampilkan di ErrorDetails.reservation_error_details). Perhatikan bahwa quote_campaigns_operation memerlukan validate_only = true dan partial_failure = false.