Mises à jour à l'aide de 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 avec 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.

FieldMaskUtil

La méthode recommandée pour générer des masques de champ consiste à utiliser l'utilitaire de masque de champ intégré, qui masque des détails spécifiques et vous permet de générer automatiquement des masques de champ en surveillant les modifications que vous apportez aux champs de l'entité.

L'exemple suivant montre comment générer un masque de champ pour mettre à jour une campagne :

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Le code crée d'abord un objet Campaign vide, puis définit son nom de ressource pour informer l'API de la campagne en cours de mise à jour.

Cet exemple utilise la méthode client.field_mask.with sur la campagne pour commencer le bloc englobant les mises à jour. À la fin de ce bloc, l'utilitaire compare l'état actuel de la campagne après le bloc avec l'état initial de la campagne avant le bloc, et génère automatiquement un masque de champ énumérant les champs modifiés. Vous pouvez fournir ce masque de champ à l'opération lors de sa construction pour l'appel de mutation comme suit :

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Cette méthode est recommandée lorsque vous créez une opération complexe et que vous souhaitez contrôler chaque étape de manière précise. Toutefois, dans la plupart des cas, vous pouvez transmettre le nom de ressource (ou une instance de ressource existante) à la méthode de fabrique de la bibliothèque Ruby :

campaign_resource_name = client.path.campaign(customer_id, campaign_id)

operation =
  client.operation.update_resource.campaign(campaign_resource_name) do |c|
    c.status = :PAUSED
    c.network_settings = client.resource.network_settings do |ns|
      ns.target_search_network = false
    end
  end

Lorsqu'une chaîne de nom de ressource est fournie, cette méthode crée automatiquement une nouvelle ressource de campagne avec resource_name renseigné, construit le masque de champ en fonction des modifications que vous apportez dans le bloc, crée l'opération de mise à jour et renvoie l'opération finale avec update et update_mask déjà renseignés. Vous pouvez également transmettre une instance proto Campaign existante au lieu d'une chaîne de nom de ressource pour spécifier l'état de départ de la campagne. Ce modèle fonctionne pour toutes les ressources qui prennent en charge l'opération de mise à jour.

Créer manuellement un masque de champ

Pour créer un masque de champ à partir de zéro sans utiliser les utilitaires de la bibliothèque, créez un Google::Protobuf::FieldMask, créez un tableau contenant les noms de tous les champs que vous souhaitez modifier, puis attribuez le tableau au champ paths du masque de champ :

mask = Google::Protobuf::FieldMask.new
mask.paths = ['status', 'name']

Mettre à jour les champs de message et leurs sous-champs

MESSAGE champs peuvent avoir des sous-champs (tels que MaximizeConversions, qui en comporte trois : target_cpa_micros, cpc_bid_ceiling_micros et cpc_bid_floor_micros), ou aucun (comme ManualCpm).

Champs de message sans sous-champs définis

Lorsque vous mettez à jour un champ MESSAGE qui n'est défini avec aucun sous-champ, utilisez FieldMaskUtil pour générer un masque de champ, comme indiqué précédemment.

Champs de message avec sous-champs définis

Lorsque vous mettez à jour un champ MESSAGE défini avec des sous-champs sans définir explicitement aucun de ces sous-champs dans ce message, vous devez ajouter manuellement chacun des sous-champs MESSAGE modifiables au FieldMask, comme dans l'exemple précédent qui a créé un masque de champ à partir de zéro.

Un exemple courant consiste à mettre à jour la stratégie d'enchères d'une campagne sans définir aucun des champs de 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 des sous-champs de la stratégie d'enchères.

Dans cet exemple, l'utilisation de la comparaison intégrée de FieldMaskUtil n'atteint pas l'objectif souhaité.

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

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that results in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask starts empty. You can modify
# other fields in this block, except the message field intended to have a
# blank subfield.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

Effacer les champs

Certains champs peuvent être effacés explicitement. Comme dans l'exemple précédent, vous devez ajouter explicitement ces champs au masque de champ. 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.

Dans proto3, la définition d'un champ scalaire non facultatif sur sa valeur par défaut (0) est identique à son absence de définition dans une nouvelle instance de message. Par conséquent, FieldMaskUtil ajoute maximize_conversions au masque de champ au lieu de maximize_conversions.target_cpa_micros, ce qui génère une erreur FieldMaskError.FIELD_HAS_SUBFIELDS.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation includes 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it results in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation fails because the field mask is invalid.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

# Create a campaign including the maximize conversions fields right away, since
# they are manually added to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You can add a block here with
# other changes that are automatically added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation succeeds because the correct field mask is specified.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

Notez que l'approche de comparaison automatique fonctionne comme prévu pour les champs définis comme optional dans les tampons de protocole de l'API Google Ads. Étant donné que target_cpa_micros n'est pas un champ optional dans MaximizeConversions, vous devez ajouter explicitement le chemin à update_mask.paths pour l'effacer.