Maschere di campo

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

Classe FieldMaskUtil

Il modo consigliato per generare maschere di campo è utilizzare la classe FieldMaskUtil 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 del 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, dovrai modificare il codice per utilizzare il metodo FieldMasks.FromChanges. Questo metodo genera una maschera di campo che rappresenta la differenza tra due oggetti.

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

Come gestire gli errori FieldMaskError.FIELD_HAS_SUBFIELDS

In rari casi, potrebbe essere necessario impostare un campo senza aggiornare nessuno dei sottocampi di quel tipo. 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 andrà a buon fine e verrà restituito un errore FieldMaskError.FIELD_HAS_SUBFIELDS. Poiché MaximizeConversions ha tre sottocampi, il server API Google Ads prevede che le maschere dei campi per questi campi siano presenti nella richiesta. Tuttavia, FieldMaskUtil non può generare maschere di campo correttamente in questa situazione, poiché la richiesta non imposta questi campi.

In questi casi, puoi modificare manualmente la maschera del campo nel seguente modo:

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

Come cancellare i campi

L'API Google Ads supporta la cancellazione di alcuni valori dei campi. Per cancellare un campo, devi impostare manualmente la maschera del campo. L'impostazione di un campo sul valore predefinito (ad esempio zero per un campo int64) non comporta la cancellazione del campo.

Il seguente esempio di codice mostra come cancellare il campo target_cpa_micros della strategia di offerta MaximizeConversions.

Codice corretto

Il seguente codice cancella il campo target_cpa_micros perché stiamo impostando maximize_conversions.target_cpa_micros nella maschera del campo e non stiamo impostando il campo 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 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
};

Codice errato

Il seguente codice non cancella il campo target_cpa_micros, poiché lo impostiamo su zero. Sia FieldMaskUtils che il server dell'API Google Ads ignoreranno questo valore. Inoltre, in questo caso potresti non ricevere un errore, poiché il valore è stato ignorato dal server.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt 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 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 });