Masques de champ

Dans l'API Google Ads, un masque de champ est utilisé pour fournir la liste des champs qu'une requête d'API doit mettre à jour. Tout champ non spécifié dans le masque de champ est ignoré, même s'il est envoyé au serveur.

Classe FieldMasks

La méthode recommandée pour générer des masques de champ dans la bibliothèque cliente .NET consiste à utiliser la classe utilitaire FieldMasks intégrée, 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 qui utilise la méthode FieldMasks.AllSetFieldsOf pour générer un masque de champ énumérant tous les champs définis. Vous pouvez ensuite transmettre le masque de champ généré directement à l'appel de mise à jour :

// Update campaign by setting its status to paused, and "Search network" to
// false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Il peut arriver que vous deviez travailler avec un objet existant et mettre à jour quelques champs. Dans ce cas, utilisez plutôt la méthode FieldMasks.FromChanges. Cette méthode génère un masque de champ qui représente la différence entre deux objets :

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

Gérer les erreurs FieldMaskError.FIELD_HAS_SUBFIELDS

Dans de rares cas, vous devrez peut-être définir un champ de message sans mettre à jour aucun de ses sous-champs. Prenons l'exemple suivant :

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Cet appel d'API échoue et renvoie une erreur FieldMaskError.FIELD_HAS_SUBFIELDS. Étant donné que MaximizeConversions comporte des sous-champs, le serveur de l'API Google Ads s'attend à ce que les masques de champ des sous-champs modifiables soient présents dans la requête. Toutefois, FieldMasks ne peut pas générer automatiquement de masques de sous-champs dans ce cas, car la requête ne définit aucun sous-champ.

Dans ce cas, vous pouvez ajouter manuellement des chemins à fieldMask.Paths (qui est un RepeatedField<string>) :

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
// 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 at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Effacer les champs

L'API Google Ads permet d'effacer certaines valeurs de champ. Pour effacer un champ, vous devez l'inclure manuellement dans le masque de champ tout en le laissant non défini dans l'objet de ressource. Définir un champ sur sa valeur par défaut (par exemple, 0 pour un champ int64) n'efface pas le champ.

L'exemple de code suivant montre comment effacer le champ target_cpa_micros d'une stratégie d'enchères MaximizeConversions :

Code correct

Le code suivant efface le champ target_cpa_micros, car il ajoute maximize_conversions.target_cpa_micros au masque de champ sans définir la propriété campaign.MaximizeConversions.TargetCpaMicros :

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Code incorrect

Le code suivant n'efface pas le champ target_cpa_micros, car il le définit sur 0. L'utilitaire FieldMasks et le serveur de l'API Google Ads ignorent cette valeur lorsque TargetCpaMicros est défini sur 0 ou lorsque le chemin d'accès est omis du masque. Le serveur ne renvoie pas d'erreur :

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts to clear the target_cpa_micros
// field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation using FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });