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 ignoran los campos especificados que no están en la máscara de campo, incluso si se envían al servidor.
Utilidad FieldMasks
La forma recomendada de generar máscaras de campo es usar nuestra utilidad integrada de máscaras de campo (FieldMasks), que te permite generar máscaras de campo
a partir de un objeto modificado en lugar de crearlas desde cero.
Este es un ejemplo de cómo actualizar una campaña:
use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);
my $campaign =
Google::Ads::GoogleAds::V26::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
status => "PAUSED",
networkSettings =>
Google::Ads::GoogleAds::V26::Resources::NetworkSettings
->new({
targetSearchNetwork => "false",
}),
});
my $campaign_operation =
Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
->new({
update => $campaign,
updateMask => all_set_fields_of($campaign),
});
En este ejemplo, primero se crea un objeto Campaign estableciendo su nombre de recurso con la utilidad ResourceNames para 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 enumere 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 podrías usar lo siguiente:
field_mask(
Google::Ads::GoogleAds::V26::Resources::Campaign->new({}),
$campaign
)
en lugar de all_set_fields_of($campaign).
Cómo crear una máscara de forma manual
Para crear una máscara de campo desde cero, primero crea un objeto
Google::Ads::GoogleAds::Common::FieldMask y, luego,
crea una referencia de array propagada con los nombres de todos los campos que quieras
cambiar y, por último, asigna 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 objeto pueden tener subcampos (como
MaximizeConversions, que incluye subcampos como
target_cpa_micros) o no tener ninguno (como
ManualCpm).
Campos de objetos sin subcampos definidos
Un campo de objeto en Perl equivale a un MESSAGE de protobuf en las 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 describe en la sección anterior.
Campos de objetos con subcampos definidos
Cuando actualizas un campo de objeto que se define con subcampos sin configurar de forma explícita ninguno de los subcampos en ese mensaje, debes agregar de forma manual cada uno de los subcampos de objeto mutables a 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 establecer ninguno de los campos de la nueva estrategia de ofertas. En el siguiente ejemplo, se muestra cómo actualizar una campaña para usar la estrategia de ofertas MaximizeConversions sin establecer ninguno de los campos secundarios de la estrategia de ofertas.
En este caso, usar los métodos all_set_fields_of() y field_mask() de la utilidad 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 de forma accidental y produce un error FieldMaskError.FIELD_HAS_SUBFIELDS.
# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign =
Google::Ads::GoogleAds::V26::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions =>
Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
->new(),
});
# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask includes 'maximize_conversions',
# which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
->new({
update => $campaign,
updateMask => all_set_fields_of($campaign),
});
# Sends the operation in a mutate request that results 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 campos secundarios.
# Creates a campaign with the proper resource name.
my $campaign =
Google::Ads::GoogleAds::V26::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
});
# Creates a field mask from the existing campaign and adds the mutable subfield
# on the MaximizeConversions bidding strategy to the field mask. Because this
# field is included in the field mask but excluded from the campaign object,
# the Google Ads API sets 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V26::Services::CampaignService::CampaignOperation
->new({
update => $campaign,
updateMask => $field_mask,
});
Borrar campos
Los campos se pueden borrar de forma explícita agregándolos a la máscara de campo, como se muestra en
el ejemplo anterior, o configurando el campo con un valor vacío o indefinido.
Por ejemplo, supongamos que tienes una campaña que utiliza una estrategia de ofertas MaximizeConversions y que el campo target_cpa_micros se establece con un valor superior a 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::V26::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions =>
Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
->new({
targetCpaMicros => 0,
}),
});
# Constructs an operation using all_set_fields_of to derive the update mask,
# which includes 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
Google::Ads::GoogleAds::V26::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 se borra cada uno de los subcampos individuales, como se muestra en Campos de objeto con subcampos definidos.