Cette page a été traduite par l'API Cloud Translation.

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 suite à la mise à jour, ainsi que tous les champs spécifiés ; qui ne sont pas dans le masque de champ sont ignorés, même s'ils sont envoyés au serveur.

Utilitaire FieldMasks

Pour générer des masques de champ, nous vous recommandons d'utiliser notre masque de champ intégré. fournisseur d'énergie (FieldMasks), qui vous permet de générer des masques de champ à partir d'un objet modifié au lieu de créer à partir de zéro.

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

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)
  });

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

Cet exemple utilise la FieldMasks::all_set_fields_of() de la campagne pour générer automatiquement un masque de champ qui énumère toutes à l'aide de 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 transmis à un objet vide de la même classe. Dans la section code ci-dessus, vous pouvez également utiliser

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

au lieu de all_set_fields_of($campaign).

Créer manuellement un masque

Pour créer un masque de champ à partir de zéro, vous devez d'abord créer un Google::Ads::GoogleAds::Common::FieldMask puis créez une référence de tableau avec les noms de tous les champs que vous avez l'intention de modifier, puis attribuez la référence au tableau au masque de champ paths.

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

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

Les champs d'objet peuvent comporter des sous-champs (comme MaximizeConversions, qui comporte trois: target_cpa_micros, cpc_bid_ceiling_micros et cpc_bid_floor_micros) ; ou il peut n'en avoir aucune (par exemple, ManualCpm).

Champs d'objet sans sous-champs définis

Un champ d'objet dans Perl équivaut à un protobuf MESSAGE dans le client s'exécutant sur gRPC. Lors de la mise à jour d'un champ d'objet non défini avec n'importe quel sous-champ, utilisez l'utilitaire FieldMasks pour générer un masque de champ, comme décrites ci-dessus.

Champs d'objet avec des sous-champs définis

Lors de la mise à jour d'un champ d'objet défini avec des sous-champs sans indiquer explicitement en définissant l'un des sous-champs de ce message, vous devez ajouter manuellement sous-champs d'objet mutable en FieldMask, comme dans l'exemple ci-dessus qui crée un masque de champ à partir de zéro.

Par exemple, vous pouvez mettre à jour la stratégie d'enchères d'une campagne sans définir des champs de la nouvelle stratégie d'enchères. L'exemple ci-dessous montre comment mettre à jour une campagne afin d'utiliser MaximizeConversions stratégie d'enchères sans définir aucun des sous-champs de la stratégie d'enchères.

Dans ce cas, les méthodes all_set_fields_of() et field_mask() de la L'utilitaire FieldMasks n'atteint pas l'objectif visé.

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 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'exemple suivant montre comment mettre à jour correctement une campagne afin d'utiliser la classe MaximizeConversions sans définir aucun de ses sous-champs.

# 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
  });

Effacer les champs

Les champs peuvent être effacés explicitement en les ajoutant au masque de champ, comme indiqué. ci-dessus, ou en définissant le champ sur une valeur vide ou non définie. Par exemple : partent du principe que l'une de vos campagnes utilise une stratégie d'enchères MaximizeConversions et que le champ target_cpa_micros est défini avec 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::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)
  });

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