Google Ads API'de güncellemeler bir alan maskesi kullanılarak yapılır. Alan maskesi, güncellemeyle değiştirmek istediğiniz tüm alanları listeler. Alan maskesinde bulunmayan belirtilen alanlar, sunucuya gönderilse bile yoksayılır.
FieldMaskUtil
Alan maskeleri oluşturmak için önerilen yöntem, yerleşik alan maskesi yardımcı programını kullanmaktır. Bu yardımcı program, belirli ayrıntıları gizler ve öğenin alanlarında yaptığınız değişiklikleri izleyerek alan maskelerini otomatik olarak oluşturmanıza olanak tanır.
Aşağıdaki örnekte, bir kampanyayı güncellemek için alan maskesinin nasıl oluşturulacağı gösterilmektedir:
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
Kod önce boş bir Campaign nesnesi oluşturur, ardından güncellenen kampanyayı API'ye bildirmek için nesnenin kaynak adını ayarlar.
Bu örnekte, güncellemeleri kapsayan bloğu başlatmak için kampanyada client.field_mask.with yöntemi kullanılmaktadır. Bu bloğun sonunda yardımcı program, bloğun ardından kampanyanın mevcut durumunu bloktan önceki ilk durumuyla karşılaştırır ve değiştirilen alanları listeleyen bir alan maskesini otomatik olarak oluşturur. Bu alan maskesini, değişiklik çağrısı için oluştururken
işleme aşağıdaki gibi sağlayabilirsiniz:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Karmaşık bir işlem oluştururken ve her adım üzerinde ayrıntılı kontrol sahibi olmak istediğinizde bu yöntem önerilir. Ancak çoğu durumda, kaynak adını (veya mevcut bir kaynak örneğini) Ruby kitaplığı fabrika yöntemine iletebilirsiniz:
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation =
client.operation.update_resource.campaign(campaign_resource_name) do |c|
c.status = :PAUSED
c.network_settings = client.resource.network_settings do |ns|
ns.target_search_network = false
end
end
Bu yöntem, bir kaynak adı dizesi verildiğinde resource_name doldurulmuş yeni bir kampanya kaynağını otomatik olarak oluşturur, blokta yaptığınız değişikliklere göre alan maskesini oluşturur, güncelleme işlemini oluşturur ve update ile update_mask doldurulmuş son işlemi döndürür.
Kampanyanın başlangıç durumunu belirtmek için kaynak adı dizesi yerine mevcut bir Campaign proto örneği de iletebilirsiniz. Bu kalıp, güncelleme işlemini destekleyen tüm kaynaklar için geçerlidir.
Manuel olarak alan maskesi oluşturma
Kitaplık yardımcı programlarını kullanmadan sıfırdan bir alan maskesi oluşturmak için Google::Protobuf::FieldMask oluşturun, değiştirmek istediğiniz tüm alanların adlarıyla doldurulmuş bir dizi oluşturun ve diziyi alan maskesinin paths alanına atayın:
mask = Google::Protobuf::FieldMask.new
mask.paths = ['status', 'name']
Mesaj alanlarını ve alt alanlarını güncelleme
MESSAGE alanlarının alt alanları olabilir (ör. üç alt alanı olan MaximizeConversions: target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros) veya hiç alt alanı olmayabilir (ör. ManualCpm).
Tanımlanmış alt alanları olmayan mesaj alanları
Herhangi bir alt alanla tanımlanmamış bir MESSAGE alanını güncellerken daha önce gösterildiği gibi alan maskesi oluşturmak için FieldMaskUtil kullanın.
Tanımlanmış alt alanları olan mesaj alanları
Alt alanlarla tanımlanmış bir MESSAGE alanını, mesajdaki alt alanlardan herhangi birini açıkça ayarlamadan güncellerken değiştirilebilir MESSAGE alt alanlarının her birini FieldMask alanına manuel olarak eklemeniz gerekir. Bu işlem, sıfırdan alan maskesi oluşturulan önceki örneğe benzer.
Sık karşılaşılan bir örnek, yeni teklif stratejisindeki alanlardan hiçbirini ayarlamadan bir kampanyanın teklif stratejisini güncellemektir. Aşağıdaki örnekte, teklif stratejisindeki alt alanlardan herhangi biri ayarlanmadan MaximizeConversions teklif stratejisini kullanmak için bir kampanyanın nasıl güncelleneceği gösterilmektedir.
Bu örnekte, yerleşik FieldMaskUtil karşılaştırmasını kullanmak istenen hedefe ulaşmayı sağlamaz.
Aşağıdaki kod, maximize_conversions içeren bir alan maskesi oluşturur.
Ancak Google Ads API, alanların yanlışlıkla temizlenmesini önlemek için bu davranışa izin vermez ve FieldMaskError.FIELD_HAS_SUBFIELDS hatası verir.
# 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 results 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]
)
# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask starts empty. You can modify
# other fields in this block, except the message field intended to have a
# blank subfield.
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]
)
Alanları temizle
Bazı alanlar açıkça temizlenebilir. Önceki örnekte olduğu gibi, bu alanları alan maskesine açıkça eklemeniz gerekir. Örneğin, MaximizeConversions teklif stratejisini kullanan bir kampanyanız olduğunu ve target_cpa_micros alanının 0 değerinden daha yüksek bir değere ayarlandığını varsayalım.
proto3 dilinde, isteğe bağlı olmayan bir skaler alanı varsayılan değerine (0) ayarlamak, yeni bir mesaj örneğinde ayarlanmamış olarak bırakmaktan farksızdır. Sonuç olarak FieldMaskUtil, alan maskesine maximize_conversions.target_cpa_micros yerine maximize_conversions ekler ve bu da FieldMaskError.FIELD_HAS_SUBFIELDS hatasına neden olur.
# 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 includes 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it results 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 fails because the field mask is invalid.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation]
)
# Create a campaign including the maximize conversions fields right away, since
# they are manually added 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 can add a block here with
# other changes that are automatically 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 succeeds because the correct field mask is specified.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation]
)
Otomatik karşılaştırma yaklaşımının, Google Ads API protokol arabelleklerinde optional olarak tanımlanan alanlar için amaçlandığı şekilde çalıştığını unutmayın. target_cpa_micros, MaximizeConversions üzerinde bir optional alanı olmadığından, temizlemek için yolun update_mask.paths öğesine açıkça eklenmesi gerekir.