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 ve alan maskesinde bulunmayan belirtilen alanlar sunucuya gönderilseler bile yoksayılır.
FieldMaskUtil
Alan maskeleri oluşturmak için önerilen yöntem, belirli ayrıntıların çoğunu gizleyen ve varlığın alanlarında yaptığınız değişiklikleri izleyerek otomatik olarak alan maskeleri oluşturmanıza olanak tanıyan yerleşik alan maskesi yardımcı aracımızı kullanmaktır.
Bir kampanyayı güncellemek için alan maskesini nasıl oluşturabileceğiniz aşağıda açıklanmıştır:
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 kaynak adını, güncellenen kampanyanın API'sine bilgi verecek şekilde ayarlar.
Bu örnekte, güncellemeleri içeren bloğu başlatmak için kampanyada client.field_mask.with yöntemi kullanılmaktadır. Bu blokun sonunda, yardımcı program, engellemeden sonraki kampanyanın mevcut durumunu, engellemeden önceki kampanyanın ilk durumuyla karşılaştırır ve otomatik olarak değiştirilen alanları sıralayan bir alan maskesi oluşturur. Bu alan maskesini, değişiklik çağrısı için oluştururken aşağıdaki gibi işleme sağlayabilirsiniz:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Karmaşık bir işlem yapıyorsanız ve her adımı ayrıntılı olarak kontrol etmek istiyorsanız bu yöntem önerilir. Ancak çoğu durumda, daha basit Ruby kitaplığı yardımcı programını kullanabilirsiniz:
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
Bu yöntem otomatik olarak yeni bir boş kampanya kaynağı oluşturur, alan maskesini blok içinde yaptığınız değişikliklere göre oluşturur, güncelleme işlemini oluşturur ve update ile update_mask doldurulmuş halde son işlemi döndürür. Kampanyanın başlangıç durumunu belirtmek için de bir kampanyayı campaign yöntemine geçirebilirsiniz. Bu kalıp, güncelleme işlemini destekleyen tüm kaynaklarda çalışır.
Manuel olarak maske oluşturma
Herhangi bir kitaplık yardımcı programı kullanmadan sıfırdan alan maskesi oluşturmak için önce Google::Protobuf::FieldMask oluşturmanız, ardından değiştirmek istediğiniz tüm alanların adlarıyla doldurulmuş bir dizi oluşturmanız ve son olarak da diziyi alan maskesinin path alanına atamanız gerekir.
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
Mesaj alanlarını ve alt alanlarını güncelleme
MESSAGE alanlarının alt alanları olabilir (örneğin, üç adet target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros içeren MaximizeConversions) veya hiç alt alan içeremez (ManualCpm gibi).
Tanımlanmış alt alanı olmayan mesaj alanları
Alt alanlarla tanımlanmayan bir MESSAGE alanını güncellerken, daha önce belirtildiği gibi alan maskesi oluşturmak için FieldMaskUtil'i kullanın.
Tanımlı alt alanları olan mesaj alanları
Alt alanlarla tanımlanmış bir MESSAGE alanını bu mesajdaki alt alanlardan herhangi birini açık bir şekilde ayarlamadan güncellerken, sıfırdan alan maskesi oluşturan önceki örnekte olduğu gibi, değişebilir MESSAGE alt alanlarının her birini FieldMask öğesine manuel olarak eklemeniz gerekir.
Yaygın bir örnek, yeni teklif stratejisindeki alanların hiçbirini ayarlamadan bir kampanyanın teklif stratejisini güncellemektir. Aşağıdaki örnekte, bir kampanyanın, teklif stratejisindeki alt alanların hiçbiri ayarlanmadan MaximizeConversions teklif stratejisini kullanacak şekilde nasıl güncelleneceği gösterilmektedir.
Bu örnekte, FieldMaskUtil'in yerleşik karşılaştırmasını kullanmak hedeflenen hedefe ulaşmaz.
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ına neden olur.
# 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],
)
Aşağıdaki kod, bir kampanyayı alt alanlarından birini ayarlamadan MaximizeConversions teklif stratejisini kullanacak şekilde doğru şekilde nasıl güncelleyeceğinizi gösterir.
# 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],
)
Alanlar temizleniyor
Bazı alanlar açıkça temizlenebilir. Önceki örnekte olduğu gibi, bu alanları alan maskesine açık bir şekilde eklemeniz gerekir. Örneğin, MaximizeConversions teklif stratejisi kullanan bir kampanyanız olduğunu ve target_cpa_micros alanının 0 değerinden büyük bir değerle ayarlandığını varsayalım.
Aşağıdaki kod çalıştırılır; ancak, maximize_conversions.target_cpa_micros alan maskesine eklenmez ve bu nedenle target_cpa_micros alanında herhangi bir değişiklik yapılmaz:
# 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
Aşağıdaki kod, MaximizeConversions teklif stratejisinde target_cpa_micros alanının nasıl doğru şekilde temizleneceğini gösterir.
# 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
"Hatalı" kodun, Google Ads API protocol buffers'de optional olarak tanımlanan alanlarda amaçlandığı gibi çalıştığını unutmayın. Ancak target_cpa_micros bir optional alanı olmadığından, "yanlış" kod teklif stratejisini target_cpa alanını temizleyecek şekilde güncellemez.