Mises à jour concernant l'utilisation des 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.

FieldMaskUtil

Pour générer des masques de champ, nous vous recommandons d'utiliser notre masque de champ intégré. qui masque de nombreux détails spécifiques et vous permet de générer des champs masque automatiquement en surveillant les modifications que vous apportez aux champs de l'entité.

Voici 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 le nom de ressource sur informer l'API de la mise à jour de la campagne.

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

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

Cette méthode est recommandée lorsque vous effectuez une opération compliquée souhaitent contrôler précisément chaque étape. Toutefois, dans la plupart des cas, vous pouvez utiliser un utilitaire simple de bibliothèque Ruby:

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

Cette méthode crée automatiquement une ressource de campagne vide, 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 campagne à la méthode campaign pour ainsi que l'état de départ de la campagne. Ce modèle fonctionne pour tous ressources compatibles avec l'opération de mise à jour.

Créer manuellement un masque

Pour créer un masque de champ à partir de zéro, sans utiliser d'utilitaire de bibliothèque, vous devez crée d'abord un élément Google::Protobuf::FieldMask, puis génère un tableau contenant les noms de tous les champs que vous avez l'intention de modifier, et enfin attribuer le tableau au champ path du masque de champ.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

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

Les champs MESSAGE peuvent comporter des sous-champs (comme MaximizeConversions, qui en compte trois : target_cpa_micros, cpc_bid_ceiling_micros et cpc_bid_floor_micros), ou n'en avoir aucun (comme ManualCpm).

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 la méthode FieldMaskUtil pour générer un masque de champ, comme présenté précédemment.

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 ajouter manuellement chacun des sous-champs MESSAGE modifiables au FieldMask, comme pour le champ exemple précédent qui a créé un masque de champ à partir de zéro.

Par exemple, vous pouvez modifier 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 utiliser MaximizeConversions stratégie d'enchères sans définir aucun des sous-champs de la stratégie d'enchères.

Dans cet exemple, la comparaison intégrée de FieldMaskUtil ne permet pas atteindre l'objectif visé.

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'empêcher si vous effacez accidentellement des champs, FieldMaskError.FIELD_HAS_SUBFIELDS .

Avertissement : Le code suivant génère une 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 will result 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],
)

Le code suivant montre comment mettre à jour correctement une campagne afin d'utiliser la classe MaximizeConversions sans définir aucun de ses sous-champs.

Succès : le code ci-dessous met à jour la stratégie d'enchères de la campagne.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
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 des 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. 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:

Avertissement :Ce code génère une erreur.

# 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 will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result 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 will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Le code suivant montre comment effacer correctement le target_cpa_micros. de la stratégie d'enchères MaximizeConversions.

Opération réussie :le code suivant efface le target_cpa_micros.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them 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 may add a block here with
# other changes that will automatically get 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 will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Notez que l'erreur "incorrecte" fonctionne comme prévu pour les champs définis en tant que optional dans l'API Google Ads protocol buffers. Mais puisque le target_cpa_micros correspond à et non un champ optional, le mot "incorrect" le code ne met pas à jour les enchères pour effacer le champ target_cpa.

Important :Si vous avez l'intention d'effacer un champ, la méthode la plus sûre consiste à ajouter explicitement ce champ au masque de champ.