Actualizaciones con 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.

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

El código primero crea un objeto Campaign vacío y luego establece su nombre de recurso en Informar a la API sobre 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 del bloque que contiene las actualizaciones. Al final de este bloque, la utilidad compara el estado actual de la campaña después del bloqueo con el estado estado de la campaña antes del bloqueo, y automáticamente se genera un campo que enumera los campos modificados. Puedes asignarle esa máscara de campo al cuando se construye para la llamada {i>mutate<i} de la siguiente manera:

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

Se recomienda este método cuando realizas una operación compleja quieren un control preciso de cada paso. Sin embargo, en la mayoría de los casos, puedes usar 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 y crea la máscara de campo según los cambios que realices en el bloque, y muestra la operación final con update y update_mask. ya se completaron. 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.

Crea una máscara de forma manual

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

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

Actualiza los campos de mensaje 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) es posible que no tenga ninguno (por ejemplo, ManualCpm).

Campos de mensaje sin subcampos definidos

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

Campos de mensaje con subcampos definidos

Cuando se actualiza un campo MESSAGE definido con subcampos sin configurar explícitamente cualquiera de los subcampos en ese mensaje, debes agregar cada uno de los subcampos MESSAGE mutables a FieldMask, similar al ejemplo anterior que 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. El siguiente ejemplo muestra cómo actualizar una campaña para usar la Estrategia de ofertas de MaximizeConversions sin configurar ninguno de los subcampos de la estrategia de ofertas.

Para este ejemplo, el uso de la comparación integrada de FieldMaskUtil no lograr 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 borrar campos accidentalmente y produce un FieldMaskError.FIELD_HAS_SUBFIELDS .

Advertencia: El siguiente código produce 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],
)

El siguiente código 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.

# 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 un campaña que usa una estrategia de ofertas MaximizeConversions y que la El campo target_cpa_micros se configura con un valor mayor que 0.

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

Advertencia: Este código produce 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 target_cpa_micros en la estrategia de ofertas MaximizeConversions.

Listo: El siguiente código borra el 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 la sección “incorrecto” el código funciona según lo previsto para los campos que están definidos como optional en protocol buffers de la API de Google Ads. Sin embargo, como el target_cpa_micros es no es un campo optional, el campo "incorrecto" código no actualiza las ofertas para borrar el campo target_cpa.

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