Maschere di campo

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

Utilità FieldMasks

Il modo consigliato per generare maschere dei campi è usare la nostra maschera integrata dei campi società di servizi pubblici (FieldMasks), che consente di generare maschere di campo da un oggetto modificato, anziché creare partendo da zero.

Di seguito è riportato un esempio di aggiornamento di una campagna:

my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V17::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

Questo esempio crea prima un oggetto Campaign impostando il relativo nome risorsa utilizzando l'utilità ResourceNames, in modo che l'API la campagna da aggiornare.

L'esempio utilizza il parametro FieldMasks::all_set_fields_of() della campagna per produrre automaticamente una maschera dei campi che enumera tutti campi impostati. Puoi quindi passare la maschera restituita direttamente alla chiamata di aggiornamento.

FieldMasks::all_set_fields_of() è un metodo pratico per FieldMasks::field_mask() Confronta l'oggetto passato con un oggetto vuoto della stessa classe. Quindi nel precedente, puoi utilizzare anche

field_mask(Google::Ads::GoogleAds::V17::Resources::Campaign->new({}), $campaign)

anziché all_set_fields_of($campaign).

Creazione manuale di una maschera

Per creare una maschera dei campi da zero, devi prima creare una Google::Ads::GoogleAds::Common::FieldMask , crea un riferimento a un array compilato con i nomi di tutti i campi che intendi modificare e infine assegnare il riferimento all'array al valore-chiave paths.

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

Aggiornamento dei campi dell'oggetto e dei relativi campi secondari

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); o non possono averne affatto (ad esempio ManualCpm).

Campi dell'oggetto senza campi secondari definiti

Un campo oggetto in Perl equivale a un protobuf MESSAGE nel client in esecuzione su gRPC. Quando si aggiorna un campo dell'oggetto che non è definito con qualsiasi campo secondario, utilizza l'utilità FieldMasks per generare una maschera di campo, descritti sopra.

Campi oggetto con campi secondari definiti

Quando si aggiorna un campo dell'oggetto definito con campi secondari senza impostare uno qualsiasi dei campi secondari del messaggio, devi aggiungere manualmente ogni sottocampi dell'oggetto mutabile in FieldMask, come nell'esempio precedente che crea una maschera dei campi da zero.

Un esempio comune è l'aggiornamento della strategia di offerta di una campagna senza impostare alcuna campi della nuova strategia di offerta. L'esempio seguente mostra come aggiorna una campagna per utilizzare Strategia di offerta MaximizeConversions senza impostare nessuno dei campi secondari nella strategia di offerta.

In questo caso, utilizzando i metodi all_set_fields_of() e field_mask() del metodo L'utilità FieldMasks non raggiunge 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 FieldMaskError.FIELD_HAS_SUBFIELDS .

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::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::V17::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 il parametro MaximizeConversions senza impostare nessuno dei relativi campi secondari.

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::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::V17::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 precedente oppure impostando il campo su un valore vuoto o non definito. Ad esempio: supponi che tu abbia una campagna che utilizza la 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::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::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::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

Tieni presente che i campi con campi secondari nidificati possono essere cancellati solo cancellando ciascuno di i singoli campi secondari, come mostrato in Campi oggetto con campi secondari.