Alan maskelerini kullanarak güncelleme

Google Ads API'de güncellemeler 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, 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 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, 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

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 otomatik olarak resource_name doldurulmuş yeni bir kampanya kaynağı 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ş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ı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 alanı olmayan 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ı

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 stratejisinde alt alanlardan herhangi biri ayarlanmadan bir kampanyanın MaximizeConversions teklif stratejisini kullanacak şekilde 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ı 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 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 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.