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 figurent pas dans le masque de champ sont ignorés, même s'ils sont envoyés au serveur.
FieldMaskUtil
Pour générer des masques de champ, nous vous recommandons d'utiliser notre masque de champ intégré. qui vous permet de générer des masques de champ à partir d'un objet modifié au lieu en les construisant à partir de zéro.
Voici un exemple de mise à jour d'une campagne:
// Creates a Campaign object with the proper resource name and any other changes.
Campaign campaign =
Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setStatus(CampaignStatus.PAUSED)
.build();
// Constructs an operation that will update the campaign, using the FieldMasks'
// allSetFieldsOf utility to derive the update mask. This mask tells the Google
// Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// Sends the operation in a mutate request.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Cet exemple crée d'abord un objet Campaign
vide, puis définit sa ressource
afin que l'API sache quelle campagne est mise à jour.
L'exemple utilise la méthode FieldMasks.allSetFieldsOf()
au niveau de la campagne pour
génère automatiquement un masque de champ qui énumère tous les champs définis. Vous pouvez ensuite
transmettre directement le masque renvoyé
à l'appel de mise à jour.
Si vous devez utiliser un objet existant pour mettre à jour quelques champs, vous pouvez modifiez le code comme suit:
Campaign existingCampaign;
// Obtains existingCampaign from elsewhere.
...
// Creates a new campaign based off the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
existingCampaign.toBuilder()
.setStatus(CampaignStatus.PAUSED)
.build();
// Constructs an operation that will update the campaign, using the FieldMasks'
// compare utility to derive the update mask. This mask tells the Google Ads API
// which attributes of the campaign you want to change.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaignToUpdate)
.setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
.build();
// Sends the operation in a mutate request.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Pour créer un masque de champ à partir de zéro, vous devez d'abord créer un
FieldMask
puis ajoutez le nom de chacun des champs que vous souhaitez modifier
.
FieldMask fieldMask =
FieldMask.newBuilder()
.addPaths("status")
.addPaths("name")
.build();
Mettre à jour des champs de message et leurs sous-champs
Les champs MESSAGE
peuvent comporter des sous-champs (tels que
MaximizeConversions
, qui en comporte trois:
target_cpa_micros
,
cpc_bid_ceiling_micros
et cpc_bid_floor_micros
), ou n'en doivent pas
(ManualCpm
, par exemple).
Champs du message sans sous-champs définis
Lors de la mise à jour d'un champ MESSAGE
qui n'est défini avec aucun sous-champ, utilisez
FieldMaskUtil pour générer un masque de champ, comme décrit ci-dessus.
Champs de message avec des sous-champs définis
Lors de la mise à jour d'un champ MESSAGE
défini avec des sous-champs sans
en définissant explicitement l'un des sous-champs de ce message, vous devez
ajoutez chacun des sous-champs MESSAGE
modifiables au FieldMask
, comme suit :
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 allSetFieldsOf()
et compare()
de la
FieldMaskUtil 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 ne permet 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.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setMaximizeConversions(MaximizeConversions.newBuilder().build())
.build();
// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// Sends the operation in a mutate request that will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(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 object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.build();
// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) 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 will set the campaign's
// bidding strategy to a MaximizeConversions object without any of its subfields
// set.
FieldMask fieldMask = FieldMasks.allSetFieldsOf(campaign)
.toBuilder()
// 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
.addPaths("maximize_conversions.target_cpa_micros")
.build();
// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(fieldMask)
.build();
Effacement des champs
Certains champs peuvent être explicitement effacés. Comme dans l'exemple ci-dessus, vous devez
ajouter explicitement ces champs au masque de champ. Par exemple, supposons que vous avez
campagne qui utilise une stratégie d'enchères MaximizeConversions
et que la
La valeur du champ target_cpa_micros
est supérieure à 0.
Le code suivant s'exécute : En revanche, le maximize_conversions.target_cpa_micros
ne sont pas ajoutés au masque de champ et aucune modification n'est donc apportée au
Champ target_cpa_micros
:
// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
Campaign campaign =
Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setMaximizeConversions(
MaximizeConversions.newBuilder().setTargetCpa(0).build())
.setStatus(CampaignStatus.PAUSED)
.build();
// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
L'exemple suivant montre comment effacer correctement le target_cpa_micros
.
de la stratégie d'enchères MaximizeConversions
.
// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.build();
// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.allSetFieldsOf(campaign)
.toBuilder()
.addPaths("maximize_conversions.target_cpa_micros")
.build();
// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(fieldMask))
.build();
Notez que l'erreur "incorrecte" l'exemple ci-dessus fonctionne comme prévu pour les champs
sont définis comme optional
dans l'API Google Ads ;
protocol buffers
Mais puisque le
target_cpa_micros
n'est pas un champ optional
, le mot "incorrect" exemple ne met pas à jour
pour effacer le champ target_cpa
.