En la API de Google Ads, las actualizaciones se realizan mediante una máscara de campo. La máscara de campo enumera todos los campos que deseas cambiar con la actualización y se ignorará cualquier campo especificado que no esté en la máscara de campo, incluso si se envía al servidor.
Utilidad FieldMasks
La forma recomendada de generar máscaras de campo es usar nuestra utilidad integrada de máscara de campo (FieldMasks), que te permite generar máscaras de campo a partir de un objeto modificado en lugar de compilarlas desde cero.
A continuación, presentamos un ejemplo para actualizar una campaña:
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
status => PAUSED,
networkSettings =>
Google::Ads::GoogleAds::V16::Resources::NetworkSettings->new({
targetSearchNetwork => "false"
})
});
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
En este ejemplo, primero se crea un objeto Campaign mediante la configuración de su nombre de recurso con la utilidad ResourceNames, de modo que la API sepa qué campaña se está actualizando.
En el ejemplo, se usa el método FieldMasks::all_set_fields_of() en la campaña para producir automáticamente una máscara de campo que enumera todos los campos establecidos. Luego, puedes pasar la máscara que se muestra directamente a la llamada de actualización.
FieldMasks::all_set_fields_of() es un método de conveniencia para FieldMasks::field_mask().
Compara el objeto que pasaste con un objeto vacío de la misma clase. En el código anterior, también puedes usar
field_mask(Google::Ads::GoogleAds::V16::Resources::Campaign->new({}), $campaign)
en lugar de all_set_fields_of($campaign).
Crea una máscara manualmente
Para crear una máscara de campo desde cero, primero debes crear un objeto Google::Ads::GoogleAds::Common::FieldMask, luego hacer una referencia de array propagada con los nombres de todos los campos que deseas cambiar y, por último, asignar la referencia de array al campo paths de la máscara de campo.
my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
paths => ["status", "name"]
});
Actualiza los campos de objetos y sus subcampos
Los campos de objetos pueden tener subcampos (como MaximizeConversions, que tiene tres: target_cpa_micros, cpc_bid_ceiling_micros y cpc_bid_floor_micros), o no pueden tener ninguno (como ManualCpm).
Campos de objeto sin subcampos definidos
Un campo de objeto en Perl es equivalente a un protobuf MESSAGE en bibliotecas cliente que se ejecutan en gRPC. Cuando actualices un campo de objeto que no esté definido con ningún subcampo, usa la utilidad FieldMasks para generar una máscara de campo, como se describió anteriormente.
Campos de objeto con subcampos definidos
Cuando actualizas un campo de objeto definido con subcampos sin configurar explícitamente ninguno de los subcampos de ese mensaje, debes agregar manualmente cada uno de los subcampos del objeto mutable a FieldMask, 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 estrategia de oferta nueva. 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, el uso de los métodos all_set_fields_of() y field_mask() de la utilidad FieldMasks no logra el objetivo deseado.
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 por accidente y se produzca un
error FieldMaskError.FIELD_HAS_SUBFIELDS.
# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions =>
Google::Ads::GoogleAds::V16::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::V16::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]
});
En el siguiente ejemplo, se muestra cómo actualizar correctamente una campaña para usar la estrategia de ofertas MaximizeConversions sin configurar ninguno de sus subcampos.
# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => $field_mask
});
Borrando campos
Para borrar los campos de forma explícita, agrégalos a la máscara de campo como se muestra más arriba o configura el campo en un valor vacío o indefinido. Por ejemplo, supongamos que tienes una campaña que utiliza la estrategia de ofertas MaximizeConversions y que el campo target_cpa_micros está configurado con un valor mayor que 0.
# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
Ten en cuenta que los campos con subcampos anidados solo se pueden borrar si borras cada uno de los subcampos individuales, como se muestra en Campos de objetos con subcampos definidos.