Máscaras de campo

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 quieres cambiar con la actualización y los campos especificados que no están en la máscara de campo se ignoran, incluso si se envían al servidor.

Utilidad FieldMasks

La forma recomendada de generar máscaras de campo es usar nuestra máscara de campo integrada servicio (FieldMasks), que te permite generar máscaras de campo a partir de un objeto modificado, en lugar de compilar desde cero.

A continuación, le mostramos un ejemplo de cómo actualizar una campaña:

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

En este ejemplo, primero se crea un objeto Campaign mediante la configuración del nombre de su recurso con la utilidad ResourceNames, de modo que la API sepa qué campaña se está actualizando.

En el ejemplo, se usa FieldMasks::all_set_fields_of() de la campaña para generar automáticamente una máscara de campo que enumere todas establecer campos. Luego, puedes pasar la máscara devuelta 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 se pasó con un objeto vacío de la misma clase. En la el código anterior, también podrías usar

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

en lugar de all_set_fields_of($campaign).

Crea una máscara de forma manual

Para crear una máscara de campo desde cero, primero debes crear una Google::Ads::GoogleAds::Common::FieldMask Luego, crea una referencia de array completada con los nombres de todos los campos. deseas cambiar y, por último, asigna la referencia de array a la máscara de campo paths.

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 tiene tres: target_cpa_micros, cpc_bid_ceiling_micros y cpc_bid_floor_micros); o no puede tener ninguno (por ejemplo, ManualCpm).

Campos de objeto sin subcampos definidos

Un campo de objeto en Perl es equivalente a un MESSAGE de protobuf en el cliente. que se ejecutan en gRPC. Cuando se actualiza un campo de objeto que no está definido con cualquier subcampo, usa la utilidad FieldMasks para generar una máscara de campo, como descrita anteriormente.

Campos de objeto con subcampos definidos

Cuando se actualiza un campo de objeto definido con subcampos sin especificar explícitamente configurar cualquiera de los subcampos de ese mensaje, debes agregar manualmente cada uno mutable en 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 establecer ninguna de los campos en la nueva estrategia de ofertas. El siguiente ejemplo demuestra cómo actualizar una campaña para utilizar la Estrategia de ofertas de MaximizeConversions sin configurar ninguno de los subcampos de la estrategia de ofertas.

En este caso, usando los métodos all_set_fields_of() y field_mask() de la 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 los campos se borren por accidente y produce un FieldMaskError.FIELD_HAS_SUBFIELDS .

Advertencia: El siguiente código produce un error.

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

El siguiente ejemplo demuestra cómo actualizar correctamente una campaña para usar la Estrategia de ofertas de MaximizeConversions sin configurar ninguno de sus subcampos.

Listo: El siguiente código actualiza correctamente la estrategia de ofertas de la campaña.

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

Borrando campos

Los campos se pueden borrar de forma explícita si los agregas a la máscara de campo, como se muestra a continuación. arriba o configurando 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

Operación exitosa: El siguiente código borra el 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)
  });

Ten en cuenta que los campos con subcampos anidados solo se pueden borrar borrando los en los subcampos individuales, como se muestra en Campos de objeto con subcampos.