Máscaras de campo

Na API Google Ads, uma máscara de campo é usada para fornecer uma lista de campos que uma solicitação de API precisa atualizar. Qualquer campo que não esteja especificado na máscara de campo é ignorado, mesmo que seja enviado ao servidor.

Classe FieldMasks

A maneira recomendada de gerar máscaras de campo na biblioteca de cliente .NET é usar a classe de utilitário FieldMasks integrada, que permite gerar máscaras de campo com base em um objeto modificado, em vez de criá-las do zero.

Veja um exemplo de atualização de uma campanha que usa o método FieldMasks.AllSetFieldsOf para produzir uma máscara de campo que enumera todos os campos definidos. Em seguida, transmita a máscara de campo gerada diretamente para a chamada de atualização:

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

Às vezes, é necessário trabalhar com um objeto existente e atualizar alguns campos. Nesses casos, use o método FieldMasks.FromChanges. Esse método gera uma máscara de campo que representa a diferença entre dois 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)
};

Tratar erros FieldMaskError.FIELD_HAS_SUBFIELDS

Em raras ocasiões, talvez seja necessário definir um campo de mensagem sem atualizar nenhum dos subcampos. Veja o exemplo a seguir:

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

Essa chamada de API falha com um erro FieldMaskError.FIELD_HAS_SUBFIELDS. Como MaximizeConversions tem subcampos, o servidor de API Google Ads espera que as máscaras de campo para os subcampos mutáveis estejam presentes na solicitação. No entanto, o FieldMasks não pode gerar máscaras de subcampo automaticamente nessa situação porque a solicitação não define nenhum subcampo.

Nesses casos, é possível adicionar manualmente caminhos para fieldMask.Paths (que é um 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
};

Limpar campos

A API Google Ads permite limpar alguns valores de campo. Para limpar um campo, é necessário incluí-lo manualmente na máscara de campo e deixar o campo sem definição no objeto de recurso. Definir um campo com o valor padrão (como 0 para um campo int64) não limpa o campo.

O exemplo de código a seguir mostra como limpar o campo target_cpa_micros de uma estratégia de lances MaximizeConversions:

Código correto

O código a seguir limpa o campo target_cpa_micros porque adiciona maximize_conversions.target_cpa_micros à máscara de campo sem definir a propriedade 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 incorreto

O código a seguir não limpa o campo target_cpa_micros porque define o campo como 0. O utilitário FieldMasks e o servidor da API Google Ads ignoram esse valor quando TargetCpaMicros é 0 ou quando o caminho é omitido da máscara, e o servidor não retorna um erro:

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