Na API Google Ads, as atualizações são feitas usando uma máscara de campo. A máscara de campo lista todos os campos que você pretende mudar com a atualização, e todos os campos especificados que não estão na máscara de campo são ignorados, mesmo que sejam enviados ao servidor.
FieldMaskUtil
A maneira recomendada de gerar máscaras de campo é usar o utilitário integrado que oculta muitos detalhes específicos e permite gerar máscaras de campo automaticamente monitorando as mudanças feitas nos campos da entidade.
Veja como gerar uma máscara de campo para atualizar uma campanha:
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
Primeiro, o código cria um objeto de campanha vazio e define o nome do recurso para informar à API sobre a campanha que está sendo atualizada.
Este exemplo usa o método client.field_mask.with na campanha para iniciar
o bloco que abrange as atualizações. No final desse bloco, a utilidade
compara o status atual da campanha após o bloco com o status
inicial da campanha antes do bloco e produz automaticamente uma máscara
de campo que enumera os campos alterados. Você pode fornecer essa máscara de campo à operação ao construí-la para a chamada de mutação da seguinte maneira:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Esse método é recomendado quando você está fazendo uma operação complicada e quer ter controle detalhado sobre cada etapa. No entanto, na maioria dos casos, é possível usar o utilitário de biblioteca Ruby mais simples:
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
Esse método cria automaticamente um novo recurso de campanha vazio, constrói
a máscara de campo com base nas mudanças feitas no bloco, cria a operação de
atualização e retorna a operação final com update e update_mask
já preenchidos. Você também pode transmitir uma campanha ao método campaign para
especificar o estado inicial dela. Esse padrão funciona para todos os recursos que aceitam a operação de atualização.
Criar uma máscara manualmente
Para criar uma máscara de campo do zero, sem usar utilitários de biblioteca, primeiro crie um Google::Protobuf::FieldMask, depois faça uma matriz preenchida com os nomes de todos os campos que você pretende mudar e, por fim, atribua a matriz ao campo path da máscara de campo.
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
Atualizar campos de mensagem e subcampos
Os campos MESSAGE podem ter subcampos (como
MaximizeConversions, que tem três:
target_cpa_micros, cpc_bid_ceiling_micros e cpc_bid_floor_micros) ou
não ter nenhum (como ManualCpm).
Campos de mensagem sem subcampos definidos
Ao atualizar um campo MESSAGE que não está definido com subcampos, use o
FieldMaskUtil para gerar uma máscara de campo, conforme apresentado anteriormente.
Campos de mensagem com subcampos definidos
Ao atualizar um campo MESSAGE definido com subcampos sem
definir explicitamente nenhum dos subcampos nessa mensagem, adicione manualmente
cada um dos subcampos MESSAGE mutáveis ao FieldMask, semelhante ao
exemplo anterior que criou uma máscara de campo do zero.
Um exemplo comum é atualizar a estratégia de lances de uma campanha sem definir nenhum dos campos na nova estratégia. O exemplo a seguir
demonstra como atualizar uma campanha para usar a
estratégia de lances MaximizeConversions
sem definir nenhum dos subcampos na estratégia de lances.
Neste exemplo, usar a comparação integrada do FieldMaskUtil não atinge a meta pretendida.
O código a seguir gera uma máscara de campo que inclui maximize_conversions.
No entanto, a API Google Ads não permite esse comportamento para evitar a limpeza acidental de campos e produz um erro FieldMaskError.FIELD_HAS_SUBFIELDS.
# 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],
)
O código a seguir demonstra como atualizar corretamente uma campanha para usar a
estratégia de lances MaximizeConversions sem definir nenhum dos subcampos dela.
# 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],
)
Limpar campos
Alguns campos podem ser limpos explicitamente. Assim como no exemplo anterior, você precisa adicionar esses campos explicitamente à máscara de campo. Por exemplo, suponha que você tenha uma campanha que usa uma estratégia de lances MaximizeConversions e que o campo target_cpa_micros esteja definido com um valor maior que 0.
O código a seguir é executado, mas o maximize_conversions.target_cpa_micros
não é adicionado à máscara de campo. Portanto, nenhuma mudança é feita no campo
target_cpa_micros:
# 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
O código a seguir demonstra como limpar corretamente o campo target_cpa_micros
na estratégia de lances MaximizeConversions.
# 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
O código "incorreto" funciona como esperado para campos definidos como optional na protocol buffers da API Google Ads. No entanto, como o
target_cpa_micros não é um campo optional, o código "incorreto" não atualiza a estratégia de
lances para limpar o campo target_cpa.