Masques de champ

Dans l'API Google Ads, les mises à jour sont effectuées à l'aide d'un masque de champ. Le masque de champ répertorie tous les champs que vous souhaitez modifier lors de la mise à jour. Tous les champs spécifiés qui ne figurent pas dans le masque de champ sont ignorés, même s'ils sont envoyés au serveur.

Utilitaire FieldMasks

La méthode recommandée pour générer des masques de champ consiste à utiliser notre utilitaire de masque de champ intégré (FieldMasks), qui vous permet de générer des masques de champ à partir d'un objet modifié au lieu de les créer de toutes pièces.

Voici un exemple de mise à jour d'une campagne :

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

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

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

Cet exemple crée d'abord un objet Campaign en définissant son nom de ressource à l'aide de l'utilitaire ResourceNames, afin que l'API sache quelle campagne est mise à jour.

L'exemple utilise la FieldMasks::all_set_fields_of() méthode sur la campagne pour générer automatiquement un masque de champ qui énumère tous les champs définis. Vous pouvez ensuite transmettre le masque renvoyé directement à l'appel de mise à jour.

FieldMasks::all_set_fields_of() est une méthode pratique pour FieldMasks::field_mask(). Elle compare l'objet que vous avez transmis à un objet vide de la même classe. Dans le code précédent, vous pouvez également utiliser :

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

au lieu de all_set_fields_of($campaign).

Créer manuellement un masque

Pour créer un masque de champ de toutes pièces, vous devez d'abord créer un Google::Ads::GoogleAds::Common::FieldMask objet, puis créer une référence de tableau contenant les noms de tous les champs que vous souhaitez modifier. Enfin, vous devez attribuer la référence de tableau au champ paths du masque de champ :

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

Mettre à jour les champs d'objet et leurs sous-champs

Les champs d'objet peuvent comporter des sous-champs (par exemple, MaximizeConversions, qui inclut des sous-champs tels que target_cpa_micros) ou aucun (par exemple, ManualCpm).

Champs d'objet sans sous-champs définis

Un champ d'objet en Perl équivaut à un MESSAGE protobuf dans les bibliothèques clientes exécutées sur gRPC. Lorsque vous mettez à jour un champ d'objet qui n'est défini avec aucun sous-champ, utilisez l'utilitaire FieldMasks pour générer un masque de champ, comme décrit dans la section précédente.

Champs d'objet avec sous-champs définis

Lorsque vous mettez à jour un champ d'objet défini avec des sous-champs sans définir explicitement l'un d'eux dans ce message, vous devez ajouter manuellement chacun des sous-champs d'objet modifiables au FieldMask, comme dans l'exemple précédent qui crée un masque de champ de toutes pièces.

Un exemple courant consiste à mettre à jour la stratégie d'enchères d'une campagne sans définir aucun champ dans la nouvelle stratégie d'enchères. L'exemple suivant montre comment mettre à jour une campagne pour qu'elle utilise la stratégie d'enchères MaximizeConversions sans définir aucun sous-champ dans la stratégie d'enchères.

Dans ce cas, l'utilisation des méthodes all_set_fields_of() et field_mask() de l'utilitaire FieldMasks n'atteint pas l'objectif souhaité.

L'exemple suivant génère un masque de champ qui inclut maximize_conversions. Toutefois, l'API Google Ads n'autorise pas ce comportement pour éviter d'effacer accidentellement des champs et génère une FieldMaskError.FIELD_HAS_SUBFIELDS erreur.

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

L'exemple suivant montre comment mettre à jour correctement une campagne pour qu'elle utilise la stratégie d'enchères MaximizeConversions sans définir aucun de ses sous-champs.

# Creates a campaign with the proper resource name.
my $campaign =
  Google::Ads::GoogleAds::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::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::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => $field_mask,
  });

Effacer les champs

Les champs peuvent être effacés explicitement en les ajoutant au masque de champ, comme illustré dans l'exemple précédent, ou en définissant le champ sur une valeur vide ou non définie. Supposons, par exemple, que vous ayez une campagne qui utilise une stratégie d'enchères MaximizeConversions et que le champ target_cpa_micros soit défini sur une valeur supérieure à 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::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::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

Notez que les champs avec des sous-champs imbriqués ne peuvent être effacés qu'en effaçant chacun des sous-champs individuels, comme illustré dans Champs d'objet avec sous-champs définis.