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önderilmiş olsa bile yoksayılır.
FieldMaskUtil
Alan maskeleri oluşturmanın önerilen yolu, yerleşik alan maskesi yardımcı programımızı kullanmaktır. Bu yardımcı program, belirli ayrıntıların çoğunu gizler ve öğenin alanlarında yaptığınız değişiklikleri izleyerek alan maskelerini otomatik olarak oluşturmanıza olanak tanır.
Bir kampanyayı güncellemek için alan maskesi oluşturmak üzere aşağıdaki adımları uygulayın:
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 ilk olarak boş bir Campaign nesnesi oluşturur, ardından kaynak adını API'yi güncellenen kampanya hakkında bilgilendirecek şekilde ayarlar.
Bu örnekte, güncellemeleri içeren bloğu başlatmak için kampanyadaki 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ı listeleyen bir alan maskesi otomatik olarak oluşturur. Bu alan maskesini, mutasyon ç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 yaparken her adım üzerinde ayrıntılı kontrol sahibi olmak istiyorsanız bu yöntemi kullanmanız ö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 nihai işlemi update ve update_mask ile doldurulmuş olarak döndürür. Kampanyanın başlangıç durumunu da belirtmek için campaign yöntemine bir kampanya da iletebilirsiniz. Bu kalıp, güncelleme işlemini destekleyen tüm kaynaklarda işe yarar.
Manuel olarak maske oluşturma
Kitaplık yardımcı programları kullanmadan sıfırdan bir alan maskesi oluşturmak için önce bir Google::Protobuf::FieldMask oluşturur, ardından değiştirmek istediğiniz tüm alanların adlarıyla doldurulmuş bir dizi oluşturur ve son olarak diziyi alan maskesinin path alanına atarsınız.
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
Mesaj alanlarını ve alt alanlarını güncelleme
MESSAGE alanlarında alt alanlar olabilir (ör. target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros olmak üzere üç alt alanı olan MaximizeConversions) veya hiç alt alan olmayabilir (ör. ManualCpm).
Tanımlanmış alt alanı olmayan mesaj alanları
Herhangi bir alt alanla tanımlanmayan bir MESSAGE alanını güncellerken, daha önce açıklandığı gibi bir alan maskesi oluşturmak için FieldMaskUtil'i kullanın.
Tanımlanmış alt alanları olan ileti alanları
Alt alanlarla tanımlanan bir MESSAGE alanını, bu iletideki alt alanlardan herhangi birini açıkça ayarlamadan güncellerken, sıfırdan alan maskesi oluşturan önceki örneğe benzer şekilde, değiştirilebilir MESSAGE alt alanlarının her birini FieldMask alanına 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, teklif stratejisindeki alt alanlardan hiçbirini ayarlamadan bir kampanyanın MaximizeConversions teklif stratejisini kullanacak şekilde nasıl güncelleneceği gösterilmektedir.
Bu örnekte, FieldMaskUtil'ın yerleşik karşılaştırması kullanılarak istenen hedefe ulaşı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 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 kodda, bir kampanyanın alt alanlarından herhangi birini ayarlamaksızın MaximizeConversions teklif stratejisini kullanacak şekilde nasıl doğru şekilde güncelleneceği gösterilmektedir.
# 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ı temizleme
Bazı alanlar açıkça temizlenebilir. Önceki örneğe benzer şekilde, bu alanları alan maskesine açıkça eklemeniz gerekir. Örneğin, MaximizeConversions teklif stratejisi kullanan bir kampanyanız olduğunu ve target_cpa_micros alanının 0'den 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 stratejisindeki target_cpa_micros alanının nasıl doğru şekilde temizleneceğini göstermektedir.
# 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
"Yanlış" kodunun, Google Ads API'de optional olarak tanımlanan alanlar için amaçlandığı gibi çalıştığını unutmayın protocol buffers. Ancak target_cpa_micros bir optional alanı olmadığından "yanlış" kod, teklif stratejisini target_cpa alanını temizleyecek şekilde güncellemez.