Máscaras de campo

En la API de Google Ads, se usa una máscara de campo para proporcionar una lista de campos que debe actualizar una solicitud a la API. Se ignorará cualquier campo que no se especifique en la máscara de campo, incluso si se envía al servidor.

Clase FieldMasks

La forma recomendada de generar máscaras de campo en la biblioteca cliente de .NET es usar la clase de utilidad FieldMasks integrada, que te permite generar máscaras de campo a partir de un objeto modificado en lugar de crearlas desde cero.

Este es un ejemplo de cómo actualizar una campaña que usa el método FieldMasks.AllSetFieldsOf para producir una máscara de campo que enumere todos los campos establecidos. Luego, puedes pasar la máscara de campo generada directamente a la llamada de actualización:

// 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 veces, es posible que debas trabajar con un objeto existente y actualizar algunos campos. En esos casos, usa el método FieldMasks.FromChanges. Este método genera una máscara de campo que representa la diferencia entre dos objetos:

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

Cómo controlar los errores FieldMaskError.FIELD_HAS_SUBFIELDS

En raras ocasiones, es posible que debas establecer un campo de mensaje sin actualizar ninguno de sus subcampos. Consulta el siguiente ejemplo:

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

Esta llamada a la API falla con un error FieldMaskError.FIELD_HAS_SUBFIELDS. Como MaximizeConversions tiene campos secundarios, el servidor de la API de Google Ads espera que las máscaras de campo para los campos secundarios mutables estén presentes en la solicitud. Sin embargo, FieldMasks no puede generar máscaras de subcampos automáticamente en esta situación porque la solicitud no establece ningún subcampo.

En esos casos, puedes agregar rutas de acceso de forma manual a fieldMask.Paths (que es 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
};

Borrar campos

La API de Google Ads admite borrar algunos valores de campo. Para borrar un campo, debes incluirlo de forma manual en la máscara de campo y dejarlo sin configurar en el objeto de recurso. Establecer un campo en su valor predeterminado (como 0 para un campo int64) no borra el campo.

En el siguiente ejemplo de código, se muestra cómo borrar el campo target_cpa_micros de una estrategia de ofertas MaximizeConversions:

Código correcto

En el siguiente código, se borra el campo target_cpa_micros porque se agrega maximize_conversions.target_cpa_micros a la máscara de campo sin configurar la propiedad 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
};

Código incorrecto

El siguiente código no borra el campo target_cpa_micros, porque establece el campo en 0. Tanto la utilidad FieldMasks como el servidor de la API de Google Ads ignoran este valor cuando TargetCpaMicros es 0 o cuando se omite la ruta de acceso de la máscara, y el servidor no devuelve un error:

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