Google Ads API'de güncellemeler alan maskesi kullanılarak yapılır. Alan maskesi, güncellemeyle değiştirmeyi planladığınız tüm alanları listeler. Alan maskesinde olmayan belirtilmiş alanlar, sunucuya gönderilse bile yoksayılır.
FieldMaskUtil
Alan maskeleri oluşturmak için önerilen yöntem, belirli ayrıntıları gizleyen ve varlığın alanlarında yaptığınız değişiklikleri izleyerek alan maskelerini otomatik olarak oluşturmanıza olanak tanıyan yerleşik alan maskesi yardımcı programını kullanmaktı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 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, bloktan sonraki kampanyanın mevcut durumunu bloktan önceki kampanyanın ilk durumuyla karşılaştırır ve değiştirilen alanları numaralandıran bir alan maskesini otomatik olarak oluşturur. Bu alan maskesini, mutate çağrısı için oluştururken aşağıdaki şekilde işleme sağlayabilirsiniz:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Bu yöntem, karmaşık bir işlem oluştururken ve her adım üzerinde ayrıntılı kontrol sahibi olmak istediğinizde ö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ğı oluşturur, alanda yaptığınız değişikliklere göre alan maskesini oluşturur, güncelleme işlemini oluşturur ve update ile update_mask önceden doldurulmuş nihai 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ştirmeyi planladığınız 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ı, alt alanlara (ör. üç alt alanı olan MaximizeConversions: target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros) sahip olabilir veya hiç alt alanı olmayabilir (ör. ManualCpm).
Alt alanları tanımlanmamış mesaj alanları
Herhangi bir alt alanla tanımlanmamış bir MESSAGE alanını güncellerken daha önce gösterildiği gibi bir alan maskesi oluşturmak için FieldMaskUtil kullanın.
Alt alanları tanımlanmış ileti alanları
Bir iletideki alt alanların hiçbirini açıkça ayarlamadan alt alanlarla tanımlanmış bir MESSAGE alanını güncellerken, her bir değiştirilebilir MESSAGE alt alanını FieldMask'ye manuel olarak eklemeniz gerekir. Bu işlem, daha önce sıfırdan alan maskesi oluşturulan örnekte olduğu gibidir.
Bunun yaygın bir örneği, yeni teklif stratejisindeki alanlardan herhangi birini ayarlamadan bir kampanyanın teklif stratejisini güncellemedir. Aşağıdaki örnekte, teklif stratejisinde alt alanlardan herhangi biri ayarlanmadan bir kampanyanın MaximizeConversions teklif stratejisini kullanacak şekilde nasıl güncelleneceği gösterilmektedir.
Bu örnekte, FieldMaskUtil yerleşik karşılaştırmasını kullanmak amaçlanan hedefi karşı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ı oluşturur.
# 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 örneğe benzer şekilde, bu alanları alan maskesine açıkça eklemeniz gerekir. Örneğin, MaximizeConversions teklif stratejisinin kullanıldığı 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.
proto3 içinde, zorunlu olmayan bir skaler alanı varsayılan değerine (0) ayarlamak, yeni bir mesaj örneğinde ayarlanmamış olarak bırakmaktan ayırt edilemez. Sonuç olarak, FieldMaskUtil, maximize_conversions.target_cpa_micros yerine alan maskesine maximize_conversions ekler. Bu durum, 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 alanlarda beklendiği gibi çalıştığını unutmayın. Çünkü target_cpa_micros, MaximizeConversions üzerinde bir optional alanı değildir. Bu nedenle, update_mask.paths'a yolu açıkça eklemek, bu alanı temizlemek için gereklidir.