Máscaras de campo

En la API de Google Ads, se usa una máscara de campo para proporcionar una lista de los 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 FieldMaskUtil

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

A continuación, se muestra un ejemplo para actualizar una campaña que usa el método FieldMasks.AllSetFieldsOf para generar una máscara de campo que enumera 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, modificarías el código para usar 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 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)
};

Cómo controlar los errores FieldMaskError.FIELD_HAS_SUBFIELDS

En raras ocasiones, es posible que debas establecer un campo sin actualizar ninguno de los subcampos de ese tipo. 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 fallará con un error FieldMaskError.FIELD_HAS_SUBFIELDS. Dado que MaximizeConversions tiene tres campos secundarios, el servidor de la API de Google Ads espera que las máscaras de campo para esos campos estén presentes en la solicitud. Sin embargo, FieldMaskUtil no puede generar máscaras de campo correctamente en esta situación, ya que la solicitud no establece estos campos.

En esos casos, puedes editar manualmente la máscara de campo de la siguiente manera:

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

Cómo borrar campos

La API de Google Ads admite el borrado de algunos valores de campos. Para borrar un campo, debes establecer manualmente la máscara de campo para ese campo. Establecer un campo en su valor predeterminado (como cero para un campo int64) no borrará el campo.

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

Código correcto

En el siguiente código, se borra el campo target_cpa_micros porque establecemos maximize_conversions.target_cpa_micros en la máscara de campo y no establecemos el 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
};

Código incorrecto

El siguiente código no borra el campo target_cpa_micros, ya que establecemos este campo en cero. Tanto FieldMaskUtils como el servidor de la API de Google Ads ignorarán este valor. Además, es posible que tampoco recibas un error en este caso, ya que el servidor ignoró el valor.

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