Masques de champ

<ph type="x-smartling-placeholder">

</ph> Avertissement:À partir de la version 19.0.0, le La bibliothèque cliente de l'API Google Ads pour .NET n'est plus compatible avec .NET 5.0. Pour garantir un fonctionnement sans faille, nous vous recommandons mettre à niveau votre version .NET avant la fin de l'année 2024.

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:

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

Tout d'abord, nous créons un objet Campaign vide. Ensuite, nous définissons son nom de ressource afin que l'API sache exactement quelle campagne nous mettons à jour.

L'exemple utilise la méthode FieldMasks.AllSetFieldsOf sur la campagne génèrent automatiquement un masque de champ énumérant tous les champs définis. Vous pouvez ensuite transmettre directement le masque renvoyé à l'appel de mise à jour.

Parfois, vous devrez peut-être utiliser un objet existant et mettre à jour quelques champs. Dans ce cas, vous devez modifier le code comme suit:

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off 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)
};

Pour créer un masque de champ à partir de zéro, vous devez d'abord créer un FieldMask puis créez un tableau contenant les noms de tous les champs pour le modifier, puis ajoutez le contenu du tableau au champ Path du masque de champ.

FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });

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 FieldMasks 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 FromChanges() de 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 ne permet pas ce comportement pour éviter d'effacer accidentellement des champs FieldMaskError.FIELD_HAS_SUBFIELDS .

Avertissement :Le code suivant génère une erreur.

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

// 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 = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// 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 = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { 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.

Opération effectuée :le code ci-dessous met à jour la stratégie d'enchères de la campagne.

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

// 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.
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 here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

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

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:

Avertissement :Ce code ne génère pas d'erreur, mais la target_cpa_micros de la stratégie d'enchères MaximizeConversions ne sera pas effacée.

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

// 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 = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// 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 = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

L'exemple 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.

// 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 will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

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

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.

Important :Si vous avez l'intention d'effacer un champ, le moyen le plus sûr d'y parvenir est l'objectif est d'ajouter explicitement ce champ au masque de champ.