Actualizaciones con máscaras de campo

En la API de Google Ads, las actualizaciones se realizan con una máscara de campo. En la máscara de campo, se enumeran todos los campos que deseas cambiar con la actualización, y se ignoran los campos especificados que no se encuentran en la máscara de campo, incluso si se envían al servidor.

FieldMaskUtil

La forma recomendada de generar máscaras de campo es usar nuestra utilidad integrada, que oculta muchos de los detalles específicos y te permite generar máscaras de campo automáticamente a través de la supervisión de los cambios que realices en los campos de la entidad.

A continuación, te mostramos cómo puedes generar una máscara de campo para actualizar una campaña:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Primero, el código crea un objeto Campaign vacío y, luego, establece su nombre de recurso para informar a la API de la campaña que se está actualizando.

En este ejemplo, se usa el método client.field_mask.with en la campaña para comenzar el bloque que abarca las actualizaciones. Al final de este bloque, la utilidad compara el estado actual de la campaña después del bloque con el estado inicial de la campaña antes del bloque y genera automáticamente una máscara de campo que enumera los campos modificados. Puedes proporcionar esa máscara de campo a la operación cuando la construyas para la llamada de mutación de la siguiente manera:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Este método se recomienda cuando realizas una operación complicada y deseas tener un control preciso sobre cada paso. Sin embargo, en la mayoría de los casos, puedes usar la utilidad de biblioteca de Ruby más simple:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Este método crea automáticamente un nuevo recurso de campaña vacío, construye la máscara de campo según los cambios que realices dentro del bloque, compila la operación de actualización y muestra la operación final con update y update_mask ya propagados. También puedes pasar una campaña al método campaign para especificar el estado inicial de la campaña. Este patrón funciona para todos los recursos que admiten la operación de actualización.

Cómo crear una máscara de forma manual

Para crear una máscara de campo desde cero, sin usar ninguna utilidad de biblioteca, primero debes crear un Google::Protobuf::FieldMask, luego, crear un array propagado con los nombres de todos los campos que deseas cambiar y, por último, asignar el array al campo path de la máscara de campo.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

Actualiza los campos de mensajes y sus subcampos

Los campos MESSAGE pueden tener subcampos (como MaximizeConversions, que tiene tres: target_cpa_micros, cpc_bid_ceiling_micros y cpc_bid_floor_micros) o no tener ninguno (como ManualCpm).

Campos de mensajes sin subcampos definidos

Cuando actualices un campo MESSAGE que no esté definido con ningún subcampo, usa FieldMaskUtil para generar una máscara de campo, como se presentó antes.

Campos de mensajes con subcampos definidos

Cuando actualizas un campo MESSAGE que se define con subcampos sin configurar explícitamente ninguno de los subcampos en ese mensaje, debes agregar manualmente cada uno de los subcampos MESSAGE mutables a FieldMask, de manera similar al ejemplo anterior en el que se creó 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 nueva estrategia de ofertas. 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 ejemplo, usar la comparación integrada de FieldMaskUtil no logra el objetivo previsto.

El siguiente código 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 genera un error FieldMaskError.FIELD_HAS_SUBFIELDS.

Advertencia: El siguiente código genera un error.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

En el siguiente código, se muestra cómo actualizar correctamente una campaña para usar la estrategia de ofertas MaximizeConversions sin configurar ninguno de sus subcampos.

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

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Cómo borrar campos

Algunos campos se pueden borrar de forma explícita. Al igual que en el ejemplo anterior, debes agregar estos campos de forma explícita a la máscara de campos. Por ejemplo, supongamos que tienes una campaña que utiliza una estrategia de ofertas MaximizeConversions y que el campo target_cpa_micros está configurado con un valor superior a 0.

Se ejecuta el siguiente código; sin embargo, maximize_conversions.target_cpa_micros no se agregará a la máscara de campo, por lo que no se realizarán cambios en el campo target_cpa_micros:

Advertencia: Este código genera un error.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

En el siguiente código, se muestra cómo borrar correctamente el campo target_cpa_micros en la estrategia de ofertas MaximizeConversions.

Éxito: El siguiente código borra target_cpa_micros.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Ten en cuenta que el código "incorrecto" funciona según lo previsto para los campos que se definen como optional en la protocol buffers de la API de Google Ads. Sin embargo, como target_cpa_micros no es un campo optional, el código "incorrecto" no actualiza la estrategia de ofertas para borrar el campo target_cpa.

Punto clave: Si tu intención es borrar un campo, la forma más segura es agregarlo de forma explícita a la máscara de campos.