Aggiornamenti utilizzando le maschere di campo

Nell'API Google Ads, gli aggiornamenti vengono eseguiti utilizzando una maschera dei campi. La maschera di campi elenca tutti i campi che intendi modificare con l'aggiornamento ed eventuali campi specificati che non sono presenti nella maschera di campi vengono ignorati, anche se inviati al server.

FieldMaskUtil

Il modo consigliato per generare maschere dei campi è usare la nostra maschera integrata dei campi che nasconde molti dettagli specifici e consente di generare campi monitorando le modifiche apportate ai campi dell'entità.

Ecco come generare una maschera dei campi per aggiornare una campagna:

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

Il codice prima crea un oggetto Campaign vuoto, poi imposta il nome risorsa su comunicare all'API l'aggiornamento della campagna.

In questo esempio viene utilizzato il metodo client.field_mask.with nella campagna per iniziare il blocco che comprende gli aggiornamenti. Al termine di questo blocco, l'utilità confronta lo stato corrente della campagna dopo il blocco con lo stato iniziale della campagna prima del blocco e genera automaticamente una maschera di campo che enumera i campi modificati. Puoi fornire questa maschera del campo durante la sua creazione per la chiamata di modifica:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Questo metodo è consigliato quando esegui un'operazione complicata che vogliono avere un controllo preciso su ogni passo. Tuttavia, nella maggior parte dei casi, puoi utilizzare un'utilità di libreria Ruby più semplice:

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

Questo metodo crea automaticamente una nuova risorsa di campagna vuota, la maschera del campo basata sulle modifiche apportate all'interno del blocco, crea l'aggiornamento e restituisce l'operazione finale con update e update_mask è già compilato. Puoi anche trasferire una campagna al metodo campaign a specificare anche lo stato iniziale della campagna. Questo pattern funziona per tutte le risorse che supportano l'operazione di aggiornamento.

Creazione manuale di una maschera

Per creare una maschera di campo da zero, senza utilizzare utilità della libreria, devi prima creare un Google::Protobuf::FieldMask, poi un array compilato con i nomi di tutti i campi che intendi modificare e infine assegnare l'array al campo path della maschera di campo.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

Aggiornamento dei campi dei messaggi e dei relativi campi secondari

MESSAGE campi possono avere campi secondari (ad esempio MaximizeConversions, che ne ha tre: target_cpa_micros, cpc_bid_ceiling_micros e cpc_bid_floor_micros) oppure non possono averne affatto (ad esempio ManualCpm).

Campi dei messaggi senza sottocampi definiti

Quando aggiorni un campo MESSAGE non definito con sottocampi, utilizza FieldMaskUtil per generare una maschera dei campi, come illustrato in precedenza.

Campi dei messaggi con sottocampi definiti

Quando aggiorni un campo MESSAGE definito con campi secondari senza impostare in modo esplicito uno qualsiasi dei sottocampi di quel messaggio, devi aggiungere manualmente per ciascuno dei sottocampi MESSAGE mutabili in FieldMask, simili un esempio precedente di creazione di una maschera di campo da zero.

Un esempio comune è l'aggiornamento della strategia di offerta di una campagna senza impostare qualsiasi campo nella nuova strategia di offerta. L'esempio seguente dimostra come aggiornare una campagna in modo da utilizzare la strategia di offerta MaximizeConversions senza impostare nessuno dei campi secondari della strategia di offerta.

Per questo esempio, il confronto integrato di FieldMaskUtil non raggiungere l'obiettivo previsto.

Il seguente codice genera una maschera di campo che include maximize_conversions. Tuttavia, l'API Google Ads non consente questo comportamento per evitare la cancellazione accidentale dei campi produce un FieldMaskError.FIELD_HAS_SUBFIELDS .

# 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],
)

Il seguente codice mostra come aggiornare correttamente una campagna per utilizzare il MaximizeConversions senza impostare nessuno dei relativi campi secondari.

# 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],
)

Cancellazione dei campi

Alcuni campi possono essere cancellati esplicitamente. Come nell'esempio precedente, devi aggiungere esplicitamente questi campi alla maschera di campo. Ad esempio, supponiamo che tu abbia una campagna che utilizza una strategia di offerta MaximizeConversions e che Il campo target_cpa_micros è impostato con un valore maggiore di 0.

Viene eseguito il codice riportato di seguito. tuttavia, maximize_conversions.target_cpa_micros non verranno aggiunte alla maschera del campo e quindi non verranno apportate modifiche alla Campo target_cpa_micros:

# 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

Il codice seguente mostra come cancellare correttamente il campo target_cpa_micros nella strategia di offerta MaximizeConversions.

# 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

Tieni presente che il messaggio "Risposta errata" funziona come previsto per i campi definiti come optional nell'API Google Ads protocol buffers. Ma poiché target_cpa_micros è non è un campo optional, l'errore il codice non aggiorna l'offerta per cancellare il campo target_cpa.