Maschere dei campi

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

Utilità FieldMasks

Il modo consigliato per generare maschere di campo è utilizzare l'utilità integrata (FieldMasks), che consente di generare maschere di campo da un oggetto modificato anziché crearle da zero.

Ecco un esempio di aggiornamento di una campagna:

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

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

my $campaign_operation =
  Google::Ads::GoogleAds::V25::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() nella campagna per generare automaticamente una maschera di campo che enumera tutti i 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. Nel codice precedente, puoi anche utilizzare:

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

anziché all_set_fields_of($campaign).

Creare manualmente una maschera

Per creare una maschera di campo da zero, devi prima creare un oggetto Google::Ads::GoogleAds::Common::FieldMask, quindi creare un riferimento di array compilato con i nomi di tutti i campi che intendi modificare e infine assegnare il riferimento di array al campo paths della maschera di campo:

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

Aggiorna i campi degli oggetti e i relativi campi secondari

I campi oggetto possono avere campi secondari (ad esempio MaximizeConversions, che include campi secondari come target_cpa_micros) o non averne affatto (ad esempio ManualCpm).

Campi oggetto senza campi secondari definiti

Un campo oggetto in Perl equivale a un MESSAGE protobuf nelle librerie client in esecuzione su gRPC. Quando aggiorni un campo oggetto non definito con alcun campo secondario, utilizza l'utilità FieldMasks per generare una maschera del campo, come descritto nella sezione precedente.

Campi oggetto con campi secondari definiti

Quando aggiorni un campo oggetto definito con campi secondari senza impostare esplicitamente nessuno dei campi secondari nel messaggio, devi aggiungere manualmente ciascuno dei campi secondari dell'oggetto modificabile a FieldMask, in modo simile all'esempio precedente che crea una maschera di campo da zero.

Un esempio comune è l'aggiornamento della strategia di offerta di una campagna senza impostare nessuno dei campi della nuova strategia di offerta. Il seguente esempio mostra come aggiornare una campagna in modo che utilizzi la strategia di offerta MaximizeConversions senza impostare nessuno dei sottocampi della 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 del campo che include maximize_conversions. Tuttavia, l'API Google Ads non consente questo comportamento per evitare di cancellare accidentalmente i campi e genera un errore FieldMaskError.FIELD_HAS_SUBFIELDS.

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::Resources::MaximizeConversions
      ->new(),
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask includes 'maximize_conversions',
# which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

# Sends the operation in a mutate request that results 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],
});

Il seguente esempio 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::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
  });

# Creates a field mask from the existing campaign and adds the mutable subfield
# on the MaximizeConversions bidding strategy to the field mask. Because this
# field is included in the field mask but excluded from the campaign object,
# the Google Ads API sets 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => $field_mask,
  });

Cancella campi

I campi possono essere cancellati in modo esplicito aggiungendoli alla maschera del campo come mostrato nell'esempio precedente o impostando il campo su un valore vuoto o non definito. Ad esempio, supponiamo che tu abbia una campagna che utilizza una strategia di offerta MaximizeConversions e che il campo target_cpa_micros sia impostato con un valore superiore a 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::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::Resources::MaximizeConversions
      ->new({
        targetCpaMicros => 0,
      }),
  });

# Constructs an operation using all_set_fields_of to derive the update mask,
# which includes 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V25::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 oggetto con sottocampi definiti.