Atualizações usando máscaras de campo

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. Os campos especificados que não estão na máscara são ignorados, mesmo que sejam enviados ao servidor.

Assistente de máscara de campo

A maneira recomendada de gerar máscaras de campo é usar a função auxiliar field_mask incluída no pacote google.api_core. Ele aceita dois objetos protobuf e retorna um objeto de máscara de campo com uma lista paths que contém todos os campos diferentes entre os dois objetos.

Se None for transmitido como o primeiro parâmetro, a lista de máscaras de campo vai conter todos os campos no segundo objeto protobuf que não estão definidos como o valor padrão.

Depois de construído, o objeto de máscara de campo precisa ser copiado para o objeto de operação que será enviado ao servidor.

Atualizar de um novo objeto local

No exemplo a seguir, você cria um objeto CampaignOperation vazio e recupera um objeto Campaign vazio do campo update. Em seguida, modifique esse objeto de campanha e crie uma nova máscara de campo comparando-o com None, que gera uma máscara de campo contendo o campo network_settings.target_search_network modificado:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Retrieve a new campaign object from its update field and set its resource
# name.
campaign = campaign_operation.update
campaign.resource_name = client.get_service("CampaignService").campaign_path(
    customer_id, campaign_id
)

# Mutate the campaign (use direct attribute assignment in proto-plus).
campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
# The field_mask helper is compatible with raw protobuf message instances,
# which you can access using the ._pb attribute.
field_mask = protobuf_helpers.field_mask(None, campaign._pb)

# Copy the field_mask onto the operation's update_mask field.
client.copy_from(campaign_operation.update_mask, field_mask)

Atualizar um recurso

O exemplo a seguir atualiza uma campanha recuperada da API, supondo um resource_name e um customer_id válidos. Com essa estratégia, updated_campaign compartilha todos os campos recuperados em initial_campaign (incluindo o resource_name), e a máscara de campo gerada informa à API que apenas o campo network_settings.target_search_network mudou:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Retrieve an instance of the GoogleAdsService.
googleads_service = client.get_service("GoogleAdsService")

# Search query to retrieve the campaign. Quote string literals in GAQL.
query = f"""
    SELECT
      campaign.network_settings.target_search_network,
      campaign.resource_name
    FROM campaign
    WHERE campaign.resource_name = '{resource_name}'"""

# Submit a query to retrieve a campaign instance.
response = googleads_service.search_stream(
    customer_id=customer_id, query=query
)

# Iterate over results to retrieve the campaign.
initial_campaign = None
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign
        break

if not initial_campaign:
    raise ValueError(f"Campaign '{resource_name}' not found.")

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Set the copied campaign object to a variable for easy reference.
updated_campaign = campaign_operation.update

# Copy the retrieved campaign into the new campaign.
# client.copy_from works with both native protobuf messages and messages
# wrapped by the proto-plus library.
client.copy_from(updated_campaign, initial_campaign)

# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask by comparing initial and updated protobuf objects.
field_mask = protobuf_helpers.field_mask(
    initial_campaign._pb, updated_campaign._pb
)

# Copy the field mask onto the operation's update_mask field.
# Note that the client's copy_from method works with both native messages
# and messages wrapped by proto-plus, including google.protobuf.field_mask_pb2.
client.copy_from(campaign_operation.update_mask, field_mask)

Limpar campos ou definir mensagens vazias

Ao comparar com None, o auxiliar field_mask ignora campos definidos como valores vazios ou padrão. Para limpar explicitamente um campo ou definir um campo de mensagem vazio, adicione o caminho do campo diretamente a campaign_operation.update_mask.paths. Para mais detalhes, consulte Definir objetos de mensagem vazios como campos.