Máscaras de campo

En la API de Google Ads, las actualizaciones se realizan con una máscara de campo. La máscara de campo enumera todos los campos que deseas cambiar con la actualización, y se ignorarán todos los campos especificados que no estén en la máscara de campo, incluso si se envían al servidor.

FieldMaskUtil

La forma recomendada de generar máscaras de campo es usar nuestra utilidad integrada de máscaras de campo, 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:

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

Primero, creamos un objeto Campaign vacío. Luego, establecemos su nombre de recurso para que la API sepa exactamente qué campaña estamos actualizando.

En el ejemplo, se usa el método FieldMasks.AllSetFieldsOf en la campaña para generar automáticamente una máscara de campo que enumere todos los campos establecidos. Luego, puedes pasar la máscara devuelta directamente a la llamada de actualización.

A veces, es posible que debas trabajar con un objeto existente y actualizar algunos campos. En esos casos, modificarías el código de la siguiente manera:

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

Para crear una máscara de campo desde cero, primero debes crear un objeto FieldMask, luego crear un array completado con los nombres de todos los campos que deseas cambiar y, por último, agregar el contenido del array al campo Path de la máscara de campo.

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

Actualiza los campos de mensajes y sus subcampos

Los campos MESSAGE pueden tener subcampos (como MaximizeConversions, que tiene tres: target_cpa_micros, cpc_bid_ceiling_micros y cpc_bid_floor_micros) o no tener ninguno (como ManualCpm).

Campos de mensajes sin subcampos definidos

Cuando actualices un campo MESSAGE que no esté definido con ningún subcampo, usa FieldMasks para generar una máscara de campo, como se describió anteriormente.

Campos de mensajes con subcampos definidos

Cuando actualices un campo MESSAGE que se define con subcampos sin configurar explícitamente ninguno de los subcampos en ese mensaje, debes agregar manualmente cada uno de los subcampos MESSAGE mutables al FieldMask, de manera similar al ejemplo anterior que crea una máscara de campo desde cero.

Un ejemplo común es actualizar la estrategia de ofertas de una campaña sin configurar ninguno de los campos de la nueva estrategia de ofertas. En el siguiente ejemplo, se muestra cómo actualizar una campaña para que use la estrategia de ofertas MaximizeConversions sin configurar ninguno de los subcampos de la estrategia de ofertas.

En este caso, usar los métodos AllSetFieldsOf() y FromChanges() de FieldMasks no logra el objetivo previsto.

En el siguiente ejemplo, se genera una máscara de campo que incluye maximize_conversions. Sin embargo, la API de Google Ads no permite este comportamiento para evitar que se borren campos accidentalmente y produce un error FieldMaskError.FIELD_HAS_SUBFIELDS.

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

En el siguiente ejemplo, se muestra cómo actualizar correctamente una campaña para usar la estrategia de ofertas MaximizeConversions sin establecer ninguno de sus campos secundarios.

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

Cómo borrar campos

Algunos campos se pueden borrar de forma explícita. De manera similar al ejemplo anterior, debes agregar estos campos de forma explícita a la máscara de campo. Por ejemplo, supongamos que tienes una campaña que utiliza una estrategia de ofertas MaximizeConversions y que el campo target_cpa_micros está configurado con un valor mayor que 0.

El siguiente código se ejecuta, pero maximize_conversions.target_cpa_micros no se agregará a la máscara de campo, por lo que no se realizarán cambios en el campo target_cpa_micros:

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

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

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

Ten en cuenta que el ejemplo "incorrecto" anterior funciona según lo previsto para los campos que se definen como optional en la API de Google Ads protocol buffers. Sin embargo, dado que target_cpa_micros no es un campo de optional, el ejemplo "incorrecto" no actualiza la estrategia de ofertas para borrar el campo target_cpa.