Update Menggunakan Mask Kolom

Di Google Ads API, pembaruan dilakukan menggunakan mask kolom. Mask kolom mencantumkan semua kolom yang ingin Anda ubah dengan update, dan setiap kolom yang ditentukan yang tidak ada dalam mask kolom akan diabaikan, meskipun dikirim ke server.

FieldMaskUtil

Cara yang direkomendasikan untuk membuat mask kolom adalah menggunakan utilitas mask kolom bawaan kami yang menyembunyikan banyak detail spesifik dan memungkinkan Anda membuat mask kolom secara otomatis dengan memantau perubahan yang Anda buat pada kolom entity.

Berikut cara membuat mask kolom untuk memperbarui kampanye:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Kode ini pertama-tama membuat objek Kampanye kosong, lalu menetapkan nama resource-nya untuk memberi tahu API tentang kampanye yang sedang diperbarui.

Contoh ini menggunakan metode client.field_mask.with di kampanye untuk memulai blok yang mencakup update. Di akhir blok ini, utilitas membandingkan status kampanye saat ini setelah blok dengan status awal kampanye sebelum blok, dan secara otomatis menghasilkan mask kolom yang menghitung kolom yang diubah. Anda dapat memberikan mask kolom tersebut ke operasi saat membuatnya untuk panggilan mutasi sebagai berikut:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Metode ini direkomendasikan saat Anda melakukan operasi yang rumit dan ingin kontrol yang tepat atas setiap langkah. Namun, untuk sebagian besar kasus, Anda dapat menggunakan utilitas library Ruby yang lebih sederhana:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Metode ini otomatis membuat resource kampanye kosong baru, membuat mask kolom berdasarkan perubahan yang Anda buat dalam blok, membuat operasi update, dan menampilkan operasi akhir dengan update dan update_mask yang sudah terisi. Anda juga dapat meneruskan kampanye ke metode campaign untuk menentukan status awal kampanye. Pola ini berfungsi untuk semua resource yang mendukung operasi update.

Membuat mask secara manual

Untuk membuat mask kolom dari awal, tanpa menggunakan utilitas library apa pun, Anda harus membuat Google::Protobuf::FieldMask terlebih dahulu, lalu membuat array yang diisi dengan nama semua kolom yang ingin diubah, dan akhirnya menetapkan array ke kolom path mask kolom.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

Memperbarui kolom pesan dan sub-kolomnya

Kolom MESSAGE dapat memiliki subkolom (seperti MaximizeConversions yang memiliki tiga: target_cpa_micros, cpc_bid_ceiling_micros, dan cpc_bid_floor_micros), atau kolom tersebut tidak dapat memiliki subkolom sama sekali (seperti ManualCpm).

Kolom pesan tanpa subkolom yang ditentukan

Saat memperbarui kolom MESSAGE yang tidak ditentukan dengan subkolom apa pun, gunakan FieldMaskUtil untuk membuat mask kolom, seperti yang telah dijelaskan sebelumnya.

Kolom pesan dengan subkolom yang ditentukan

Saat memperbarui kolom MESSAGE yang ditentukan dengan subkolom tanpa menetapkan subkolom apa pun pada pesan tersebut secara eksplisit, Anda harus menambahkan setiap subkolom MESSAGE yang dapat diubah secara manual ke FieldMask, mirip dengan contoh sebelumnya yang membuat mask kolom dari awal.

Salah satu contoh umum adalah memperbarui strategi bidding kampanye tanpa menetapkan kolom apa pun pada strategi bidding baru. Contoh berikut menunjukkan cara memperbarui kampanye untuk menggunakan strategi bidding MaximizeConversions tanpa menetapkan subkolom apa pun pada strategi bidding.

Untuk contoh ini, penggunaan perbandingan bawaan FieldMaskUtil tidak mencapai sasaran yang diinginkan.

Kode berikut menghasilkan mask kolom yang menyertakan maximize_conversions. Namun, Google Ads API tidak mengizinkan perilaku ini untuk mencegah penghapusan kolom secara tidak sengaja dan menghasilkan error FieldMaskError.FIELD_HAS_SUBFIELDS.

Peringatan: Kode berikut menghasilkan error.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Kode berikut menunjukkan cara memperbarui kampanye dengan benar untuk menggunakan strategi bidding MaximizeConversions tanpa menetapkan subkolom apa pun.

Berhasil: Kode di bawah berhasil memperbarui strategi bidding kampanye.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Menghapus kolom

Beberapa kolom dapat dihapus secara eksplisit. Serupa dengan contoh sebelumnya, Anda harus menambahkan kolom ini secara eksplisit ke mask kolom. Misalnya, Anda memiliki kampanye yang menggunakan strategi bidding MaximizeConversions dan kolom target_cpa_micros ditetapkan dengan nilai yang lebih besar dari 0.

Kode berikut akan berjalan; namun, maximize_conversions.target_cpa_micros tidak akan ditambahkan ke mask kolom sehingga tidak ada perubahan yang dilakukan pada kolom target_cpa_micros:

Peringatan: Kode ini akan menghasilkan error.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Kode berikut menunjukkan cara menghapus kolom target_cpa_micros dengan benar di strategi bidding MaximizeConversions.

Berhasil: Kode berikut menghapus target_cpa_micros.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Perhatikan bahwa kode "salah" berfungsi sebagaimana mestinya untuk kolom yang ditentukan sebagai optional di protocol buffers Google Ads API. Namun, karena target_cpa_micros bukan kolom optional, kode "salah" tidak memperbarui strategi bidding untuk menghapus kolom target_cpa.

Poin Penting: Jika Anda ingin menghapus kolom, cara teraman adalah dengan menambahkan kolom tersebut secara eksplisit ke mask kolom.