Máscaras de campo

Na API Google Ads, as atualizações são feitas usando uma máscara de campo. A máscara de campo lista todos os campos que você pretende alterar com a atualização e todos os campos especificados que não estão na máscara de campo são ignorados, mesmo se forem enviados ao servidor.

Utilitário FieldMasks

A maneira recomendada de gerar máscaras de campo é usando nossa máscara de campo integrada utilitário (FieldMasks), que permite gerar máscaras de campo a partir de um objeto modificado em vez de criar do zero.

Veja um exemplo de atualização de uma campanha:

my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V17::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

Este exemplo primeiro cria um objeto Campaign ao definir o nome do recurso usando o utilitário ResourceNames, para que a API saiba qual campanha será atualizada.

O exemplo usa FieldMasks::all_set_fields_of() na campanha para produzir automaticamente uma máscara de campo que enumera todos campos definidos. Você pode transmitir a máscara retornada diretamente para a chamada de atualização.

FieldMasks::all_set_fields_of() é um método conveniente para FieldMasks::field_mask(). Ela compara o objeto transmitido com um objeto vazio da mesma classe. Então, no o código acima, também é possível usar

field_mask(Google::Ads::GoogleAds::V17::Resources::Campaign->new({}), $campaign)

em vez de all_set_fields_of($campaign).

Como criar uma máscara manualmente

Para criar uma máscara de campo do zero, primeiro é necessário criar uma Google::Ads::GoogleAds::Common::FieldMask em seguida, faça uma referência de matriz preenchida com os nomes de todos os campos que você pretende alterar e, por fim, atribuir a referência da matriz ao atributo paths.

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

Como atualizar campos de objetos e os subcampos

Os campos de objeto podem ter subcampos (como MaximizeConversions, que tem três: target_cpa_micros, cpc_bid_ceiling_micros e cpc_bid_floor_micros); ou não será possível ter nenhuma (como ManualCpm).

Campos de objeto sem subcampos definidos

Um campo de objeto em Perl é equivalente a um protobuf MESSAGE no cliente bibliotecas em execução no gRPC. Ao atualizar um campo de objeto que não está definido com subcampos, use o utilitário FieldMasks para gerar uma máscara de campo, conforme descritas acima.

Campos de objeto com subcampos definidos

Ao atualizar um campo de objeto definido com subcampos sem definindo qualquer subcampos da mensagem, será necessário adicionar manualmente cada um dos Subcampos de objeto mutable para o FieldMask, semelhante ao exemplo acima que cria uma máscara de campo do zero.

Um exemplo comum é atualizar a estratégia de lances de uma campanha sem definir nenhuma dos campos na nova estratégia de lances. O exemplo abaixo demonstra como atualizar uma campanha para usar MaximizeConversions estratégia de lances sem definir nenhum dos subcampos na estratégia de lances.

Nesse caso, usar os métodos all_set_fields_of() e field_mask() da O utilitário FieldMasks não atinge a meta pretendida.

O exemplo a seguir gera uma máscara de campo que inclui maximize_conversions: No entanto, a API Google Ads não permite esse comportamento, para evitar a limpeza acidental de campos e produz uma FieldMaskError.FIELD_HAS_SUBFIELDS erro.

Aviso :o código a seguir produz um erro.

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

O exemplo a seguir demonstra como atualizar corretamente uma campanha para usar o MaximizeConversions estratégia de lances sem definir nenhum dos subcampos.

Sucesso: o código abaixo atualiza a estratégia de lances da campanha.

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# 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.
# 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
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

Limpar campos

Os campos podem ser apagados explicitamente adicionando-os à máscara de campo, conforme mostrado acima ou definindo o campo com um valor vazio ou indefinido. Por exemplo: suponha que você tenha uma campanha que usa uma estratégia de lances de MaximizeConversions. e que o campo target_cpa_micros seja definido com um valor maior que 0

Sucesso: o código a seguir limpa o campo target_cpa_micros.

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

Os campos com subcampos aninhados só podem ser apagados desmarcando cada um os subcampos individuais, como demonstrado em Campos de objeto com subcampos.