Nell'API Google Ads, gli aggiornamenti vengono effettuati utilizzando una maschera di campo. La maschera dei campi elenca tutti i campi che intendi modificare con l'aggiornamento e tutti i campi specificati che non sono presenti nella maschera del campo vengono ignorati, anche se vengono inviati al server.
Utilità FieldMask
Il modo consigliato per generare maschere di campo è utilizzare la nostra utilità per le maschere di campo integrata (FieldMasks), che consente di generare maschere di campo da un oggetto modificato anziché crearle da zero.
Di seguito è riportato un esempio per l'aggiornamento di una campagna:
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
status => PAUSED,
networkSettings =>
Google::Ads::GoogleAds::V16::Resources::NetworkSettings->new({
targetSearchNetwork => "false"
})
});
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
Questo esempio crea innanzitutto un oggetto Campaign impostando il nome della risorsa
utilizzando l'utilità ResourceNames, in modo che l'API sappia
quale campagna viene aggiornata.
L'esempio utilizza il metodo FieldMasks::all_set_fields_of() sulla campagna per produrre automaticamente una maschera di campo che elenca tutti i campi impostati. Puoi quindi passare la maschera restituita direttamente alla chiamata di aggiornamento.
FieldMasks::all_set_fields_of() è un metodo di convenienza per
FieldMasks::field_mask().
Confronta l'oggetto passato con un oggetto vuoto della stessa classe. Nel codice riportato sopra, potresti usare anche
field_mask(Google::Ads::GoogleAds::V16::Resources::Campaign->new({}), $campaign)
anziché all_set_fields_of($campaign).
Creazione manuale di una maschera
Per creare una maschera di campo da zero, devi prima creare un oggetto Google::Ads::GoogleAds::Common::FieldMask, poi creare un riferimento array compilato con i nomi di tutti i campi che intendi modificare e infine assegnare il riferimento dell'array al campo paths della maschera di campo.
my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
paths => ["status", "name"]
});
Aggiornamento dei campi degli oggetti e dei relativi sottocampi
I campi degli oggetti possono avere campi secondari (come MaximizeConversions che ne ha tre: target_cpa_micros, cpc_bid_ceiling_micros e cpc_bid_floor_micros); oppure non possono averne del tutto nessuno (ad esempio ManualCpm).
Campi degli oggetti senza campi secondari definiti
Un campo oggetto in Perl equivale a un protobuf MESSAGE nelle librerie client in esecuzione su gRPC. Quando aggiorni un campo oggetto che non è definito con alcun sottocampi, utilizza l'utilità FieldMask per generare una maschera di campo, come descritto sopra.
Campi degli oggetti con campi secondari definiti
Quando aggiorni un campo oggetto definito con sottocampi senza impostare esplicitamente alcun sottocampo del messaggio, devi aggiungere manualmente ciascuno dei sottocampi dell'oggetto mutabile a FieldMask, come nell'esempio precedente, che crea 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 riportato di seguito mostra come aggiornare una campagna per utilizzare la strategia di offerta MaximizeConversions senza impostare nessuno dei campi secondari nella strategia di offerta.
In questo caso, l'utilizzo dei metodi all_set_fields_of() e field_mask() dell'utilità FieldMasks non consente di raggiungere l'obiettivo previsto.
L'esempio seguente genera una maschera di campo che include maximize_conversions. Tuttavia, l'API Google Ads non consente questo comportamento per evitare di cancellare accidentalmente i campi e generare un errore FieldMaskError.FIELD_HAS_SUBFIELDS.
# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions =>
Google::Ads::GoogleAds::V16::Resources::MaximizeConversions->new()
});
# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
customerId => $customer_id,
operations => [$campaign_operation]
});
L'esempio seguente mostra come aggiornare correttamente una campagna per utilizzare la strategia di offerta MaximizeConversions senza impostare nessuno dei relativi campi secondari.
# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
)
});
# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are included in the field mask but excluded from the campaign object,
# the Google Ads API will set the campaign's bidding strategy to a
# MaximizeConversions object with none of its subfields set.
# Only include 'maximize_conversions.target_cpa_micros' in the field mask
# as it is the only mutable subfield on MaximizeConversions when used as a
# standard bidding strategy.
#
# Learn more about standard and portfolio bidding strategies here:
# https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";
# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => $field_mask
});
Cancellazione dei campi
I campi possono essere cancellati in modo esplicito aggiungendoli alla maschera del campo come mostrato sopra oppure impostando un valore vuoto o non definito per il campo. 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 maggiore di 0.
# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions => Google::Ads::GoogleAds::V16::Resources::MaximizeConversions->new({
targetCpaMicros => 0
})
});
# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
Tieni presente che i campi con sottocampi nidificati possono essere cancellati solo cancellando ciascuno dei singoli sottocampi, come mostrato in Campi dell'oggetto con sottocampi definiti.