Maschere dei campi

Nell'API Google Ads, una maschera del campo viene utilizzata per fornire un elenco di campi che una richiesta API deve aggiornare. Qualsiasi campo non specificato nella maschera del campo viene ignorato, anche se inviato al server.

Classe FieldMasks

Il modo consigliato per generare maschere di campo nella libreria client .NET è utilizzare la classe di utilità FieldMasks integrata, che consente di generare maschere di campo da un oggetto modificato anziché crearle da zero.

Ecco un esempio di aggiornamento di una campagna che utilizza il metodo FieldMasks.AllSetFieldsOf per produrre una maschera di campo che enumera tutti i campi impostati. Puoi quindi passare la maschera di campo generata direttamente alla chiamata di aggiornamento:

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

A volte, potrebbe essere necessario lavorare con un oggetto esistente e aggiornare alcuni campi. In questi casi, utilizza invece il metodo FieldMasks.FromChanges. Questo metodo genera una maschera del campo che rappresenta la differenza tra due oggetti:

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

Gestisci gli errori FieldMaskError.FIELD_HAS_SUBFIELDS

In rari casi, potrebbe essere necessario impostare un campo del messaggio senza aggiornare nessuno dei relativi sottocampi. Considera l'esempio seguente:

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

Questa chiamata API non va a buon fine e restituisce un errore FieldMaskError.FIELD_HAS_SUBFIELDS. Poiché MaximizeConversions ha dei campi secondari, il server API Google Ads prevede che le maschere dei campi per i campi secondari modificabili siano presenti nella richiesta. Tuttavia, FieldMasks non può generare automaticamente maschere di campi secondari in questa situazione perché la richiesta non imposta alcun campo secondario.

In questi casi, puoi aggiungere manualmente i percorsi a fieldMask.Paths (che è 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
};

Cancella campi

L'API Google Ads supporta l'eliminazione di alcuni valori dei campi. Per cancellare un campo, devi includerlo manualmente nella maschera del campo lasciandolo non impostato nell'oggetto risorsa. L'impostazione di un campo sul valore predefinito (ad esempio 0 per un campo int64) non comporta la cancellazione del campo.

Il seguente esempio di codice mostra come cancellare il campo target_cpa_micros di una strategia di offerta MaximizeConversions:

Codice corretto

Il seguente codice cancella il campo target_cpa_micros perché aggiunge maximize_conversions.target_cpa_micros alla maschera del campo senza impostare la proprietà 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
};

Codice errato

Il seguente codice non cancella il campo target_cpa_micros perché lo imposta su 0. Sia l'utilità FieldMasks sia il server dell'API Google Ads ignorano questo valore quando TargetCpaMicros è 0 o quando il percorso viene omesso dalla maschera e il server non restituisce un errore:

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