Nell'API Google Ads, gli aggiornamenti vengono effettuati utilizzando una maschera di campo. La maschera del campo elenca tutti i campi che intendi modificare con l'aggiornamento e tutti i campi specificati che non sono nella maschera del campo vengono ignorati, anche se vengono inviati al server.
FieldMaskUtil
Il metodo consigliato per generare maschere di campo è utilizzare la nostra utilità per le maschere di campo integrata, che nasconde molti dettagli specifici e consente di generare automaticamente maschere di campo monitorando le modifiche apportate ai campi dell'entità.
Ecco come generare una maschera di campo per l'aggiornamento di 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 crea prima un oggetto Campaign vuoto, quindi imposta il nome della risorsa per informare l'API della campagna da aggiornare.
Questo esempio utilizza 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 di campo all'operazione durante la sua creazione per la chiamata di modifica, come segue:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Questo metodo è consigliato quando stai effettuando un'operazione complicata e vuoi avere un controllo preciso di ogni passaggio. Tuttavia, nella maggior parte dei casi, puoi utilizzare l'utilità della 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, costruisce la maschera del campo in base alle modifiche apportate all'interno del blocco, crea l'operazione di aggiornamento e restituisce l'operazione finale con i campi update e update_mask già completati. Puoi anche passare una campagna al metodo campaign per 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à di libreria, devi prima creare un Google::Protobuf::FieldMask, poi completare un array 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
I campi MESSAGE possono avere dei campi secondari (ad es. MaximizeConversions che ne ha tre: target_cpa_micros, cpc_bid_ceiling_micros e cpc_bid_floor_micros) oppure non averne affatto (ad esempio ManualCpm).
Campi dei messaggi senza campi secondari definiti
Quando aggiorni un campo MESSAGE che non è definito con nessun campo secondario, utilizza FieldMaskUtil per generare una maschera del campo, come presentato in precedenza.
Campi dei messaggi con sottocampi definiti
Quando aggiorni un campo MESSAGE definito con sottocampi senza impostare esplicitamente alcun sottocampo del messaggio, devi aggiungere manualmente ognuno dei sottocampi MESSAGE modificabili MESSAGE a FieldMask, come nell'esempio precedente, in cui veniva creata una maschera di campo da zero.
Un esempio comune è l'aggiornamento della strategia di offerta di una campagna senza impostare alcun campo nella nuova strategia di offerta. L'esempio seguente mostra come aggiornare una campagna per utilizzare la strategia di offerta MaximizeConversions senza impostare nessuno dei campi secondari nella strategia di offerta.
In questo esempio, l'utilizzo del confronto integrato di FieldMaskUtil non consente di 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 impedire
la cancellazione accidentale dei campi e generare un
errore
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 la strategia di offerta 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. Ad esempio, supponiamo di avere una campagna che utilizza una strategia di offerta MaximizeConversions e che il campo target_cpa_micros sia impostato con un valore superiore a 0.
Viene eseguito il codice seguente; tuttavia, maximize_conversions.target_cpa_micros
non verrà aggiunto alla maschera del campo e non vengono apportate modifiche al
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 seguente codice 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 codice "errato" funziona come previsto per i campi definiti
come optional nell'API Google Ads protocol buffers. Tuttavia, poiché target_cpa_micros non è un campo optional, il codice "errato" non aggiorna la strategia di offerta per cancellare il campo target_cpa.